javax.media
Class Manager

java.lang.Object
  |
  +--javax.media.Manager

public final class Manager
extends java.lang.Object

Manager is the access point for obtaining system dependent resources such as Players, DataSources, Processors, DataSinks, the system TimeBase, the cloneable and merging utility DataSources.

A DataSource is an object used to deliver time-based multimedia data that is specific to a delivery protocol.

A Player is an object used to control and render multimedia data that is specific to the content type of the data.

A Processor is an object similar to a Player which is used to process data and output the processed data.

A DataSink is an object that takes a DataSource as input and renders the output to a specified destination.

A DataSource provides a Player, Processor or DataSink with media data; a Player, Processor or DataSink must have a DataSource. Manager provides access to a protocol and media independent mechanism for constructing DataSources, Players, Processors and DataSinks.

Creating Players and DataSources

Manager will createPlayers from a URL, a MediaLocator or a DataSource. Creating a Player requires the following:

Finding DataSources by Protocol

A MediaLocator defines a protocol for obtaining content. DataSources are identified by the protocol that they support. Manager uses the protocol name to find DataSource classes.

To find a DataSource using a MediaLocator, Manager constructs a list of class names from the protocol package-prefix list and the protocol name obtained from the MediaLocator. For each class name in the constructed list a new DataSource is instantiated, the MediaLocator is attached, and the DataSource is connected. If no errors have occurred, the procces is considered finished and the connected DataSource is used by Manager in any following operations. If there was an error then the next class name in the list is tried. The exact details of the search algorithm is described in the method documentation below.

Finding Players by Content Type

A Player is a MediaHandler. A MediaHandler is a an object that reads data from a DataSource. There are three types of supported MediaHandler: MediaProxy, Player and Processor.

MediaHandlers are identified by the content type that they support. A DataSource identifies the content type of the data it produces with the getContentType method. Manager uses the content type name to find instances of MediaHandler.

To find a MediaHandler using a content type name, Manager constructs a list of class names from the content package-prefix list and the content type name. For each class name in the constructed list a new MediaHandler is instantiated, and the DataSource is attached to the MediaHandler using MediaHandler.setSource.

If the MediaHandler is a Player and the setSource was successful the process is finished and the Player is returned. If the setSource failed, another name in the list is tried.

If the MediaHandler is a MediaProxy then a new DataSource is obtained from the MediaProxy, a new list is created for the content type the DataSource supports and the whole thing is tried again.

If a valid Player is not found then the whole procedure is repeated with "unknown" substituted for the content-type name. The "unknown" content type is supported by generic Players that are capable of handling a large variety of media types, often in a platform dependent way.

The detailed creation algorithm is specified in the methods below.

Creating a Realized Player

Versions of createRealizedPlayer calls are provided as an acceleration to create a Player. The returned player is in the Realized state. In addition to NoPlayerException and IOException, CannotRealizeException can be thrown if the Manager cannot realize the Player.

Creating Processors

Processors are created in the same way as Players as outlined above. Manager also provides an additional way to create a Processor via the createRealizedProcessor call. A ProcessorModel is used to fully identify the input and output requirements of a Processor. The createRealizedProcessor call takes a ProcessorModel as input and create a Processor that adheres to the given ProcessorModel. The returned Processor is in the Realized state. The method is a blocking call.

If the Manager fails to find a Processor that fits the ProcessorModel, a NoProcessorException is thrown. If there is a problem creating and realizing a Processor, it will throw an IOException or CannotRealizeException depending on the circumstances.

Creating DataSinks

DataSinks are created from an input DataSource MediaLocator. The MediaLocator identifies the protocol and content of the DataSink to be used. The search for the particular DataSink class to be created is similar to the process of creating a DataSource. The detail search and creation algorithm is described in the method documentation below.

Player and Processor Threads

Players and Processors process media data asynchronously from the main program flow. This implies that a Player or Processor must often manage one or more threads. The threads managed by the Player or Processor are not in the thread group of the application that calls createPlayer or createProcessor.

