javax.microedition.media.protocol
Class DataSource

java.lang.Object
  extended by javax.microedition.media.protocol.DataSource
All Implemented Interfaces:
Controllable
Direct Known Subclasses:
ByteArrayInputStreamDataSource

public abstract class DataSource
extends 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(java.lang.String) method.

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

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
Since:
BlackBerry API 4.0.0

Constructor Summary
DataSource(String locator)
          Construct a DataSource from a locator.
 
Method Summary
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  String getContentType()
          Get a sting that describes the content-type of the media that the source is providing.
 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.microedition.media.Controllable
getControl, getControls
 



Constructor Detail

DataSource

public DataSource(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.
Since:
BlackBerry API 4.0.0


Method Detail

getLocator

public String getLocator()
Get the locator that describes this source. Returns null if the locator hasn't been set.

Returns:
The locator for this source.
Since:
BlackBerry API 4.0.0

getContentType

public abstract String getContentType()
Get a sting 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:
IllegalStateException - Thrown if the source is not connected.
Since:
BlackBerry API 4.0.0

connect

public abstract void connect()
                      throws IOException
Open a connection to the source described by the locator and initiate communication.

Throws:
IOException - Thrown if there are IO problems when connect is called.
SecurityException - Thrown if the caller does not have security permission to call connect.
Since:
BlackBerry API 4.0.0

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, callling disconnect implies a stop.

Since:
BlackBerry API 4.0.0

start

public abstract void start()
                    throws IOException
Initiate data-transfer. The start method must be called before data is available for reading.

Throws:
IllegalStateException - Thrown if the DataSource is not connected.
IOException - Thrown if the DataSource cannot be started due to some IO problems.
SecurityException - Thrown if the caller does not have security permission to call start.
Since:
BlackBerry API 4.0.0

stop

public abstract void stop()
                   throws IOException
Stop the data-transfer. If the DataSource has not been connected and started, stop is ignored.

Throws:
IOException - Thrown if the DataSource cannot be stopped due to some IO problems.
Since:
BlackBerry API 4.0.0

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:
IllegalStateException - Thrown if the source is not connected.
Since:
BlackBerry API 4.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.