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