System Time Base

All Players need a TimeBase. Many use a system-wide TimeBase, often based on a time-of-day clock. Manager provides access to the system TimeBase through getSystemTimeBase.

Cloning and Merging DataSources

DataSources can be cloned or merged. If a DataSource is cloned, more than one MediaHandler can use it as input. Merging more than one DataSources will generate one DataSource which contains all the SourceStreams of the constituent DataSources

The Manager provides two methods: createCloneableDataSource and createMergingDataSource for such purpose.

Manager Hints

Using the setHint method, the preference for how the Manager creates the objects can be specified. However, a particular implementation of the Manager can choose to ignore the requested hints.

Since:
1.0 , new methods added in 2.0
See Also:
MAX_SECURITY, CACHING, LIGHTWEIGHT_RENDERER,

, URL, MediaLocator, PackageManager, DataSource, URLDataSource, MediaHandler, Player, Processor, MediaProxy, TimeBase


Field Summary
static int CACHING
          Boolean hint to turn on/off the use of playback caching.
static int LIGHTWEIGHT_RENDERER
          Boolean hint to turn on/off the use of light weight rendering.
static int MAX_SECURITY
          Boolean hint to turn on/off maximum security.
static int PLUGIN_PLAYER
          Boolean hint to request the Manager to create Players that support PlugIns.
static java.lang.String UNKNOWN_CONTENT_NAME
           
 
Method Summary
static DataSource createCloneableDataSource(DataSource source)
          Creates a cloneable DataSource.
static DataSink createDataSink(DataSource datasource, MediaLocator destLocator)
          Create a DataSink for the specified input Datasource and destination Medialocator.
static DataSource createDataSource(MediaLocator sourceLocator)
          Create a DataSource for the specified media.
static DataSource createDataSource(java.net.URL sourceURL)
          Create a DataSource for the specified media.
static DataSource createMergingDataSource(DataSource[] sources)
          Creates a merged DataSource from an array of sources.
static Player createPlayer(DataSource source)
          Create a Player for the DataSource.
static Player createPlayer(MediaLocator sourceLocator)
          Create a Player for the specified media.
static Player createPlayer(java.net.URL sourceURL)
          Create a Player for the specified media.
static Processor createProcessor(DataSource source)
          Create a Processor for the DataSource.
static Processor createProcessor(MediaLocator sourceLocator)
          Create a Processor for the specified media.
static Processor createProcessor(java.net.URL sourceURL)
          Create a Processor for the specified media.
static Player createRealizedPlayer(DataSource source)
          Create a Realized Player for the specified source.
static Player createRealizedPlayer(MediaLocator ml)
          Create a Realized Player for the specified media.
static Player createRealizedPlayer(java.net.URL sourceURL)
          Create a Realized Player for the specified media.
static Processor createRealizedProcessor(ProcessorModel model)
          Create a Realized Processor for the specified ProcessorModel.
static java.lang.String getCacheDirectory()
          Retrieve the directory that's used for playback caching.
static java.util.Vector getDataSourceList(java.lang.String protocolName)
          Build a list of DataSource class names from the protocol prefix-list and a protocol name.
static java.util.Vector getHandlerClassList(java.lang.String contentName)
          Build a list of Player Handler classes from the content-prefix-list and a content name.
static java.lang.Object getHint(int hint)
          Retrieve the value of a hint set.
static java.util.Vector getProcessorClassList(java.lang.String contentName)
          Build a list of Processor Handler classes from the content-prefix-list and a content name.
static TimeBase getSystemTimeBase()
          Get the time-base object for the system.
static java.lang.String getVersion()
          Returns the version string for this revision of JMF.
static void setHint(int hint, java.lang.Object value)
          Specify a hint for the Manager to use.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_SECURITY

public static final int MAX_SECURITY
Boolean hint to turn on/off maximum security.

