javax.microedition.amms
Interface MediaProcessor

All Superinterfaces:

javax.microedition.media.Controllable

public interface MediaProcessor

extends javax.microedition.media.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 UNREALIZED MediaProcessor 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.

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.

Method	Initial state
	UNREALIZED	REALIZED	STARTED	STOPPED
No method called	Nothing happens	Nothing happens	Processing is in progress On success: Posts PROCESSING_COMPLETED → UNREALIZED On failure: Posts PROCESSING_ERROR → REALIZED	Nothing happens
setInput()	Sets the input. If output is already set: Posts PROCESSOR_REALIZED → REALIZED	Updates input	Throws IllegalStateException	Throws IllegalStateException
setOutput()	Sets the output. If input is already set: Posts PROCESSOR_REALIZED → REALIZED	Updates output	Throws IllegalStateException	Throws IllegalStateException
complete()	Throws IllegalStateException	Tries to start processing. On failure: Throws MediaException On success: Posts PROCESSING_STARTED → STARTED Method then blocks until processing is completed. If processing fails: Throws MediaException Posts PROCESSING_ERROR → REALIZED If processing succeeds: Posts PROCESSING_COMPLETED → UNREALIZED	Waits for processing to finish. If processing succeeds: Posts PROCESSING_COMPLETED → UNREALIZED If processing fails: Throws MediaException Posts PROCESSING_ERROR → REALIZED	Tries to resume processing. On failure: Throws MediaException On success: Posts PROCESSING_STARTED → STARTED Method then blocks until processing is completed. If processing succeeds: Posts PROCESSING_COMPLETED → UNREALIZED If processing fails: Throws MediaException Posts PROCESSING_ERROR → REALIZED
start()	Throws IllegalStateException	Tries to start processing. On success: Posts PROCESSING_STARTED → STARTED On failure: Throws MediaException	Nothing happens	Tries to resume processing. On success: Posts PROCESSING_STARTED → STARTED On failure: Throws MediaException
stop()	Nothing happens	Nothing happens	Tries to pause processing. On success: Posts PROCESSING_STOPPED → STOPPED On failure: Throws MediaException	Nothing happens
abort()	Nothing happens	Nothing happens	Tries to abort processing. On success: Resets input and output. Posts PROCESSING_ABORTED → UNREALIZED On failure: Throws MediaException	Tries to abort processing. On success: Resets input and output. Posts PROCESSING_ABORTED → UNREALIZED On failure: Throws MediaException
getProgress()	Returns 0	Returns 0	Returns % of work complete or UNKNOWN	Returns % of work complete or UNKNOWN

Stream Handling

Input to a MediaProcessor is provided via InputStream and processed media is written to an OutputStream.

The MediaProcessor can read data from an InputStream when a setInput method is called or any time between the call to setInput and the start of the processing. The MediaProcessor reads some data in before processing in order to setup values of associated controls. For example, the header of the media can contain information about the media format and that information must be available to the application via FormatControl.

In some cases, not all information about the processed media is available to the application before the processing starts. Since the InputStream does not allow seeking, the MediaProcessor must buffer all data it reads before processing. If the size of the processed media is large and the headers and/or metadata are at the end of the stream, it is not possible to read and buffer the whole media before processing. FormatControl.setMetadataOverride(boolean) can be used to choose whether the metadata set by the application overrides the metadata in the processed file when the two have contradictions.

The MediaProcessor will write data to an OutputStream only once the processing is started. When the processing is completed, the MediaProcessor calls InputStream.close() and OutputStream.close() before sending a PROCESSING_COMPLETED event. When the abort method is called MediaProcessor also closes the streams before sending PROCESSING_ABORTED event.

Processing images

A MediaProcessor to process Image objects (that is, an image processor) is created by specifying input type "image/raw" to GlobalManager.createMediaProcessor. The default output type for an image processor is implementation-specific, and the input data can only be set via setInput(java.lang.Object). A MediaException is thrown if an attempt is made to call setInput(java.io.InputStream, int).

Conversely, a MediaProcessor created to process files will only accept input set via setInput(InputStream, int). Any attempt to use setInput(Object) will cause a MediaException to be thrown.

Example

Below is shown a simple example where a JPEG image is converted into a monochrome image.

 MediaProcessor mp = GlobalManager.createMediaProcessor("image/jpeg");

 InputStream inputStream = ... // create a InputStream that contains the source image
 OutputStream outputStream = ... // create a OutputStream that will receive the resulting image
 mp.setInput(inputStream);
 mp.setOutput(outputStream);
 
 // Define effects to be applied during processing
 ImageEffectControl imageEffect = 
      (ImageEffectControl)mp.getControl("javax.microedition.amms.control.imageeffect.ImageEffectControl");

 imageEffect.setPreset("monochrome");
 
 // Set output format
 ImageFormatControl fc = (ImageFormatControl)mp.getControl("javax.microedition.amms.control.ImageFormatControl");
 fc.setFormat("image/jpeg");
 fc.setParameter("quality", 80);
 
 // Do the actual processing. If you do not want to use a blocking call, 
 // use start() and MediaProcessorListener.
 mp.complete();
 
 

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(java.io.InputStream input, int length) Sets the input of the media processor.
void	setInput(java.lang.Object image) Sets the input of the media processor as an Image.
void	setOutput(java.io.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

public 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

UNREALIZED

public 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

REALIZED

public 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

STARTED

public static final int STARTED

The state of the MediaProcessor indicating that processing has already begun.

See Also:

Constant Field Values

STOPPED

public static final int STOPPED

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

See Also:

Constant Field Values

Method Detail

setInput

public void setInput(java.io.InputStream input,
                     int length)
              throws javax.microedition.media.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:

java.lang.IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state

javax.microedition.media.MediaException - if input can not be given as a stream

java.lang.IllegalArgumentException - if input is null

java.lang.IllegalArgumentException - if length < 1 and length != UNKNOWN

setInput

public void setInput(java.lang.Object image)
              throws javax.microedition.media.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:

java.lang.IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state

javax.microedition.media.MediaException - if input can not be given as an image

java.lang.IllegalArgumentException - if the image is not an Image object

setOutput

public void setOutput(java.io.OutputStream output)

Sets the output of the media processor.

Parameters:

output - the OutputStream to be used as output

Throws:

java.lang.IllegalArgumentException - if output is null

java.lang.IllegalStateException - if the MediaProcessor was not in UNREALIZED or REALIZED state

start

public void start()
           throws javax.microedition.media.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:

java.lang.IllegalStateException - if the MediaProcessor was in UNREALIZED state

javax.microedition.media.MediaException - if the MediaProcessor could not be started

stop

public void stop()
          throws javax.microedition.media.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:

javax.microedition.media.MediaException - if the MediaProcessor could not be stopped

complete

public void complete()
              throws javax.microedition.media.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:

java.lang.IllegalStateException - if the MediaProcessor was in UNREALIZED state

javax.microedition.media.MediaException - if completing the processing failed either because the processing couldn't be started or because an error occured during processing

abort

public 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. A PROCESSING_ABORTED event is posted and the MediaProcessor is moved into UNREALIZED state.

Ignored if the MediaProcessor was in REALIZED or UNREALIZED state.

addMediaProcessorListener

public 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.

removeMediaProcessorListener

public 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.

getProgress

public 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.

getState

public int getState()

Get the state of the MediaProcessor

Returns:

state of the MediaProcessor