javax.microedition.amms
Interface MediaProcessor

All Superinterfaces:
Controllable

public interface MediaProcessor
extends Controllable

MediaProcessor is an interface designed to post-process different media types. It is intended that a MediaProcessor generally exposes various EffectControls (to configure the processing behavior) and FormatControls (to set the output format). At least one object implementing the FormatControl can be fetched from a MediaProcessor.

To retrieve a MediaProcessor, call GlobalManager.createMediaProcessor(java.lang.String).

MediaProcessor states

MediaProcessor has four different states: UNREALIZED, REALIZED, STARTED and STOPPED. In the UNREALIZED state, the input and output of the processor must be specified and various Controls may be used to specify different aspects of the processing.

The MediaProcessor enters the REALIZED state when the input and output have been set. Controls can still be used in the REALIZED state. Once REALIZED, the MediaProcessor can be started, causing it to enter the STARTED state. An UNREALIZEDMediaProcessor cannot be started.

Once in the STARTED state, processing has begun. Processing may be paused by stopping the MediaProcessor, at which point it enters the STOPPED state. Starting the MediaProcessor again will cause it to re-enter the STARTED state, resuming its processing where it left off.

If processing completes successfully, the MediaProcessor returns to the UNREALIZED state, at which point both the input and output must be set again before another processing task can be started. Any applied effects will, however, remain.

If processing fails, the MediaProcessor returns to the REALIZED state. Possible actions then depend on the implementation and the reason for the failure.

In the STARTED or STOPPED states, the details of the processing should not be changed via its controls. If the details are changed, it is unspecified when the changes will actually be effective. They may occur immediately; the latest they might take effect is when the MediaProcessor returns to the REALIZED state again.

getControl and getControls methods can be called in all states.

The following diagram depicts the most important state transitions in the lifecycle of the MediaProcessor as a directed graph. For clarity, the diagram does not cover all possible transitions and exceptions.

The following table details the behavior of each method in each MediaProcessor state. STATE indicates that the MediaProcessor enters the specified state.

MethodInitial stateUNREALIZEDREALIZEDSTARTEDSTOPPEDNo method calledNothing happensNothing happens Processing is in progressOn success: Posts PROCESSING_COMPLETEDUNREALIZEDOn failure: Posts PROCESSING_ERRORREALIZEDNothing happenssetInput() Sets the input. If output is already set: Posts PROCESSOR_REALIZEDREALIZEDUpdates input

Since:
BlackBerry API 5.0.0

Field Summary
static int REALIZED
          The state of the MediaProcessor indicating that it has all the information it needs to begin processing, but no processing is currently in progress.
static int STARTED
          The state of the MediaProcessor indicating that processing has already begun.
static int STOPPED
          The state of the MediaProcessor indicating that processing was started but has been stopped temporarily.
static int UNKNOWN
          Constant telling that either the length of the media or progress of the processing is unknown.
static int UNREALIZED
          The state of the MediaProcessor indicating that it is not ready to begin processing because the input and/or output have not yet been set.
 
Method Summary
 void abort()
          Aborts the processing even if the processing was not complete.
 void addMediaProcessorListener(MediaProcessorListener mediaProcessorListener)
          Add a MediaProcessorListener that will receive events generated by this MediaProcessor.
 void complete()
          Waits until the processing has been completed.
 int getProgress()
          Get an estimated percentage of work that has been done.
 int getState()
          Get the state of the MediaProcessor
 void removeMediaProcessorListener(MediaProcessorListener mediaProcessorListener)
          Remove a MediaProcessorListener that was receiving events generated by this MediaProcessor.
 void setInput(InputStream input, int length)
          Sets the input of the media processor.
 void setInput(Object image)
          Sets the input of the media processor as an Image.
 void setOutput(OutputStream output)
          Sets the output of the media processor.
 void start()
          Starts processing.
 void stop()
          Stops processing temporarily.
 
Methods inherited from interface javax.microedition.media.Controllable
getControl, getControls
 



Field Detail

UNKNOWN

static final int UNKNOWN
Constant telling that either the length of the media or progress of the processing is unknown.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

UNREALIZED

static final int UNREALIZED
The state of the MediaProcessor indicating that it is not ready to begin processing because the input and/or output have not yet been set.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

REALIZED

static final int REALIZED
The state of the MediaProcessor indicating that it has all the information it needs to begin processing, but no processing is currently in progress.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

STARTED

static final int STARTED
The state of the MediaProcessor indicating that processing has already begun.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

STOPPED

static final int STOPPED
The state of the MediaProcessor indicating that processing was started but has been stopped temporarily.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

