javax.media.Manager Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of ocap Show documentation
There is a newer version: 1.3.1
/**
This is not an official specification document, and usage is restricted.


NOTICE





(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.


Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.  

Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example, 
this file and any files generated from it may be used to generate other documentation, 
such as a unified set of documents of API signatures for a platform 
that includes technologies expressed as Java APIs. 
This file may also be used to produce "compilation stubs," 
which allow applications to be compiled and validated for such platforms. 
By contrast, no permission is given for you to incorporate this file, 
in whole or in part, in an implementation of a Java specification.

Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.  
In the event of a discrepency between this work and the JSR 927 specification, 
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/



  


package javax.media;

import java.io.IOException;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.Enumeration;
import java.util.Vector;
import javax.media.protocol.DataSource;
import javax.media.protocol.URLDataSource;

/** 
 * 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.
 * 
 *
 * It is possible to create multiple Players for the same scarce resource
 * (such as a hardware video decoder).
 * However, doing so may affect the state of other Players which depend on
 * that resource.
 *
 * 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 java.net.URL
 * @see MediaLocator
 * @see PackageManager
 * @see javax.media.protocol.DataSource
 * @see javax.media.protocol.URLDataSource
 * @see MediaHandler
 * @see Player
 * @see MediaProxy
 * @see TimeBase
 *
 * @version 1.58, 07/09/19.
 */
public final class Manager
{
    public static final String UNKNOWN_CONTENT_NAME = "unknown";

    /*
     * This hidden constructor does not necessarily correspond to
     * a constructor in the original source file -- it keeps javadoc
     * from generating an inappropriate default constructor.
     */
    private Manager() { }

    /** 
     * Create a Player for the specified media.
     * This creates a MediaLocator from the URL and then
     * calls createPlayer.
     *
     * @param sourceURL The URL that describes the media data.
     * @return A new Player.
     * @exception NoPlayerException Thrown if no Player
     * can be found.
     * @exception IOException Thrown if there was a problem connecting
     * with the source.
     */
    public static Player createPlayer(URL sourceURL)
        throws IOException, NoPlayerException
    {
        return null;
    }

    /** 
     * Create a Player for the specified media.
     * 
     * The algorithm for creating a Player from
     * a MediaLocator is:
     * 

     * Get the protocol from the MediaLocator.
     * 
Get a list of DataSource classes that
     * support the protocol, using the protocol package-prefix-list.
     * 
 For each source class in the list:
     * 
     * Instantiate a new DataSource,
     * 
Call the connect method to connect the source.
     * 
Get the media content-type-name (using getContentType)
     * from the source.
     * 
Get a list of MediaHandler classes that support the
     * media-content-type-name, using the content package-prefix-list.
     * 
For each MediaHandler class in the list:
     * 
     * Instantiate a new MediaHandler.
     * 
Attach the source to the MediaHandler by calling
     * MediaHandler.setSource.
     * 
If there are no failures, determine the type of
     * the MediaHandler; otherwise try the next
     * MediaHandler in the list.
     * 
If the MediaHandler is a Player,
     * return the new Player.
     * 
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.
     * 
     * 
If no MediaHandler is found for this source,
     * try the next source in the list.
     * 
     * 
If no Player is found after trying all of the sources,
     * reuse the source list.

     * This time, for each source class in the list:
     * 
     * Instantiate the source.
     * 
Call the connect method to connect to the source.
     * 
Use the content package-prefix-list to create a list of 
     * MediaHandler classes that support the
     * "unknown" content-type-name.
     * 
For each MediaHandler class in the list,
     * search for a Player as in the previous search.
     * 
     * If no Player is found after trying all of the sources,
     * a NoPlayerException is thrown.
     * 
     * 
     * @param sourceLocator A MediaLocator that describes
     * the media content.
     * @return A Player for the media described by the source.
     * @exception NoPlayerException Thrown if no Player can
     * be found.
     * @exception IOException Thrown if there was a problem connecting
     * with the source.
     */
    public static Player createPlayer(MediaLocator sourceLocator)
        throws IOException, NoPlayerException
    {
        return null;
    }

    /** 
     * Create a Player for the DataSource.
     * 
     * The algorithm for creating a Player from
     * a DataSource is:
     * 

     * Get the media content-type-name from the source by
     * calling getContentType.
     * 
Use the content package-prefix-list to get a list of 
     * Player classes that support the media content-type name.
     * 
For each Player class in the list:
     * 
     * Instantiate a new Player.
     * 
Attach the source to the Player by calling
     * setSource on the Player.
     * 
If there are no failures,  return the new Player;
     * otherwise,
     * try the next Player in the list.
     *      
     * 
If no Player is found for this source:
     * 
     * Use the content package-prefix-list to create a list 
     * of Player classes that support the
     * "unknown" content-type-name.
     * 
For each Player class in the list:
     * 
     * Instantiate a new Player.
     * 
Attach the source to the Player by
     * calling setSource 
     * on the Player.
     * 
If there are no failures, return the new Player;
     * otherwise, try the next Player in the list.
     * 
     * 
     * 
If no Player can be created,
     * a NoPlayerException is thrown.
     * 
     * @param DataSource The DataSource that describes
     * the media content.
     * @return A new Player.
     * @exception NoPlayerException Thrown if a Player can't
     * be created.
     * @exception IOException Thrown if there was a problem connecting
     * with the source.
     */
    public static Player createPlayer(DataSource source)
        throws IOException, NoPlayerException
    {
        return null;
    }

    /** 
     * Create a DataSource for the specified media.
     *
     * @param sourceURL The URL that describes the media data.
     * @return A new DataSource for the media.
     * @exception NoDataSourceException Thrown if no DataSource
     * can be found.
     * @exception IOException Thrown if there was a problem connecting
     * with the source.
     */
    public static DataSource createDataSource(URL sourceURL)
        throws IOException, NoDataSourceException
    {
        return null;
    }

    /** 
     * 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:
     * 

     * Get the protocol from the MediaLocator.
     * 
Use the protocol package-prefix list to get a list of 
     * DataSource classes that
     * support the protocol.
     * 
 For each source class in the list:
     * 
     * Instantiate a new DataSource.
     * 
Call connect to connect the source.
     * 
If there are no errors, return the connected
     * source; otherwise, try the next source in the list.
     * 
     * 
If no source has been found, obtain a URL from the
     * MediaLocator and use it to create
     * a URLDataSource
     * 
If no source can be found, a NoDataSourceException
     * is thrown.
     * 
     * 
     *
     * @param sourceLocator The source protocol for the media data.
     * @return A connected DataSource.
     * @exception NoDataSourceException Thrown if no DataSource
     * can be found.
     * @exception IOException Thrown if there was a problem connecting
     * with the source.
     */
    public static DataSource createDataSource(MediaLocator sourceLocator)
        throws IOException, NoDataSourceException
    {
        return null;
    }

    /** 
     * Get the time-base object for the system.
     * @return The system time base.
     */
    public static TimeBase getSystemTimeBase() {
        return null;
    }

    /** 
     * 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.
     *
     * @param protocol The name of the protocol the source must
     * support.
     * @return A vector of strings, where each string is
     * a Player class-name.
     */
    public static Vector getDataSourceList(String protocolName) {
        return null;
    }

    /** 
     * 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.
     *
     * @param contentName The content type to use in the class name.
     * @return A vector of strings where each one is a Player
     * class-name.
     */
    public static Vector getHandlerClassList(String contentName) {
        return null;
    }
}