1.0 Overview

Print-friendly Version

TOC  Prev  Next  

• realize
  
  
• prefetch
  
  
• start
  
  
• deallocate
  
  
• stop
  
  
• close
  
  

You can implement the ControllerListener interface to manage these control methods in response to changes in the Player's state. Listening for a Player's state transitions is also important in other cases. For example, you cannot get a Player's components until the Player has been Realized. By listening for a RealizeCompleteEvent you can get the components as soon as the Player is Realized.

5.1 Preparing a Player to Start

5.1.1 Realizing and Prefetching the Player

You call realize to move the Player into the Realizing state and begin the realization process. You call prefetch to move the Player into the Prefetching state and initiate the prefetching process. The realize and prefetch methods are asynchronous and return immediately. When the Player completes the requested operation, it posts a RealizeCompleteEvent or PrefetchCompleteEvent. "Player States" on page 6 describes the operations that a Player performs in each of these states.

A Player in the Prefetched state is prepared to start and its start-up latency cannot be further reduced. However, setting the media time through setMediaTime might return the Player to the Realized state, increasing its start-up latency.

Keep in mind that a Prefetched Player ties up system resources. Because some resources, such as sound cards, might only be usable by one program at a time, this might prevent other Players from starting.

5.1.2 Blocking until a Player is Realized

Note: Be aware that blocking on realize can produce unsatisfactory results. For example, if an applet blocks while a Player is realizing, Applet.start and Applet.stop will not be able to interrupt the process.

To block until a Player is Realized, you could implement a method called blockingRealize that calls realize on your Player and returns when the Player posts a RealizeCompleteEvent and your controllerUpdate method is called. This requires that you implement the ControllerListener interface and register as a listener with the Player. If you register as a listener with multiple Players, your controllerUpdate method needs to determine which Player posted the RealizeCompleteEvent.¹

boolean realized = false;
public synchronized void blockingRealize() 
{
   myPlayer.realize();
   while (!realized) {
      try {
         wait();
      } 
      catch (java.lang.InterruptedException e) {
         status.setText("Interrupted while waiting on 
                         realize...exiting.");
         System.exit(1);
      }
   }
}
public synchronized void controllerUpdate (ControllerEvent 
event)
{
   if (event instanceof RealizeCompleteEvent) {
      realized = true;
      notify();
   } 
   else if (event instanceof EndOfMediaEvent) {
      eomReached = true;
   }
}

5.1.3 Determining a Player's Start-up Latency

The start-up latency reported by getStartLatency might differ depending on the Player's current state. For example, after a prefetch operation, the value returned by getStartLatency is typically smaller. A Controller that can be added to a Player will return a useful value once it is Prefetched. (For more information about added Controllers, see "Using a Player to Manage and Synchronize other Controllers" on page 29.)

5.2 Starting and Stopping a Player

If start is called and the Player has not been prefetched, start performs the realize and prefetch operations as needed to move the Player into the Prefetched state. The Player posts transition events as it moves through each state.

When stop is called on a Player, the Player is considered to be stopped immediately; stop is synchronous. However, a Player can also stop asynchronously when:

• The end of the media stream is reached.
  
  
• The stop time previously set with setStopTime is reached.
  
  
• The Player is data starved.
  
  

5.3 Releasing Player Resources

The deallocate method can only be called on a Stopped Player. To avoid ClockStartedErrors, you should call stop before you call deallocate. Calling deallocate on a Player in the Prefetching or Prefetched state returns it to the Realized state. If deallocate is called while the Player is realizing, the Player posts a DeallocateEvent and returns to the Unrealized state. (Once a Player has been realized, it can never return to the Unrealized state.)

You generally call deallocate when the Player is not being used. For example, an applet should call deallocate as part of its stop method. By calling deallocate , the program can maintain references to the Player, while freeing other resources for use by the system as a whole. (JMF does not prevent a Realized Player that has formerly been Prefetched or Started from maintaining information that would allow it to be started up more quickly in the future.)

When you are finished with a Player (or other Controller) and are not going to use it anymore, you should call close. The close method indicates that the Controller will no longer be used and can shut itself down. Calling close releases all of the resources that the Controller was using and causes the it to cease all activity. When a Controller is closed, it posts a ControllerClosedEvent. A closed Controller cannot be reopened and invoking methods on a closed Controller might generate errors.

5.4 Implementing the ControllerListener Interface

To implement the ControllerListener interface, you need to:

1. Implement the ControllerListener interface in a class.
2. Register that class as a listener by calling addControllerListener on the Controller that you want to receive events from.

if(event instanceof EventType){
...
} else if(event instanceof OtherEventType){
...
}

"Appendix D: ControllerAdapter" on page 73 provides the source for an implementation of ControllerListener that can be easily extended to respond to particular Events.

When you receive events from a Controller, you might need to do some additional processing to ensure that the Controller is in the proper state before calling a control method. For example, before calling any of the methods that are restricted to Stopped Players, you should check the Player's target state by calling getTargetState. If start has been called, the Player is considered to be in the Started state, though it might be posting transition events as it prepares the Player to present media.

Some types of ControllerEvents are stamped with additional state information. For example, the StartEvent and StopEvent classes each define a method that allows you to retrieve the media time at which the event occurred.

TOC  Prev  Next