Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

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, and the system TimeBase.

A Player is an object used to control and render multimedia data that is specific to the content type of the data. A DataSource is an object used to deliver time-based multimedia data that is specific to a delivery protocol. A DataSource provides a Player with media data; a Player must have a DataSource. Manager provides access to a protocol and media independent mechanism for constructing Players and DataSources.

Creating Players and DataSources

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

• Obtain the connected DataSource for the specified protocol
• Obtain the Player for the content-type specified by the DataSource
• Attach the DataSource to the Player using the setSource method.

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 instanced, 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 two types of supported MediaHandler: MediaProxy, and Player.

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 instanced, 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 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.

Player Threads

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

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.

See Also:

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

Field Summary

static java.lang.String

UNKNOWN_CONTENT_NAME

Method Summary

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 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 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 Handler/CODE> classes from the content-prefix-list and a content name.
static TimeBase	getSystemTimeBase() Get the time-base object for the system.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNKNOWN_CONTENT_NAME

public static final java.lang.String UNKNOWN_CONTENT_NAME

See Also:

Constant Field Values

Method Detail

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.

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.

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.

getSystemTimeBase

public static TimeBase getSystemTimeBase()

Get the time-base object for the system.

Returns:

The system time base.

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.

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 Handler/CODE> 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.