javax.media.Controller Maven / Gradle / Ivy
/*
* @(#)Controller.java 1.65 98/03/28
*
* Copyright 1996-1998 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package javax.media;
/**
*
* Controller, which extends Clock,
* provides resource-allocation
* state information, event generation, and a mechanism for obtaining objects
* that provide additional control over a Controller.
*
* Controller life-cycle
*
*
* As a Clock, a Controller is always either
* Started or Stopped.
* However, Controller subdivides
* Clock's Stopped state into five
* resource-allocation phases:
* Unrealized, Realizing, Realized,
* Prefetching, and Prefetched.
*
*
* The motivation for these life-cycle states is to provide
* programmatic control over potentially time-consuming operations.
* For example, when a Controller is first constructed, it's in
* the Unrealized state.
* While Realizing, the Controller
* performs the communication necessary to locate all of the resources
* it needs to function (such as communicating with a server,
* other controllers, or a file system).
* The realize method allows an application to initiate this
* potentially time-consuming process (Realizing) at an
* appropriate time.
* When a Controller is Realizing or Prefetching,
* it will eventually transition to another state, such as Realized,
* Prefetched, or even Unrealized.
*
* Because a Controller is often in one state on its way to
* another, its destination or target state is an integral part
* of the Controller life-cycle.
* You can query a Controller to determine both its
* current state and its target state.
*
*
* A Controller typically moves from the Unrealized state
* through Realizing to the Realized state,
* then through Prefetching
* to the Prefetched state, and finally on to the Started state.
* When a Controller finishes because
* the end of the media stream is reached,
* its stop time is reached,
* or the stop method is invoked,
* the Controller moves from the Started state
* back to Prefetched
* or possibly back to Realized, ready to
* repeat the cycle.
*
*
* To use a Controller, you set up parameters to
* manage its movement through these life-cycle states and then
* move it through the states using the Controller
* state transition methods.
* To keep track of the Controller's current state,
* you monitor the state transition events that it posts when changing states.
*
*
State Transition Methods
*
* A Controller has five methods that are used to induce
* life-cycle state changes:
* realize, prefetch, deallocate,
* syncStart, and stop.
*
* To transition a Controller to the Realized,
* Prefetched, or Started state,
* you use the corresponding method: realize,
* prefetch, or syncStart. The
* deallocate and stop methods can change
* a requested state transition or trigger a state change.
*
*
* The forward transition methods (realize,
* prefetch, and syncStart) are executed
* asynchronously and return immediately.
* When the requested operation is complete, the Controller
* posts a ControllerEvent
* that indicates that the target state has been reached,
* stop or deallocate has been invoked, or
* that an error occurred.
*
*
* The deallocate, and stop methods can
* change the target state and induce a transition back to
* a previous state. For example, calling deallocate on
* a Controller in the
* Prefetching state will move it back to
* Realized. These methods are synchronous.
*
*
*
State Transition Events
*
* A Controller often moves between states
* in an asynchronous manner.
* To facilitate the tracking of a Controller's state,
* every time its state or target state changes,
* the Controller is required to post a TransitionEvent that describes
* its previous state, current state, and new target state.
* By monitoring the Controller event stream, you can determine
* exactly what a Controller is doing at any point in time.
*
*
* When one of the asynchronous forward state transition methods
* completes, the Controller posts the appropriate TransitionEvent
* or a ControllerErrorEvent indicating that
* the Controller is no longer usable.
* For more information about ControllerEvents, see the Controller Events section.
*
*
* To facilitate simple asynchronous method protocols,
* a Controller always posts a method completion event
* when one of the asynchronous forward state transition methods is invoked, even
* if no state or target state change occurs.
* For example, if realize is called on a
* Prefetching Controller,
* a RealizeCompleteEvent
* is immediately posted, even though the Controller remains
* in the Prefetching state and the target state is still
* Prefetched.
* The method completion events always report the Controller's previous,
* current, and target state at the time the event was posted.
*
*
*
*
Controller States
*
* This section describes the semantics of each of the Controller
* states.
*
*
* Unrealized State
* A newly instanced Controller starts in
* the Unrealized state.
* An Unrealized Controller knows very little about its
* internals and does not have enough information to acquire all of the resources
* it needs to function.
* In particular, an Unrealized Controller does
* not know enough to properly construct
* a Clock.
* Therefore, it is illegal to call the following methods
* on an Unrealized Controller:
*
* -
getTimeBase
* -
setTimeBase
* -
setMediaTime
* -
setRate
* -
setStopTime
* -
getStartLatency
*
*
* A NotRealizedError is thrown if any of these methods are called
* on an Unrealized Controller.
*
* Realizing and Realized States
*
* A Controller is Realized when it has obtained
* all of the information necessary for it to acquire the resources it needs
* to function.
* A Realizing Controller is in the process of
* identifying the resources that it needs to acquire.
* Realizing can be a resource and time-consuming process.
* A Realizing Controller might have to communicate with
* a server, read a file, or interact with a set of other objects.
*
*
* Although a Realized Controller does not have to acquire
* any resources, a Realized Controller 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 or MPEG decoding hardware.
*
*
* Normally, a Controller moves from the Unrealized state
* through Realizing and on to the Realized state.
* After realize has been invoked on a Controller, the only way it can return
* to the Unrealized state is if deallocate is
* invoked before Realizing completes.
* Once a Controller reaches the Realized state, it
* never returns to the Unrealized state; it remains in one of four
* states: Realized, Prefetching, Prefetched, or
* Started.
*
*
*
Realize method
* The realize method executes asynchronously and completion
* is signaled by a RealizeCompleteEvent or a
* ControllerErrorEvent.
*
*
*
Prefetching and Prefetched States
*
* Once Realized, a Controller might still need to
* perform a number of time-consuming tasks before it is ready to be started.
* For example, it might need to acquire scarce hardware resources,
* fill buffers with media data, or perform other start-up processing.
* While performing these tasks, the Controller
* is in the Prefetching state.
* When finished, it moves into the Prefetched state.
* Over a Controller's lifetime, Prefetching might have to recur when certain methods are invoked.
* For example, calling setMediaTime might cause a Player to be
* Prefetched again before it is Started.
*
*
* Once a Controller is Prefetched, it is capable of starting as quickly
* as is possible for that Controller.
* Prefetching reduces the startup latency of a Controller to the minimum
* possible value. (The startup latency is the value returned by getStartLatency.)
*
*
* Typically, a Controller moves from the Realized state through
* Prefetching and on to the Prefetched state.
* Once Prefetched, a Controller
* remains Prefetched unless deallocate, syncStart
* or a method that changes its state and
* increases its startup latency is invoked, such as setMediaTime.
*
*
*
* A Started Controller returns to the Prefetched
* or Realized state when it stops.
*
*
*
Prefetch Method
*
* The prefetch method is asynchronous and its completion is signaled
* by a PrefetchCompleteEvent or a ControllerErrorEvent.
* As a convenience, if prefetch is invoked before a
* Controller has reached the Realized state,
* an implicit realize is invoked by changing the target state
* to Prefetched.
* Both a RealizeCompleteEvent and a PrefetchCompleteEvent are
* posted by the Controller as it
* transitions to the Prefetched state.
*
*
* If a Controller is Prefetching and cannot obtain all of the
* resources it needs to start, it posts a ResourceUnavailableEvent
* instead of a PrefetchCompleteEvent.
* This is a catastrophic error condition
* from which the Controller cannot recover.
*
*
Started State
*
* Once Prefetched, a Controller can enter the
* Started state. A Started Controller's Clock is running and it is processing data.
* A Controller returns to the Prefetched or Realized
* state when it stops because it has reached its stop time, reached the end of the media,
* or because the stop method was invoked.
*
*
* When the Controller moves from the Prefetched
* to the Started state, it posts a StartEvent.
* When it moves from the Started state to a stopped state, it posts a StopEvent.
*
*
* A Controller is a Clock; therefore, syncStart,
* setTimeBase, setMediaTime, and setRate
* are illegal when the Controller is in the Started state.
*
*
*
syncStart
* The only way to start a Controller is to call
* syncStart.
*
*
* It is illegal to call syncStart unless the Controller
* is in the Prefetched state. If syncStart is called before the Controller is Prefetched,
* a NotPrefetchedError is thrown.
* Player defines a start method that relaxes this
* requirement.
*
*
*
*
Freeing the Resources Used by a Controller
*
* Deallocate is used to stop a Controller's resource consumption. For example,
* when Applet.stop is called, deallocate should be called to free the resources that the Controller was using.
* Deallocate stops any resource-consuming activity
* and releases any exclusive-use resources that the Controller
* has acquired.
* Deallocate executes synchronously;
* when deallocate returns, the resources have been released.
*
*
* If the Controller is Unrealized or Realizing, calling deallocate returns it to the
* Unrealized state.
* Otherwise, calling deallocate returns a Controller to the Realized state.
* Regardless of the state that a Controller is in,
* deallocate must relinquish any exclusive-use
* system resources that it holds;
* the only way to guarantee that a Controller is not holding
* resources is to call the deallocate method.
*
*
* It is illegal to call deallocate on a Started Controller.
* You must stop the Controller before
* it can relinquish its resources.
*
*
* When deallocate is called, a Controller posts a special StopEvent,
* DeallocateEvent.
*
* Controller Events
*
* Controller events asynchronously deliver
* information about Controller state changes.
* There are four kinds of notifications:
* life-cycle transition, method acknowledgement,
* state notification, and error notification.
*
*
* To receive events, an object must implement the ControllerListener
* interface and use the addControllerListener method to register its interest in a Controller's events.
* All Controller events are posted to each registered listener.
*
*
* The Controller event mechanism is extensible and
* some Controllers define events other than
* the ones described here.
* For example, the DurationUpdateEvents that a Player posts
* are ControllerEvents.
*
*
* -
TransitionEvent
* -
*
TransitionEvents are posted when a Controller's
* current or target state changes. TransitionEvent
* is subclassed to provide a small set of events
* that are posted for particular kinds of transitions that
* merit special interest. The class name of the event indicates
* either the reason that the event was posted
* (such as EndOfMediaEvent),
* or the particular transition that the event represents (such as
* PrefetchCompleteEvent).
*
*
* In addition to being posted for state transitions,
* the method acknowledgement events RealizeCompleteEvent,
* PrefetchCompleteEvent, StartEvent,
* DeallocateEvent,
* and StopByRequestEvent are always posted to signify method
* completion even if no transition has taken place.
*
*
*
*
*
* -
RealizeCompleteEvent
* -
* Posted when a
Controller moves from
* Realizing to the Realized state,
* or when the realize method is invoked and the
* Controller is already Realized.
*
*
* -
PrefetchCompleteEvent
* -
* Posted when a
Controller moves from Prefetching to
* the Prefetched state, or when the prefetch method is
* invoked and the Controller is already Prefetched.
*
*
* -
StartEvent
* -
* Posted when a
Controller moves from Prefetched to
* Started.
*
*
*
* -
StopEvent
* -
* Posted when a
Controller moves backward. For example, when moving from Prefetched
* to Realized or from Started to Prefetched.
* The reason that a stop event occurs is often important; this information is provided through several subclasses
* of StopEvent.
*
*
*
* -
StopAtTimeEvent
* -
* Posted when a
Controller changes state because it has reached
* its stop time.
*
*
* -
StopByRequestEvent
* -
* Posted when a
Controller changes state because stop is invoked.
* This event is also posted as an acknowledgement to stop requests.
*
*
* -
DeallocateEvent
* -
* Posted when the
deallocate method is invoked, indicating
* a possible state change and the loss of exclusive-use resources.
* The current state is either Unrealized or Realized.
* This event doesn't always indicate a state change. For example, it is posted
* even if deallocate is called on a Realized
* Controller.
*
*
* -
EndOfMediaEvent
* -
* Posted when a
Controller has reached the end of the media.
*
*
* -
ControllerClosedEvent
* - When a
Controller closes it is no longer usable,
* and it will post a ControllerClosedEvent.
* Once this has happened method calls on the Controller
* have undefined behavior.
* A Controller will close for one of two reasons. Either
* the close method was invoked on the Controller, or
* an error has occurred. If a Controller is closed because the
* close method was invoked, it posts a ControllerClosedEvent.
* If an error occurs it posts one of the ControllerErrorEvents.
*
*
*
*
* -
ControllerErrorEvent
* -
* This is the super class of all of the error events that can be posted
* by a
Controller. While this event is rarely posted, you should watch
* for it when processing
* other error events--this is how you can detect implementation-specific
* error events.
*
*
* When a ControllerErrorEvent is posted, it indicates a catastrophic
* error from which the Controller cannot recover. There is no
* recovery mechanism for a Controller once one of these events has
* been posted.
*
*
*
* -
ResourceUnavailableEvent
* -
* This error event is posted during Prefetching or Realizing
* to indicate that the operation has failed because a required resource was
* unavailable.
*
*
* -
DataLostErrorEvent
* -
* This error event is posted when a
Controller has lost data.
*
* -
InternalErrorEvent
* -
* This error event is posted when something goes
* wrong with the
Controller for an implementation-specific reason.
* This usually indicates that there is a problem with the implementation.
*
*
*
* - Status Change Events
*
-
* A small number of status changes occur
* in a
Controller where notification of the change is useful,
* particularly for updating user interface components.
* Notification of these changes is provided through three
* ControllerEvents:
*
*
*
* -
RateChangeEvent
* -
* Posted when the rate of a
Controller changes.
*
* -
StopTimeChangeEvent
* -
* Posted when the stop time of a
Controller changes.
*
* -
MediaTimeSetEvent
* -
* Posted when the media time has been set using
* the
setMediaTime method.
* This event is not periodically posted as media time changes
* due to normal Controller processing and Clock operation.
*
*
*
*
* Controls
*
* A Control is an object that provides a way to
* affect some aspect of a Controller's operation
* in a specific way.
* The Control interface provides access to a
* GUI Component that is
* specific to the particular Control.
* For example, the GainControl interface provides a way
* to display a GUI control that allows the user to change the volume.
*
*
* A Controller makes a collection of Controls
* available that effect the Controller's behavior.
* To access these Controls, you use the getControls
* method, which returns an array of supported Controls.
* If you know the full class or interface name of the Control
* you want, you can use getControl.
*
*
* Since an application using a Controller might not know how
* to use all of the Controls that a Controller
* supports, it can make the functionality available to a user by
* providing access to the Component for
* the Control.
*
*
* @see Player
* @see Control
* @see ControllerListener
* @see ControllerEvent
* @see TransitionEvent
* @see RealizeCompleteEvent
* @see PrefetchCompleteEvent
* @see StartEvent
* @see StopEvent
* @see EndOfMediaEvent
* @see ControllerErrorEvent
* @see DataLostErrorEvent
* @see ResourceUnavailableEvent
* @see InternalErrorEvent
* @see RateChangeEvent
* @see MediaTimeSetEvent
* @see ClockStartedError
* @see NotRealizedError
*
* @version 1.65, 98/03/28
*/
public interface Controller extends Clock, Duration {
/**
* Returned by getStartLatency.
*/
public final static Time LATENCY_UNKNOWN = new Time(Long.MAX_VALUE);
/**
* Returned by getState.
*/
public final static int Unrealized = 100;
/**
* Returned by getState.
*/
public final static int Realizing = 200;
/**
* Returned by getState.
*/
public final static int Realized = 300;
/**
* Returned by getState.
*/
public final static int Prefetching = 400;
/**
* Returned by getState.
*/
public final static int Prefetched = 500;
/**
* Returned by getState.
*/
public final static int Started = 600;
/**
* Get the current state of this Controller.
* The state is an integer constant as defined above.
*
* Note:
* A race condition can occur between
* the return of this method and the execution of
* a state changing method.
*
* @return The Controller's current state.
*/
public int getState();
/**
* Get the current target state of this Controller.
* The state is an integer constant as defined above.
*
* Note:
* A race condition can occur between
* the return of this method and the execution of
* a state changing method.
*
* @return The Controller's current target state.
*/
public int getTargetState();
/**
* Construct the media dependent portions of the Controller.
* This can require examining media data and might
* take some time to complete.
*
* The realize method puts the Controller into the Realizing state and returns immediately.
* When realize is complete and the Controller is in the
* Realized state, the Controller posts a
* RealizeCompleteEvent.
*
*/
public void realize();
/**
* Process as much data as necessary
* to reduce the Controller's start latency to the shortest possible time.
* This typically requires examining media data and takes some
* time to complete.
*
* The prefetch method puts the Controller into the Prefetching state and returns immediately.
* When Prefetching is complete and the Controller is in
* the Prefetched state, the Controller posts
* a PrefetchCompleteEvent.
*
*/
public void prefetch();
/**
* Abort the current operation and cease any activity that
* consumes system resources. If a Controller is not yet
* Realized,
* it returns to the Unrealized state. Otherwise, the Controller
* returns to the Realized state.
*
* It is illegal to call deallocate on a Started Controller.
* A ClockStartedError is thrown if deallocate
* is called and the Controller is in the Started state.
*/
public void deallocate();
/**
*
* Release all resources and cease all activity.
* The close method indicates that the Controller will
* no longer be used, and the Controller can
* shut itself down.
* A ControllerClosedEvent is posted.
* Methods invoked on a closed Controller
* might throw errors.
*/
public void close();
/**
* Get the Controller's start latency in nanoseconds. The start latency represents a
* worst-case estimate of the amount of time it will take
* to present the first frame of data.
*
*
* This method is useful for determining how far in advance the
* syncStart method must be invoked to ensure
* that media will be
* rendered at the specified start time.
*
* For a Controller that has a variable start latency,
* the value returned represents the maximum possible
* start latency. If you call getStartLatency on a Controller that isn't Prefetched
* and getStartLatency returns LATENCY_UNKNOWN, calling
* prefetch and then calling getStartLatency again after the Controller posts
* a PrefetchCompleteEvent might
* return a more accurate estimate.
* If getStartLatency still returns LATENCY_UNKNOWN,
* the start latency is indeterminate and you might not be able to use
* syncStart to
* synchronize the Controller with other Controllers.
*
* Note: In most cases, the value returned by
* getStartLatency will change once the
* Controller is Prefetched.
*
* @return The time it will take before the first frame of media
* can be presented.
*/
public Time getStartLatency();
/**
* Get a list of the Control objects that
* this Controller supports.
* If there are no controls, an array of length zero
* is returned.
*
* @return A list of Controller Controls.
*/
public Control[] getControls();
/**
* Get the Control that supports the
* class or interface specified. The full class
* or interface name should be specified.
* Null is returned if the Control
* is not supported.
*
* @return Control for the class or interface
* name.
*/
public Control getControl(String forName);
/**
* Specify a ControllerListener to which
* this Controller will send events.
* A Controller can have multiple
* ControllerListeners.
*
* @param listener The listener to which the Controller
* will post events.
*/
public void addControllerListener(ControllerListener listener);
/**
* Remove the specified listener from this Controller's
* listener list.
*
* @param listener The listener that has been receiving events from this
* Controller.
*/
public void removeControllerListener(ControllerListener listener);
}