setInput

void setInput(InputStream input,
              int length)
              throws MediaException
Sets the input of the media processor.

Parameters:
input - the InputStream to be used as input
length - the estimated length of the processed media in bytes. Since the input is given as an InputStream, the implementation cannot find out what is the length of the media until it has been processed. The estimated length is used only when the progress method is used to query the progress of the processing. If the length is not known, UNKNOWN should be passed as a length.
Throws:
IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state
MediaException - if input can not be given as a stream
IllegalArgumentException - if input is null
IllegalArgumentException - if length < 1 and length != UNKNOWN
Since:
BlackBerry API 5.0.0

setInput

void setInput(Object image)
              throws MediaException
Sets the input of the media processor as an Image.

Setting the input as an Image allows use of raw image data in a convenient way. It also allows converting Images to image files. image is an UI Image of the implementing platform. For example, in MIDP image is javax.microedition.lcdui.Image object.

Mutable Image is allowed as an input but the behavior is unspecified if the Image is changed during processing.

Parameters:
image - the Image object to be used as input
Throws:
IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state
MediaException - if input can not be given as an image
IllegalArgumentException - if the image is not an Image object
Since:
BlackBerry API 5.0.0

setOutput

void setOutput(OutputStream output)
Sets the output of the media processor.

Parameters:
output - the OutputStream to be used as output
Throws:
IllegalArgumentException - if output is null
IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state
Since:
BlackBerry API 5.0.0

start

void start()
           throws MediaException
Starts processing. If the MediaProcessor is in STARTED state, the call is ignored. Upon calling this method, the MediaProcessor either throws a MediaException or moves to STARTED state and posts PROCESSING_STARTED event to MediaProcessorListeners.

After the processing has been completed, a PROCESSING_COMPLETED event will be delivered and the MediaProcessor will move into the UNREALIZED state.

Throws:
IllegalStateException - if the MediaProcessor was in UNREALIZED state
MediaException - if the MediaProcessor could not be started
Since:
BlackBerry API 5.0.0

stop

void stop()
          throws MediaException
Stops processing temporarily. If the MediaProcessor is in a UNREALIZED, REALIZED or STOPPED state, the call is ignored. Otherwise, the MediaProcessor either throws a MediaException or moves to STOPPED state and posts PROCESSING_STOPPED event to MediaProcessorListeners.

Throws:
MediaException - if the MediaProcessor could not be stopped
Since:
BlackBerry API 5.0.0

complete

void complete()
              throws MediaException
Waits until the processing has been completed. If the MediaProcessor is not in STARTED state, calls start implicitly causing PROCESSING_STARTED event to be posted to MediaProcessorListeners. Otherwise, waits until either a MediaException is thrown and PROCESSING_ERROR is posted or a PROCESSING_COMPLETED event has been posted. After this method returns, the MediaProcessor is in UNREALIZED state if the processing was succesful or in REALIZED state if the processing failed.

Throws:
IllegalStateException - if the MediaProcessor was in UNREALIZED state
MediaException - if completing the processing failed either because the processing couldn't be started or because an error occured during processing
Since:
BlackBerry API 5.0.0

abort

void abort()
Aborts the processing even if the processing was not complete. Any bytes that were written to output may not be reasonable and should be discarded. When this method returns, a PROCESSING_ABORTED event has been posted and the MediaProcessor has been moved into UNREALIZED state.

Ignored if the MediaProcessor was in REALIZED or UNREALIZED state.

Since:
BlackBerry API 5.0.0

addMediaProcessorListener

void addMediaProcessorListener(MediaProcessorListener mediaProcessorListener)
Add a MediaProcessorListener that will receive events generated by this MediaProcessor.

Parameters:
mediaProcessorListener - the listener to be added. If null, the request will be ignored.
Since:
BlackBerry API 5.0.0

removeMediaProcessorListener

void removeMediaProcessorListener(MediaProcessorListener mediaProcessorListener)
Remove a MediaProcessorListener that was receiving events generated by this MediaProcessor.

Parameters:
mediaProcessorListener - the listener to be removed. If the listener does not exist or is null, the request will be ignored.
Since:
BlackBerry API 5.0.0

getProgress

int getProgress()
Get an estimated percentage of work that has been done.

Returns:
0, if the MediaProcessor is in UNREALIZED or REALIZED state amount of work completed (0 - 100%) if MediaProcessor is in STARTED or STOPPED states UNKNOWN, if the estimation cannot be calculated.
Since:
BlackBerry API 5.0.0

getState

int getState()
Get the state of the MediaProcessor

Returns:
state of the MediaProcessor
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.