javax.media.protocol
Class DataSource

java.lang.Object
  |
  +--javax.media.protocol.DataSource

Direct Known Subclasses:

PullBufferDataSource, PullDataSource, PushBufferDataSource, PushDataSource

public abstract class DataSource

extends java.lang.Object

implements Controls, Duration

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.

DataSource Properties

A DataSource may implement the following few well-defined interfaces:
Positionable: if the DataSource can be positioned.
RateConfigureable: if the DataSource supports different playback rates.
SourceCloneable: if the DataSource can be cloned.
CaptureDevice: if the DataSource is a capture device.

See Also:

Manager, Positionable, RateConfigureable, CaptureDevice, SourceCloneable

Fields inherited from interface javax.media.Duration

DURATION_UNBOUNDED, DURATION_UNKNOWN

Constructor Summary

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

DataSource(MediaLocator source)
Construct a DataSource from a MediaLocator.

Method Summary

abstract void	connect() Open a connection to the source described by the MediaLocator.
abstract void	disconnect() Close the connection to the source described by the locator.
abstract java.lang.String	getContentType() Get a string that describes the content-type of the media that the source is providing.
MediaLocator	getLocator() Get the MediaLocator that describes this source.
protected void	initCheck() Check to see if this connection has been initialized with a MediaLocator.
void	setLocator(MediaLocator source) Set the connection source for this DataSource.
abstract void	start() Initiate data-transfer.
abstract void	stop() Stop the data-transfer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataSource

public DataSource()

A no-argument constructor required by pre 1.1 implementations so that this class can be instantiated by calling Class.newInstance.

DataSource

public DataSource(MediaLocator source)

Construct a DataSource from a MediaLocator. This method should be overloaded by subclasses; the default implementation just keeps track of the MediaLocator.

Parameters:

source - The MediaLocator that describes the DataSource.

Method Detail

setLocator

public void setLocator(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.

Parameters:

source - The MediaLocator that describes the media source.

getLocator

public MediaLocator getLocator()

Get the MediaLocator that describes this source. Returns null if the locator hasn't been set. (Very unlikely.)

Returns:

The MediaLocator for this source.

initCheck

protected void initCheck()

Check to see if this connection has been initialized with a MediaLocator. If the connection hasn't been initialized, initCheck throws an UninitializedError. Most methods should call initCheck on entry.

getContentType

public abstract java.lang.String getContentType()

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.

Returns:

The name that describes the media content.

connect

public abstract void connect()
                      throws java.io.IOException

Open a connection to the source described by the MediaLocator.

The connect method initiates communication with the source.

Throws:

java.io.IOException - Thrown if there are IO problems when connect is called.

disconnect

public abstract void disconnect()

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.

start

public abstract void start()
                    throws java.io.IOException

Initiate data-transfer. The start method must be called before data is available. (You must call connect before calling start.)

Throws:

java.io.IOException - Thrown if there are IO problems with the source when start is called.

stop

public abstract void stop()
                   throws java.io.IOException

Stop the data-transfer. If the source has not been connected and started, stop does nothing.