player.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)Player.java	1.24 02/07/24 @(#)
 *
 * Copyright (c) 2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.media;

import java.io.IOException;

/**
 * <code>Player</code> controls the rendering of time based media data.
 * It provides the methods to manage the <code>Player</code>'s life
 * cycle, controls the playback progress and obtains the presentation
 * components.
 * 
 * <h2>Simple Playback</h2>
 *
 * <blockquote>
 * A <code>Player</code> can be created from one of the 
 * <code>Manager</code>'s <code>createPlayer</code> methods.
 * After the <code>Player</code> is created, 
 * calling <code>start</code> will start the playback as soon as possible.
 * The method will return when the
 * playback is started.  The playback will continue in the background
 * and will stop automatically when the end of media is reached.
 * <p>
 * <a href="#example">Simple playback example</a> illustrates this.
 * </blockquote>
 * 
 * <h2>Player Life Cycle</h2>
 *
 * <blockquote>
 * A <code>Player</code> has five states:
 * <a href="#unrealizedState"><i>UNREALIZED</i></a>, 
 * <a href="#realizedState"><i>REALIZED</i></a>, 
 * <a href="#prefetchedState"><i>PREFETCHED</i></a>, 
 * <a href="#startedState"><i>STARTED</i></a>,
 * <a href="#closedState"><i>CLOSED</i></a>.
 * <p>
 *
 * The purpose of these life-cycle states is to provide
 * programmatic control over potentially time-consuming operations.
 * For example, when a <code>Player</code> is first constructed, it's in 
 * the <i>UNREALIZED</i> state.
 * Transitioned from <I>UNREALIZED</I> to <I>REALIZED</I>, the 
 * <code>Player</code> 
 * performs the communication necessary to locate all of the resources
 * it needs to function (such as communicating with a server
 * or a file system).
 * The <code>realize</code> method allows an application to initiate this
 * potentially time-consuming process at an
 * appropriate time.
 * <p>
 *
 * Typically, a <code>Player</code> moves from the <i>UNREALIZED</i> state 
 * to the <i>REALIZED</i> state, then to the <i>PREFETCHED</i> state, 
 * and finally on to the <i>STARTED</i> state.
 * <p>
 *
 * A <code>Player</code> stops when it reaches the
 * end of media;
 * or when the <code>stop</code> method is invoked.
 * When that happens, the <code>Player</code> moves from the 
 * <i>STARTED</i> state
 * back to the <i>PREFETCHED</i> state.
 * It is then ready to repeat the cycle.
 * <p>
 *
 * To use a <code>Player</code>, you must set up parameters to
 * manage its movement through these life-cycle states and then
 * move it through the states using the <code>Player</code>'s
 * state transition methods. 
 *
 * </blockquote>
 * <p>
 *
 * <h2>Player States</h2>
 *
 * <blockquote>
 * This section describes the semantics of each of the <code>Player</code>
 * states.
 *
 * <a name="unrealizedState"></a>
 * <h3>UNREALIZED State</h3>
 * <blockquote>
 * A <code>Player</code> starts in
 * the <i>UNREALIZED</i> state.
 * An unrealized <code>Player</code> 
 * does not have enough information to acquire all the resources it needs
 * to function.
 * <p>
 * The following methods must not be used
 * when the <code>Player</code> is in
 * the <i>UNREALIZED</i> state.
 * <ul>
 * <li> <CODE>getContentType</CODE>
 * <li> <CODE>setMediaTime</CODE>
 * <li> <CODE>getControls</CODE>
 * <li> <CODE>getControl</CODE>
 * </ul>
 *
 * An <code>IllegalStateException</code> will be thrown.
 * <p>
 * The <a href="#realize()"><code>realize</code></a> method transitions
 * the <code>Player</code> from the <i>UNREALIZED</i> state to the
 * <i>REALIZED</i> state.
 * </blockquote>
 *
 * <a name="realizedState"></a>
 * <h3>REALIZED State</h3>
 *
 * <blockquote>
 * A <code>Player</code> is in the <i>REALIZED</i> state when it 
 * has obtained 
 * the information required to acquire the media resources.
 * Realizing a <code>Player</code> can be a resource and 
 * time consuming process.
 * The <code>Player</code> may have to communicate with
 * a server, read a file, or interact with a set of objects.
 * <p>
 *
 * Although a realized <code>Player</code> does not have 
 * to acquire any resources, it
 * is likely to have acquired all of the resources it needs except 
 * those that imply exclusive use of a 
 * scarce system resource, such as an audio device.
 * <p>
 *
 * Normally, a <code>Player</code> moves from the <i>UNREALIZED</i> state
 * to the <i>REALIZED</i> state.
 * After <a href="#realize()"><code>realize</code></a> has been 
 * invoked on a <code>Player</code>, 
 * the only way it can return 
 * to the <i>UNREALIZED</i> state is if 
 * <a href="#deallocate()"><code>deallocate</code></a> is
 * invoked before <code>realize</code> is completed.
 * Once a <code>Player</code> reaches the <i>REALIZED</i> state, it
 * never returns to the <i>UNREALIZED</i> state.  It remains in one of four
 * states: <i>REALIZED</i>, <i>PREFETCHED</i>, <i>STARTED</i> or 
 * <i>CLOSED</i>.
 * </blockquote>
 *
 * <a name="prefetchedState"></a>
 * <h3>PREFETCHED State</h3>
 *
 * <blockquote>
 * Once realized, a <code>Player</code> may still need to 
 * perform a number of time-consuming tasks before it is ready to be started. 
 * For example, it may need to acquire scarce or exclusive resources, 
 * fill buffers with media data, or perform other start-up processing. 
 * Calling 
 * <a href="#prefetch()"><code>prefetch</code></a>
 * on the <code>Player</code> carries
 * out these tasks.
 * <p>
 *
 * Once a <code>Player</code> is in the <i>PREFETCHED</i> state, it may 
 * be started.
 * Prefetching reduces the startup latency of a <code>Player</code> 
 * to the minimum possible value. 
 * <p>
 *
 * When a started <code>Player</code> stops,
 * it returns 
 * to the <i>PREFETCHED</i> state.  
 * </blockquote>
 * <p>
 *
 * <a name="startedState"></a>
 * <h3>STARTED State</h3>
 *
 * <blockquote>
 * Once prefetched, a <code>Player</code> can enter the
 * <i>STARTED</i> state by calling the
 * <a href="#start()"><code>start</code></a> method. 
 * A <I>STARTED</I>&nbsp;<CODE>Player</CODE>&nbsp;
 * means the <code>Player</code> is running and processing data.
 * A <code>Player</code> returns to the <i>PREFETCHED</i>
 * state when it stops, because the
 * <a href="#stop()"><code>stop</code></a> method was invoked,
 * or it has reached the end of the media.
 * <p>
 *
 * When the <code>Player</code> moves from the <i>PREFETCHED</i>
 * to the <i>STARTED</i> state, it posts a <code>STARTED</code> event. 
 * When it moves from the <i>STARTED</i> state to the 
 * <i>PREFETCHED</i> state, 
 * it posts a <code>STOPPED</code>, <code>END_OF_MEDIA</code>
 * event depending on the reason it
 * stopped.
 * <p>
 *
 * The following method must not be used
 * when the <code>Player</code> is in the <i>STARTED</i> state:
 * <ul>
 * <li> <CODE>setLoopCount</CODE>
 * </ul>
 *
 * An <code>IllegalStateException</code> will be thrown.
 *
 * </blockquote>
 *
 * <a name="closedState"></a>
 * <h3>CLOSED state</h3>
 * 
 * <blockquote>
 * Calling <code>close</code> on the <code>Player</code>
 * puts it in the <i>CLOSED</i> state.  In the <i>CLOSED</i>
 * state, the <code>Player</code> has
 * released most of its resources and must not
 * be used again.
 * </blockquote>
 *
 * The <code>Player</code>'s five states and the state transition
 * methods are summarized in the following diagram:
 * <p>
 * <blockquote>
 * <img src="doc-files/states.gif" width="492" height="183">
 * </blockquote>
 *
 * </blockquote>
 * <p>
 *
 * <a name="CE">
 * <h2>Player Events</h2></a>
 *
 * <blockquote>
 * <code>Player</code> events asynchronously deliver
 * information about the <code>Player</code>'s state changes
 * and other relevant information from the <code>Player</code>'s
 * <code>Control</code>s.
 * <p>
 *
 * To receive events, an object must implement the
 * <code>PlayerListener</code> interface and use the
 * <code>addPlayerListener</code> method to register its
 * interest in a <code>Player</code>'s events.
 * All <code>Player</code> events are posted to each
 * registered listener.
 * <p>
 *
 * The events are guaranteed to be delivered in the order
 * that the actions representing the events occur.  
 * For example, if a <code>Player</code>
 * stops shortly after it starts because it is playing back
 * a very short media file, the <code>STARTED</code> event 
 * must always
 * preceed the <code>END_OF_MEDIA</code> event.
 * <p>
 *
 * An <code>ERROR</code> event may be sent any time
 * an irrecoverable error has occured.  When that happens, the
 * <code>Player</code> is in the <i>CLOSED</i> state.
 * <p>
 *
 * The <code>Player</code> event mechanism is extensible and 
 * some <code>Players</code> define events other than 
 * the ones described here.  For a list of pre-defined player
 * events, check the <code>PlayerListener</code> interface.
 * </blockquote>
 *
 * <h3>Managing the Resources Used by a Player</h3>
 *
 * <blockquote>
 * The <a href="#prefetch()"><code>prefetch</code></a> 
 * method is used to acquire scarce or exclusive resources
 * such as the audio device.
 * Conversely, the <a href="#deallocate()"><code>deallocate</code></a> 
 * method is used to release the scarce or exclusive
 * resources.  By using these two methods, an application can
 * programmatically manage the <code>Player</code>'s resources.
 * <p>
 * For example, in an implementation with an exclusive audio device, to
 * alternate the audio playback of multiple <code>Player</code>s,
 * an application can selectively deallocate and prefetch individual
 * <code>Player</code>s.
 * 
 * </blockquote>
 * <p>
 *
 * <a name="controls"></a>
 * <h2>Player's Controls</h2>
 * <blockquote>
 * <code>Player</code> implements <code>Controllable</code> which
 * provides extra controls via some type-specific <code>Control</code>
 * interfaces.  <code>getControl</code> and <code>getControls</code>
 * cannot be called when the <code>Player</code> is in the
 * <i>UNREALIZED</i> or <i>CLOSED</i> state.  
 * An <code>IllegalStateException</code> will be thrown.
 * </blockquote>
 * <p>
 * 
 * <a name="example"></a>
 * <h2>Simple Playback Example</h2>
 *
 * <blockquote>
 * <pre>
 * try {
 *     Player p = Manager.createPlayer("http://abc.wav");
 *     p.start();
 * } catch (MediaException pe) {
 * } catch (IOException ioe) {
 * }
 * </pre>
 * </blockquote>
 *
 */

public interface Player extends Controllable {

    /**
     * The state of the <code>Player</code> indicating that it has
     * not acquired the required information and resources to function.
     * <p>
     * Value 100 is assigned to <code>UNREALIZED</code>.
     */
    int UNREALIZED = 100;

    /**
     * The state of the <code>Player</code> indicating that it has
     * acquired the required information but not the resources to function.
     * <p>
     * Value 200 is assigned to <code>REALIZED</code>.
     */
    int REALIZED = 200;

    /**
     * The state of the <code>Player</code> indicating that it has
     * acquired all the resources to begin playing.
     * <p>