javax.microedition.media.protocol

Class DataSource

java.lang.Object

javax.microedition.media.protocol.DataSource

All Implemented Interfaces:

Controllable

public abstract class DataSource
extends java.lang.Object
implements Controllable

A DataSource is an abstraction for media protocol-handlers. It hides the details of how the data is read from source--whether the data is coming from a file, streaming server or proprietary delivery mechanism. It provides the methods for a Player to access the input data.

An application-defined protocol can be implemented with a custom DataSource. A Player can then be created for playing back the media from the custom DataSource using the Manager.createPlayer method.

There are a few reasons why one would choose to implement a DataSource as opposed to an InputStream for a custom protocol:

• DataSource/SourceStream provides the random seeking API that is not supported by an InputStream. i.e., if the custom protocol requires random seeking capabilities, a custom DataSource can be used.
• DataSource/SourceStream supports the concept of transfer size that is more suited for frame-delimited data, e.g. video.

A DataSource contains a set of SourceStreams. Each SourceStream represents one elementary data stream of the source. In the most common case, a DataSource only provides one SourceStream. A DataSource may provide multiple SourceStreams if it encapsulates multiple elementary data streams.

Each of the SourceStreams provides the methods to allow a Player to read data for processing.

DataSource manages the life-cycle of the media source by providing a simple connection protocol.

DataSource implements Controllable which provides extra controls via some type-specific Control interfaces. getControl and getControls can only be called when the DataSource is connected. An IllegalStateException will be thrown otherwise.

See Also:

Manager, SourceStream, ContentDescriptor

Constructor Summary

Constructors

Constructor and Description
DataSource(java.lang.String locator) Construct a DataSource from a locator.

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	connect() Open a connection to the source described by the locator and initiate communication.
abstract void	disconnect() Close the connection to the source described by the locator and free resources used to maintain the connection.
abstract java.lang.String	getContentType() Get a string that describes the content-type of the media that the source is providing.
abstract Control	getControl(java.lang.String controlType) Obtain the object that implements the specified Control interface.
abstract Control[]	getControls() Obtain the collection of Controls from the object that implements this interface.
java.lang.String	getLocator() Get the locator that describes this source.
abstract SourceStream[]	getStreams() Get the collection of streams that this source manages.
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(java.lang.String locator)

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

Parameters:

locator - The locator that describes the DataSource.

Method Detail

getLocator

public java.lang.String getLocator()

Get the locator that describes this source. Returns null if the locator hasn't been set.

Returns:

The locator for this source.

getContentType

public abstract java.lang.String getContentType()

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

Returns:

The name that describes the media content. Returns null if the content is unknown.

Throws:

java.lang.IllegalStateException - Thrown if the source is not connected.

connect

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

Open a connection to the source described by the locator and initiate communication.

Throws:

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

java.lang.SecurityException - Thrown if the caller does not have security permission to call connect.

disconnect

public abstract void disconnect()

Close the connection to the source described by the locator and free resources used to maintain the connection.

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 for reading.

Throws:

java.lang.IllegalStateException - Thrown if the DataSource is not connected.

java.io.IOException - Thrown if the DataSource cannot be started due to some IO problems.

java.lang.SecurityException - Thrown if the caller does not have security permission to call start.

stop

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

Stop the data-transfer. If the DataSource has not been connected and started, stop is ignored.

Throws:

java.io.IOException - Thrown if the DataSource cannot be stopped due to some IO problems.

getStreams

public abstract SourceStream[] getStreams()

Get the collection of streams that this source manages. The collection of streams is entirely content dependent. The MIME type of this DataSource provides the only indication of what streams may be available on this connection.

Returns:

The collection of streams for this source.

Throws:

java.lang.IllegalStateException - Thrown if the source is not connected.

getControls

public abstract Control[] getControls()

Description copied from interface: Controllable

Obtain the collection of Controls from the object that implements this interface.

Since a single object can implement multiple Control interfaces, it's necessary to check each object against different Control types. For example:

Controllable controllable;
:
Control cs[];
cs = controllable.getControls();
for (int i = 0; i < cs.length; i++) {
if (cs[i] instanceof ControlTypeA)
doSomethingA();
if (cs[i] instanceof ControlTypeB)
doSomethingB();
// etc.
}


The list of Control objects returned will not contain any duplicates. And the list will not change over time.

If no Control is supported, a zero length array is returned.

Specified by:

getControls in interface Controllable

Returns:

the collection of Control objects.

getControl

public abstract Control getControl(java.lang.String controlType)

Description copied from interface: Controllable

Obtain the object that implements the specified Control interface.

If the specified Control interface is not supported then null is returned.

If the Controllable supports multiple objects that implement the same specified Control interface, only one of them will be returned. To obtain all the Control's of that type, use the getControls method and check the list for the requested type.

Specified by:

getControl in interface Controllable

Parameters:

controlType - the class name of the Control. The class name should be given either as the fully-qualified name of the class; or if the package of the class is not given, the package javax.microedition.media.control is assumed.

Returns:

the object that implements the control, or null.