javax.media.protocol.DataSource Maven / Gradle / Ivy

/**
This is not an official specification document, and usage is restricted.


NOTICE





(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.


Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.  

Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example, 
this file and any files generated from it may be used to generate other documentation, 
such as a unified set of documents of API signatures for a platform 
that includes technologies expressed as Java APIs. 
This file may also be used to produce "compilation stubs," 
which allow applications to be compiled and validated for such platforms. 
By contrast, no permission is given for you to incorporate this file, 
in whole or in part, in an implementation of a Java specification.

Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.  
In the event of a discrepency between this work and the JSR 927 specification, 
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/



  


package javax.media.protocol;

import javax.media.*;
import java.net.*;

import javax.media.Duration;
import java.io.IOException;

/** 
 * A DataSource is an abstraction for media protocol-handlers.
 * DataSource manages the life-cycle of the media source
 * by providing a simple connection protocol.
 *
 * 
Source Controls
 * 
 * A DataSource might support an operation
 * that is not part of the DataSource
 * class definition. For example a source could support
 * positioning its media to a particular time.
 * Some operations are dependent on the data stream that the
 * source is managing, and support cannot be determined
 * until after the source has been connected.
 * 
 *
 * To obtain all of the objects that provide control
 * over a DataSource, use getControls
 * which returns an array of Object
 * To determine if a particular kind of control
 * is available and obtain the object that implements
 * it, use getControl which takes
 * the name of the Class or Interface that of the
 * desired control.
 *
 *
 * @see Manager
 * @see DefaultPlayerFactory
 * @see Positionable
 * @see RateConfigureable
 *
 * @version 1.17, 07/09/19
 */
public abstract class DataSource implements Controls, javax.media.Duration
{

    /** 
     * A no-argument constructor required by pre 1.1 implementations
     * so that this class can be instantiated by
     * calling Class.newInstance.
     *
     */
    public DataSource() { }

    /** 
     * Construct a DataSource from a MediaLocator.
     * This method should be overloaded by subclasses;
     * the default implementation just keeps track of
     * the MediaLocator.
     *
     *
     * @param source The MediaLocator that describes
     * the DataSource.
     */
    public DataSource(MediaLocator source) { }

    /** 
     * Set the connection source for this DataSource.
     * This method should only be called once; an error is thrown if 
     * the locator has already been set.
     *
     * @param source The MediaLocator that describes the
     * media source.
     */
    public void setLocator(MediaLocator source) { }

    /** 
     * Get the MediaLocator that describes this source.
     * Returns null if the locator hasn't been set. 
     * (Very unlikely.)
     * @return The MediaLocator for this source.
     */
    public MediaLocator getLocator() {
        return null;
    }

    /** 
     * Check to see if this connection has been
     * initialized with a MediaLocator.
     * If the connection hasn't been initialized,
     * initCheck throws an Error.
     * Most methods should call initCheck on entry.
     *
     * @throws java.lang.Error if the connection has not been initialized.
     */
    protected void initCheck() { }

    /** 
     * Get a string that describes the content-type of the media
     * that the source is providing.
     * 

     * It is an error to call getContentType if the source is
     * not connected.
     *
     * @return The name that describes the media content.
     */
    public abstract String getContentType();

    /** 
     * Open a connection to the source described by
     * the MediaLocator.
     * 

     *
     * The connect method initiates communication with the source.
     *
     * @exception IOException Thrown if there are IO problems
     * when connect is called.
     */
    public abstract void connect() throws IOException;

    /** 
     * Close the connection to the source described by the locator.
     * 
     * The disconnect method frees resources used to maintain a
     * connection to the source.
     * If no resources are in use, disconnect is ignored.
     * If stop hasn't already been called,
     * calling disconnect implies a stop.
     *
     */
    public abstract void disconnect();

    /** 
     * Initiate data-transfer. The start method must be
     * called before data is available.
     *(You must call connect before calling start.)
     *
     * @exception IOException Thrown if there are IO problems with the source
     * when start is called.
     */
    public abstract void start() throws IOException;

    /** 
     * Stop the data-transfer.
     * If the source has not been connected and started,
     * stop does nothing.
     */
    public abstract void stop() throws IOException;
}