javax.media
Interface Processor


public abstract interface Processor
extends Player

The Processor interface is a module for processing and controlling time based media data. Processor extends Player. Unlike a Player which processes data as a "black box" and renders data only to pre-set destinations, a Processor supports a programmatic interface to control the processing of the media data and provides access to the output data streams.

Programming the Processor

The processing of the media inside a Processor is defined by three stages:

Both the data transcoding and multiplexing are programmable. Per-track data transcoding is done via the TrackControl interface. Multiplexing is controlled via the setContentDescriptor method. Programming the Processor can be done in the Processor's Configured state. Any programming done before the Processor is configured will result in NotConfiguredErrors.

Getting the Output from a Processor

The processed output data streams from a Processor can be obtained from the output DataSource. The output DataSource provides the gateway for the output data to be read. Output DataSources from a Processor are of type PushDataSource, PushBufferDataSource, PullDataSource or PullBufferDataSource depending on the implementation of the Processor.

The Processor will throw a NotRealizedError if getDataOutput is called on a Processor that has not yet been realized.

How a Processor differs from a Controller

State Transitions

Processor extends the state transition cycle of the Controller by adding the Configuring and Configured states. The state transitions of a Processor are as follows: Unrealized, Configuring, Configured, Realizing, Realized, Prefetching, Prefetched, Started

The purpose of the Configured state is to further refine the Controller's realize step. It essentially subdivides the realize step into two phases:

In between these two steps, the user can program the Processor to carry out the user-desired processing on the media stream.

During the Configuring state, a Processor goes through the necessary steps to determine from the input DataSource how to build the TrackControls . This may mean parsing the input file to determine the individual media tracks within the file, or connecting to the capturing device to determine its capabilities. A ConfigureCompleteEvent is sent when the Configured state is reached.

When Configured, the getTrackControl call will return the TrackControl objects so the user can program the individual tracks. The setContentDescriptor call allows the user to specify format of the output content. After the programming has been completed, realize should be called so the Processor can continue and complete its construction.

Once the Processor is realized, any attempt to re-program the Processor via the TrackControls or the setContentDescriptor call is not guaranteed to work since that could involve reconstructing the internals of the Processor.

It is legal to call realize on the Processor when the Processor is still in the Unrealized state. This will cause the Processor to transition from Unrealized to Realized, going through the intermediate states of Configuring, Configured and Realizing. However, by doing this the user will miss the opportunity to program the Processor during the Configured state. If the user does not program the TrackControls, the Processor is free to implement its default behavior.

Deallocate changes the state of the Processor in much the same way as the Controller except that:

If the Processor is in the Configuring or Configured state, deallocate will return the Processor to the Unrealized state.

Using the Processor as a Player

Some implementations of a Processor can be used as a Player. In that case, the TrackControl will provide additional information and control for the individual tracks for the Player. But the Processor will not produce an output DataSource. To use a Processor as a Player, call setContentDescriptor(null).

Since:
JMF 2.0
See Also:
Controller, Player, TrackControl

Field Summary
static int Configured
          Returned by getState
static int Configuring
          Returned by getState
 
Fields inherited from class javax.media.Controller
LATENCY_UNKNOWN, Prefetched, Prefetching, Realized, Realizing, Started, Unrealized
 
Fields inherited from class javax.media.Clock
RESET
 
Fields inherited from class javax.media.Duration
DURATION_UNBOUNDED, DURATION_UNKNOWN
 
Method Summary
 void configure()
          Configure the Processor.
 ContentDescriptor getContentDescriptor()
          Return the output content-type.
 DataSource getDataOutput()
          Return the output DataSource of the Processor.
 ContentDescriptor[] getSupportedContentDescriptors()
          Return all the content-types which this Processor's output supports.
 TrackControl[] getTrackControls()
          Return the tracks in the media.
 ContentDescriptor setContentDescriptor(ContentDescriptor outputContentDescriptor)
          Set the output content-type.
 
Methods inherited from interface javax.media.Player
addController, getControlPanelComponent, getGainControl, getVisualComponent, removeController, start
 
Methods inherited from interface javax.media.MediaHandler
setSource
 
Methods inherited from interface javax.media.Controller
addControllerListener, close, deallocate, getControl, getControls, getStartLatency, getState, getTargetState, prefetch, realize, removeControllerListener
 
Methods inherited from interface javax.media.Clock
getMediaNanoseconds, getMediaTime, getRate, getStopTime, getSyncTime, getTimeBase, mapToTimeBase, setMediaTime, setRate, setStopTime, setTimeBase, stop, syncStart
 
Methods inherited from interface javax.media.Duration
getDuration
 

Field Detail

Configuring

public static final int Configuring
Returned by getState

Configured

public static final int Configured
Returned by getState
Method Detail

configure

public void configure()
Configure the Processor. The Processor gathers information regarding the data it is going to process. The configure method puts the Processor into the Configuring state and returns immediately. When configure is complete and the Processor is in the Configured state, the Processor posts a ConfigureCompleteEvent.

getTrackControls

public TrackControl[] getTrackControls()
                                throws NotConfiguredError
Return the tracks in the media. This method can only be called after the Processor has been configured. A NotConfiguredError is thrown if getTrackControls is called and the Processor is in the Unrealized or Configuring states.
Returns:
An array of the tracks in the media. An emtpy array is returned if there is no TrackControl available for this Processor.
Throws:
NotConfiguredError - if the Processor is Unrealized.

getSupportedContentDescriptors

public ContentDescriptor[] getSupportedContentDescriptors()
                                                   throws NotConfiguredError
Return all the content-types which this Processor's output supports. The Processor builds the ContentDescriptor array according to the input DataSource attached to the Processor and according to the codecs and multiplexers installed in the system.
Returns:
An array of the the content-types supported by the Processor.
Throws:
NotConfiguredError - if the Processor is Unrealized.

setContentDescriptor

public ContentDescriptor setContentDescriptor(ContentDescriptor outputContentDescriptor)
                                       throws NotConfiguredError
Set the output content-type.

If setContentDescriptor is not called, the output DataSource by default will be set to raw output (new ContentDescriptor(ContentDescriptor.RAW)). The source streams from the DataSource will be the demultiplexed tracks from the input source.

Parameters:
outputContentDescriptor - the content-type of the output.
Returns:
null if the given content descriptor cannot be set; otherwise it returns a content descriptor that most closely matches the specified one.
Throws:
NotConfiguredError - if the Processor is Unrealized.

getContentDescriptor

public ContentDescriptor getContentDescriptor()
                                       throws NotConfiguredError
Return the output content-type.
Returns:
The current output content-type.
Throws:
NotConfiguredError - if the Processor is Unrealized.

getDataOutput

public DataSource getDataOutput()
                         throws NotRealizedError
Return the output DataSource of the Processor. The output DataSource is the output connection of the Processor through which it supplies the processed streams. The output DataSource of the Processor is in the connected state when returned by the processor
Throws:
NotRealizedError - if the Processor is not realized.