CACHING

public static final int CACHING
Boolean hint to turn on/off the use of playback caching.

LIGHTWEIGHT_RENDERER

public static final int LIGHTWEIGHT_RENDERER
Boolean hint to turn on/off the use of light weight rendering. If on, the Manager will try to create Players that use renderers which can interoperate with light weight GUI components.

PLUGIN_PLAYER

public static final int PLUGIN_PLAYER
Boolean hint to request the Manager to create Players that support PlugIns. Such Players use PlugIns to demultiplex, decode, render or multiplex the data. It will also support TrackControls for application level programming.

UNKNOWN_CONTENT_NAME

public static final java.lang.String UNKNOWN_CONTENT_NAME
Method Detail

getVersion

public static java.lang.String getVersion()
Returns the version string for this revision of JMF.

createPlayer

public static Player createPlayer(java.net.URL sourceURL)
                           throws java.io.IOException,
                                  NoPlayerException
Create a Player for the specified media. This creates a MediaLocator from the URL and then calls createPlayer.
Parameters:
sourceURL - The URL that describes the media data.
Returns:
A new Player.
Throws:
NoPlayerException - Thrown if no Player can be found.
java.io.IOException - Thrown if there was a problem connecting with the source.

createPlayer

public static Player createPlayer(MediaLocator sourceLocator)
                           throws java.io.IOException,
                                  NoPlayerException
Create a Player for the specified media.

The algorithm for creating a Player from a MediaLocator is:

  1. Get the protocol from the MediaLocator.
  2. Get a list of DataSource classes that support the protocol, using the protocol package-prefix-list.
  3. For each source class in the list:
    1. Instantiate a new DataSource,
    2. Call the connect method to connect the source.
    3. Get the media content-type-name (using getContentType) from the source.
    4. Get a list of MediaHandler classes that support the media-content-type-name, using the content package-prefix-list.
    5. For each MediaHandler class in the list:
      1. Instantiate a new MediaHandler.
      2. Attach the source to the MediaHandler by calling MediaHandler.setSource.
      3. If there are no failures, determine the type of the MediaHandler; otherwise try the next MediaHandler in the list.
      4. If the MediaHandler is a Player, return the new Player.
      5. If the MediaHandler is a MediaProxy, obtain a new DataSource from the MediaProxy, obtain the list of MediaHandlers that support the new DataSource, and continue searching the new list.
    6. If no MediaHandler is found for this source, try the next source in the list.
  4. If no Player is found after trying all of the sources, reuse the source list.
    This time, for each source class in the list:
    1. Instantiate the source.
    2. Call the connect method to connect to the source.
    3. Use the content package-prefix-list to create a list of MediaHandler classes that support the "unknown" content-type-name.
    4. For each MediaHandler class in the list, search for a Player as in the previous search.
      1. If no Player is found after trying all of the sources, a NoPlayerException is thrown.
    Parameters:
    sourceLocator - A MediaLocator that describes the media content.
    Returns:
    A Player for the media described by the source.
    Throws:
    NoPlayerException - Thrown if no Player can be found.
    java.io.IOException - Thrown if there was a problem connecting with the source.

createPlayer

public static Player createPlayer(DataSource source)
                           throws java.io.IOException,
                                  NoPlayerException
Create a Player for the DataSource.

The algorithm for creating a Player from a DataSource is:

  1. Get the media content-type-name from the source by calling getContentType.
  2. Use the content package-prefix-list to get a list of Player classes that support the media content-type name.
  3. For each Player class in the list:
    1. Instantiate a new Player.
    2. Attach the source to the Player by calling setSource on the Player.
    3. If there are no failures, return the new Player; otherwise, try the next Player in the list.
  4. If no Player is found for this source:
    1. Use the content package-prefix-list to create a list of Player classes that support the "unknown" content-type-name.
    2. For each Player class in the list:
      1. Instantiate a new Player.
      2. Attach the source to the Player by calling setSource on the Player.
      3. If there are no failures, return the new Player; otherwise, try the next Player in the list.
  5. If no Player can be created, a NoPlayerException is thrown.
