Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `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.

`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
`DataSource(java.lang.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 java.lang.String` | `getContentType()` Get a string that describes the content-type of the media that the source is providing.
`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
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface javax.microedition.media.Controllable
`getControl, getControls`

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:
    `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.
    `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:
    `IllegalStateException` - Thrown if the `DataSource` is not connected.
    `java.io.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`.

### 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:
    `IllegalStateException` - Thrown if the source is not connected.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD