controller.html

JMF原版英文说明文档

 by a <code>PrefetchCompleteEvent</code> or a <code>ControllerErrorEvent</code>.
 As a convenience, if <code>prefetch</code> is invoked before a
 <code>Controller</code> has reached the <i>Realized</i> state, 
 an implicit <code>realize</code> is invoked by changing the target state
 to <i>Prefetched</i>.
 Both a <code>RealizeCompleteEvent</code> and a <code>PrefetchCompleteEvent</code> are
 posted by the <code>Controller</code> as it
 transitions to the <I>Prefetched</I> state.
 <p>

 If a <code>Controller</code> is <i>Prefetching</i> and cannot obtain all of the
 resources it needs to start, it posts a <code>ResourceUnavailableEvent</code>
 instead of a <code>PrefetchCompleteEvent</code>. 
 This is a catastrophic error condition
 from which the <code>Controller</code> cannot recover.

 <h3>Started State</h3>

 Once <i>Prefetched</i>, a <code>Controller</code> can enter the
 <i>Started</i> state. A <I>Started</I>&nbsp;<CODE>Controller's</CODE>&nbsp;<CODE>Clock</CODE> is running and is processing data.
 A <code>Controller</code> returns to the <i>Prefetched</i> or <i>Realized</i>
 state when it stops because it has either reached its stop time, reached the end of the media,
 or because the <code>stop</code> method was invoked.
 <p>

 When the <code>Controller</code> moves from the <i>Prefetched</i>
 to the <i>Started</i> state, it posts a <code>StartEvent</code>. 
 When it moves from the <i>Started</i> state to a stopped state, it posts a <code>StopEvent</code>.
 <p>
 
 A <code>Controller</code> is a <code>Clock</code>; therefore, <code>syncStart</code>,
 <code>setTimeBase</code>, <code>setMediaTime</code>, and <code>setRate</code>
 are illegal when the <code>Controller</code> is in the <i>Started</i> state.
 <p>

 <h4>syncStart</h4>
 The only way to start a <code>Controller</code> is to call
 <code>syncStart</code>.
 <p>

 It is illegal to call <code>syncStart</code> unless the <code>Controller</code> 
 is in the <i>Prefetched</i> state. If <code>syncStart</code> is called before the <code>Controller</code> is <I>Prefetched</I>,
  a <code>NotPrefetchedError</code> is thrown.
 <code>Player</code> defines a <code>start</code> method that relaxes this
 requirement. 
 <p>
 
 
 <h3>Freeing the Resources Used by a Controller</h3>

 <code>Deallocate</code> is used to stop a  <code>Controller's</code> resource consumption. For example, 
 when <code>Applet.stop</code> is called, <code>deallocate</code> should be called to free the resources that were used by the <code>Controller</code>.
 <code>Deallocate</code> stops any resource-consuming activity
 and releases any exclusive-use resources that the <code>Controller</code>
 has acquired.
 <code>Deallocate</code> executes synchronously;
 when <code>deallocate</code> returns, the resources have been released.
 <p>

 If the <code>Controller</code> is <i>Unrealized</i> or <i>Realizing</i>, calling <code>deallocate</code> returns it to the
 <i>Unrealized</i> state. 
 Otherwise, calling <code>deallocate</code> returns a <code>Controller</code> to  the <i>Realized</i> state.
 Regardless of the state that a <code>Controller</code> is in,
 <code>deallocate</code> must relinquish any exclusive-use
 system resources that it holds;
 the only way to guarantee that a <code>Controller</code> is not holding
 resources is to call the <code>deallocate</code> method.
 <p>
 
 It is illegal to call <code>deallocate</code> on a  <i>Started</i>&nbsp;<code>Controller</code>. 
 You must stop the <code>Controller</code> before
 it can relinquish its resources.
 <p>

 When <code>deallocate</code> is called,  a <code>Controller</code> posts a special <code>StopEvent</code>,
 <code>DeallocateEvent</code>.
 
 <a name="CE"><h2>Controller Events</h2></a>

 <code>Controller</code> events asynchronously deliver
 information about <code>Controller</code> state changes.
 There are four kinds of notifications:
 life cycle transition, method acknowledgement, 
 state notification, and error notification.
 <p>

 To receive events, an object must implement the <code>ControllerListener</code>
 interface and use the <code>addControllerListener</code> method to register its interest in a <code>Controller's</code> events. 
 All <code>Controller</code> events are posted to each registered listener.
 <p>

 The <code>Controller</code> event mechanism is extensible and 
 some <code>Controllers</code> define events other than 
 the ones described here.
 For example, the <code>DurationUpdateEvents</code> posted by a <code>Player</code> 
 are <code>ControllerEvents</code>.

 <dl>
 <dt> <code>TransitionEvent</code>
 <dd>
 <code>TransitionEvents</code> are posted when a <code>Controller's</code>
 current or target state changes. <code>TransitionEvent</code>
 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 <code>EndOfMediaEvent</code>),
 or the particular transition representedby the event (such as
 <code>PrefetchCompleteEvent</code>).
 <p>

 In addition to being posted for state transitions,
 the method acknowledgement events <code>RealizeCompleteEvent</code>,
 <code>PrefetchCompleteEvent</code>, <code>StartEvent</code>,
 <code>DeallocateEvent</code>,
 and <code>StopByRequestEvent</code> are always posted to signify method
 completion even if no transition has taken place.
 <p>
 
 </dd>

 <dl>
 <dt> <code>RealizeCompleteEvent</code>
 <dd>
 Posted when a <code>Controller</code> moves from the
 <i>Realizing</i> to the <i>Realized</i> state,
 or when the <code>realize</code> method is invoked and the
 <code>Controller</code> is already <i>Realized</i>.
 </dd>

 <dt> <code>PrefetchCompleteEvent</code>
 <dd>
 Posted when a <code>Controller</code> moves from the <i>Prefetching</i> to
 the <i>Prefetched</i> state, or when the <code>prefetch</code> method is
 invoked and the <code>Controller</code> is already <i>Prefetched</i>.
 </dd>

 <dt> <code>StartEvent</code>
 <dd>
 Posted when a <code>Controller</code> moves from the <i>Prefetched</i> to
 the <i>Started</i> state.
 <p>
 </dd>

 <dt> <code>StopEvent</code>
 <dd>
 Posted when a <code>Controller</code> moves backwards, for example, when moving from  <i>Prefetched</i>
 to <i>Realized</i> or from <i>Started</i> to <i>Prefetched</i>.
 The <i>reason</i> that a stop event occurs is often important; this information is provided through several subclasses
 of <code>StopEvent</code>.
 </dd>

 <dl>
 <dt> <code>StopAtTimeEvent</code>
 <dd>
 Posted when a <code>Controller</code> changes state because it has reached
 its stop time.
 </dd>

 <dt> <code>StopByRequestEvent</code>
 <dd>
 Posted when a <code>Controller</code> changes state because <code>stop</code> is invoked.
 This event is also posted as an acknowledgement to <code>stop</code> requests.
 </dd>

 <dt> <code>DeallocateEvent</code>
 <dd>
 Posted when the <code>deallocate</code> method is invoked, indicating
 a possible state change and the loss of exclusive-use resources.
 The current state is either <i>Unrealized</i> or <i>Realized</i>.
 This event doesn't always indicate a state change. For example, it is posted
 even if <code>deallocate</code> is called on a <i>Realized</i>&nbsp;
 <code>Controller</code>.
 </dd>

 <dt> <code>EndOfMediaEvent</code>
 <dd>
 Posted when a <code>Controller</code> has reached the end of the media.
 </dd>

 <dt> <CODE>ControllerClosedEvent</CODE>
 <dd> When a <CODE>Controller</CODE> closes it is no longer usable,
 and it will post a <CODE>ControllerClosedEvent</CODE>.
 Once this has happened, method calls on the <CODE>Controller</CODE>
 have undefined behavior.
 A <CODE>Controller</CODE> will close for one of two reasons; either
 the <CODE>close</CODE> method was invoked on the <CODE>Controller</CODE>, or
 an error has occurred. If a <CODE>Controller</CODE> is closed because the
 <CODE>close</CODE> method was invoked, it posts a <CODE>ControllerClosedEvent</CODE>.
 If an error occurs it posts one of the <CODE>ControllerErrorEvents</CODE>.
 </dd>
 </dl>
 </dl>

 <dt> <code>ControllerErrorEvent</code>
 <dd>
 This is the super class of all of the error events that can be posted
 by a <code>Controller</code>. 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.
 <p>

 When a <code>ControllerErrorEvent</code> is posted, it indicates a catastrophic
 error from which the <code>Controller</code> cannot recover.  There is no
 recovery mechanism for a <code>Controller</code> once one of these events has
 been posted.
 <p>

 <dl>
 <dt> <code>ResourceUnavailableEvent</code>
 <dd>
 This error event is posted during <i>Prefetching</i> or <i>Realizing</i>
 to indicate that the operation failed because a required resource was
 unavailable.
 </dd>
 
 <dt> <code>DataLostErrorEvent</code>
 <dd>
 This error event is posted when a <code>Controller</code> has lost data.
 </dd>
 <dt> <code>InternalErrorEvent</code>
 <dd>
 This error event is posted when something goes
 wrong with the <code>Controller</code> for an implementation-specific reason. 
 This usually indicates that there is a problem with the implementation.
 </dd>
 </dl>

 <dt> Status Change Events
 <dd>
 A small number of status changes occur
 in a <code>Controller</code> where notification of the change is useful,
 particularly for updating user interface components.
 Notification of these changes is provided through three
 <code>ControllerEvents</code>:
 </dd>

 <dl>
 <dt> <code>RateChangeEvent</code>
 <dd>
 Posted when the rate of a <code>Controller</code> changes.
 
 <dt> <code>StopTimeChangeEvent</code>
 <dd>
 Posted when the stop time of a <code>Controller</code> changes.
 
 <dt> <code>MediaTimeSetEvent</code>
 <dd>
 Posted when the media time has been set using
 the <code>setMediaTime</code> method. 
  This event is <i>not</i> periodically posted when media time changes 
 due to normal <code>Controller</code> processing and <code>Clock</code> operation.
 </dl>

 </dl>

 <h2>Controls</h2>

 A <code>Control</code> is an object that provides a way to
 affect some aspect of a Controller's operation
 in a specific way. 
 The <code>Control</code> interface provides access to a
 GUI <code>Component</code> that is
 specific to the particular <code>Control</code>.
 For example, the <code>GainControl</code> interface provides a way
 to display a GUI control that allows the user to change the volume.
 <p>

 A <code>Controller</code> makes available a collection of <code>Controls</code>
 that influence the <code>Controller's</code> behavior.
 To access these <code>Controls</code>, use the <code>getControls</code>
 method, which returns an array of supported <code>Controls</code>.
 If you know the full class or interface name of the desired <code>Control</code>,
 you can use <code>getControl</code>.
 <p>

 Since an application using a <code>Controller</code> might not know how
 to use all of the <code>Controls</code> supported by a <code>Controller</code>,
 it can make the functionality available to a user by
 providing access to the <code>Component</code> for
 the <code>Control</code>.
 <p>
<P>
<DL>
<DT><B>See Also: </B><DD><A HREF="../../javax/media/Player.html"><CODE>Player</CODE></A>, 
<A HREF="../../javax/media/Control.html"><CODE>Control</CODE></A>, 
<A HREF="../../javax/media/ControllerListener.html"><CODE>ControllerListener</CODE></A>, 
<A HREF="../../javax/media/ControllerEvent.html"><CODE>ControllerEvent</CODE></A>, 
<A HREF="../../javax/media/TransitionEvent.html"><CODE>TransitionEvent</CODE></A>, 
<A HREF="../../javax/media/RealizeCompleteEvent.html"><CODE>RealizeCompleteEvent</CODE></A>, 
<A HREF="../../javax/media/PrefetchCompleteEvent.html"><CODE>PrefetchCompleteEvent</CODE></A>, 
<A HREF="../../javax/media/StartEvent.html"><CODE>StartEvent</CODE></A>, 
<A HREF="../../javax/media/StopEvent.html"><CODE>StopEvent</CODE></A>,