Parameters:
DataSource - The DataSource that describes the media content.
Returns:
A new Player.
Throws:
NoPlayerException - Thrown if a Player can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.

createRealizedPlayer

public static Player createRealizedPlayer(java.net.URL sourceURL)
                                   throws java.io.IOException,
                                          NoPlayerException,
                                          CannotRealizeException
Create a Realized Player for the specified media.

This is a blocking method that creates a Player, calls realize on it and returns only after the Player has been Realized. Realizing a Player could be a time consuming operation and one should use caution when using this method as it could block the thread for several seconds.

Parameters:
ml - The MediaLocator that describes the source of the media.
Returns:
A new Player that is in the Realized state.
Throws:
NoPlayerException - Thrown if a Player can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.
CannotRealizeException - Thrown if there was a problem realizing the Player.

createRealizedPlayer

public static Player createRealizedPlayer(MediaLocator ml)
                                   throws java.io.IOException,
                                          NoPlayerException,
                                          CannotRealizeException
Create a Realized Player for the specified media.

This is a blocking method that creates a Player, calls realize on it and returns only after the Player has been Realized. Realizing a Player could be a time consuming operation and one should use caution when using this method as it could block the thread for several seconds.

Parameters:
ml - The MediaLocator that describes the source of the media.
Returns:
A new Player that is in the Realized state.
Throws:
NoPlayerException - Thrown if a Player can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.
CannotRealizeException - Thrown if there was a problem realizing the Player.

createRealizedPlayer

public static Player createRealizedPlayer(DataSource source)
                                   throws java.io.IOException,
                                          NoPlayerException,
                                          CannotRealizeException
Create a Realized Player for the specified source.

This is a blocking method that creates a Player, calls realize on it and returns only after the Player has been Realized. Realizing a Player could be a time consuming operation and one should use caution when using this method as it could block the thread for several seconds.

Parameters:
source - The DataSource that describes the media content.
Returns:
A new Player that is in the Realized state.
Throws:
NoPlayerException - Thrown if a Player can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.
CannotRealizeException - Thrown if there was a problem realizing the Player.

createProcessor

public static Processor createProcessor(java.net.URL sourceURL)
                                 throws java.io.IOException,
                                        NoProcessorException
Create a Processor for the specified media.

The algorithm is similar to that for creating a Player from a URL

Parameters:
sourceURL - A URL that describes the media content.
Returns:
A Processor for the media described by the source.
Throws:
NoProcessorException - Thrown if no Processor can be found.
java.io.IOException - Thrown if there was a problem connecting with the source.

createProcessor

public static Processor createProcessor(MediaLocator sourceLocator)
                                 throws java.io.IOException,
                                        NoProcessorException
Create a Processor for the specified media.

The algorithm is similar to that for creating a Player from a MediaLocator

Parameters:
sourceLocator - A MediaLocator that describes the media content.
Returns:
A Processor for the media described by the source.
Throws:
NoProcessorException - Thrown if no Processor can be found.
java.io.IOException - Thrown if there was a problem connecting with the source.

createProcessor

public static Processor createProcessor(DataSource source)
                                 throws java.io.IOException,
                                        NoProcessorException
Create a Processor for the DataSource.

The algorithm for creating a Processor is similar to creating a Player from a DataSource.

Parameters:
DataSource - The DataSource that describes the media content.
Returns:
A new Processor.
Throws:
NoProcessorException - Thrown if a Processor can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.

createRealizedProcessor

public static Processor createRealizedProcessor(ProcessorModel model)
                                         throws java.io.IOException,
                                                NoProcessorException,
                                                CannotRealizeException
Create a Realized Processor for the specified ProcessorModel.

This method accepts a ProcessorModel that describes the required input and/or output format of the media data. It is a blocking method and returns only after the Processor reaches the Realized state.

Parameters:
model - The ProcessorModel that describes the input and output media
Returns:
A new Processor that is in the Realized state.
Throws:
NoProcessorException - Thrown if a Processor can't be created.
java.io.IOException - Thrown if there was a problem connecting with the source.
CannotRealizeException - Thrown if there was a problem realizing the Player.
See Also:
ProcessorModel

createDataSource

public static DataSource createDataSource(java.net.URL sourceURL)
                                   throws java.io.IOException,
                                          NoDataSourceException
Create a DataSource for the specified media.
Parameters:
sourceURL - The URL that describes the media data.
Returns:
A new DataSource for the media.
Throws:
NoDataSourceException - Thrown if no DataSource can be found.
java.io.IOException - Thrown if there was a problem connecting with the source.

createDataSource

public static DataSource createDataSource(MediaLocator sourceLocator)
                                   throws java.io.IOException,
                                          NoDataSourceException
Create a DataSource for the specified media.

Returns a data source for the protocol specified by the MediaLocator. The returned data source is connected; DataSource.connect has been invoked.

The algorithm for creating a DataSource from a MediaLocator is:

  1. Get the protocol from the MediaLocator.
  2. Use the protocol package-prefix list to get a list of DataSource classes that support the protocol.
  3. For each source class in the list:
    1. Instantiate a new DataSource.
    2. Call connect to connect the source.
    3. If there are no errors, return the connected source; otherwise, try the next source in the list.
  4. If no source has been found, obtain a URL from the MediaLocator and use it to create a URLDataSource
  5. If no source can be found, a NoDataSourceException is thrown.
Parameters:
sourceLocator - The source protocol for the media data.
Returns:
A connected DataSource.
Throws:
NoDataSourceException - Thrown if no DataSource can be found.
java.io.IOException - Thrown if there was a problem connecting with the source.

createMergingDataSource

public static DataSource createMergingDataSource(DataSource[] sources)
                                          throws IncompatibleSourceException
Creates a merged DataSource from an array of sources. All sources must be of the same type (i.e PullDataSource, PushDataSource, etc.) otherwise an IncompatibleSourceException is thrown. The returned DataSource is of the same type of the given sources. Its content-type is RAW if all sources are of type RAW. Otherwise, its content-type is MIXED.
Parameters:
sources - the DataSources to be merged
Returns:
a DataSource which contains all the streams of the original sources
Throws:
IncompatibleSourceException - if the sources are not of the same type

createCloneableDataSource

public static DataSource createCloneableDataSource(DataSource source)
Creates a cloneable DataSource. The returned DataSource implements the SourceCloneable interface and enables the creation of clones by the createClone method.
If the input DataSource implements SourceCloneable, it will be returned right away as the result. Otherwise, a "proxy" DataSource is created. It implements the SourceCloneable interface and can be used to generate other clones.
When createCloneableDataSource is called on a DataSource, the returned DataSource should be used in place of the original DataSource. Any attempt to use the original DataSource may generate unpredictable results.
The resulted cloneable DataSource can be used to generate clones. The clones generated may or may not has the same properties of the original DataSource depending on the implementation. Therefore, they should be checked against the properties required for the application. If the original DataSource is not SourceCloneable and a "proxy" DataSource is resulted, the clones generated from this "proxy" DataSource is of type PushDataSource or PushBufferDataSource depending on the type of the original DataSource. In this case, each clone pushes data at the same rate that the original DataSource is pulled or pushed.
Parameters:
source - the DataSource to be cloned
Returns:
a cloneable DataSource for the given source
See Also:
SourceCloneable

getSystemTimeBase

public static TimeBase getSystemTimeBase()
Get the time-base object for the system.
Returns:
The system time base.

createDataSink

public static DataSink createDataSink(DataSource datasource,
                                      MediaLocator destLocator)
                               throws NoDataSinkException
Create a DataSink for the specified input Datasource and destination Medialocator.

The algorithm for creating a DataSink from a MediaLocator and datasource is:

  1. Get the protocol from the MediaLocator.
  2. Get a list of MediaHandler classes within the datasink package that support the protocol, using the content package-prefix-list. i.e. search for content-prefix.media.datasink.protocol.Handler
  3. For each MediaHandler class in the list:
    1. Instantiate a new MediaHandler.
    2. If the MediaHandler is a DataSink, Attach the source to the MediaHandler by calling MediaHandler.setSource
    3. If there are no failures, return this DataSink;otherwise try the next MediaHandler in the list.
    4. If the MediaHandler is a DataSinkProxy, obtain the content type of the proxy using the getContentType() method. Now obtain a list of MediaHandlers that support the protocol of the Medialocator and the content type returned by the proxy
      i.e. look for content-prefix.media.datasink.protocol.content-type.Handler
    5. If a MediaHandler is found and it is a DataSink, attach the datasource to it by calling MediaHandler.setSource.
    6. Return the DataSink if there are no errors.
    7. If no MediaHandler is found, or if there are any errors,try the next MediaHandler
    8. If no DataSink is found after trying all of the handlers, a NoDataSinkException is thrown.
Parameters:
datasource - The input DataSource to the DataSink
destLocator - A MediaLocator that describes the destination of the media to be handled by the datasink
Returns:
A DataSink for the media described by the destLocator and that supports the datasource .
Throws:
NoDataSinkException - Thrown if no DataSink can be found.
See Also:
NoDataSinkException

getCacheDirectory

public static java.lang.String getCacheDirectory()
Retrieve the directory that's used for playback caching.
Returns:
the directory that's used for playback caching, null if the directory is not specified.

setHint

public static void setHint(int hint,
                           java.lang.Object value)
Specify a hint for the Manager to use.
Parameters:
hint - The name of the hint to be set.
value - The value the hint is to be set.
See Also:
MAX_SECURITY, CACHING, LIGHTWEIGHT_RENDERER, PLUGIN_PLAYER

getHint

public static java.lang.Object getHint(int hint)
Retrieve the value of a hint set.
Parameters:
hint - The name of the hint.
Returns:
The value of the hint.
See Also:
MAX_SECURITY, CACHING, LIGHTWEIGHT_RENDERER, PLUGIN_PLAYER

getDataSourceList

public static java.util.Vector getDataSourceList(java.lang.String protocolName)
Build a list of DataSource class names from the protocol prefix-list and a protocol name.

The first name in the list will always be:

 media.protocol.<protocol>DataSource
 

Each additional name looks like:

 <protocol-prefix>.media.protocol.<protocol>.DataSource
 
for every <protocol-prefix> in the protocol-prefix-list.
Parameters:
protocol - The name of the protocol the source must support.
Returns:
A vector of strings, where each string is a Player class-name.

getHandlerClassList

public static java.util.Vector getHandlerClassList(java.lang.String contentName)
Build a list of Player Handler classes from the content-prefix-list and a content name.

The first name in the list will always be:

 media.content.<contentType>.Handler
 

Each additional name looks like:

 <content-prefix>.media.content.<contentName>.Player
 
for every <content-prefix> in the content-prefix-list.
Parameters:
contentName - The content type to use in the class name.
Returns:
A vector of strings where each one is a Player class-name.

getProcessorClassList

public static java.util.Vector getProcessorClassList(java.lang.String contentName)
Build a list of Processor Handler classes from the content-prefix-list and a content name.

The first name in the list will always be:

 media.processor.<contentType>.Handler
 

Each additional name looks like:

 <content-prefix>.media.processor.<contentName>.Processor
 
for every <content-prefix> in the content-prefix-list.
Parameters:
contentName - The content type to use in the class name.
Returns:
A vector of strings where each one is a Processor class-name.