public abstract class DataSource extends java.lang.Object implements Controllable
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 SourceStream
s.
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 SourceStream
s if it encapsulates
multiple elementary data streams.
Each of the SourceStream
s 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.
Manager
,
SourceStream
,
ContentDescriptor
Constructor and Description |
---|
DataSource(java.lang.String locator)
Construct a
DataSource from a locator. |
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
Control s
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.
|
public DataSource(java.lang.String locator)
DataSource
from a locator.
This method should be overloaded by subclasses;
the default implementation just keeps track of
the locator.locator
- The locator that describes
the DataSource
.public java.lang.String getLocator()
null
if the locator hasn't been set.public abstract java.lang.String getContentType()
null
if the content is unknown.java.lang.IllegalStateException
- Thrown if the source is
not connected.public abstract void connect() throws java.io.IOException
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
.public abstract void disconnect()
If no resources are in use, disconnect
is ignored.
If stop
hasn't already been called,
calling disconnect
implies a stop.
public abstract void start() throws java.io.IOException
start
method must be
called before data is available for reading.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
.public abstract void stop() throws java.io.IOException
DataSource
has not been connected and started,
stop
is ignored.java.io.IOException
- Thrown if the DataSource
cannot be stopped due to some IO problems.public abstract SourceStream[] getStreams()
DataSource
provides the only indication of
what streams may be available on this connection.java.lang.IllegalStateException
- Thrown if the source
is not connected.public abstract Control[] getControls()
Controllable
Control
s
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.
getControls
in interface Controllable
Control
objects.public abstract Control getControl(java.lang.String controlType)
Controllable
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.
getControl
in interface Controllable
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.null
.Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.