net.rim.plazmic.mediaengine
Class MediaPlayer

java.lang.Object
  |
  +--net.rim.plazmic.mediaengine.MediaPlayer

public class MediaPlayer

extends Object

A core class of the MediaEngine API that provides all necessary methods for the playback of the media types supported by the Media Engine.

MediaPlayer functions in the following states: UNREALIZED, REALIZED, and STARTED.

The default state is UNREALIZED. In this state MediaPlayer requires minimum resources. A MediaPlayer enters REALIZED state when the media is ready for playback by calling setMedia(). The transition from UNREALIZED to REALIZED might take a long time as MediaPlayer loads the media and allocates all required resources.

MediaPlayer moves from the REALIZED state to STARTED by calling start(). From the STARTED state it can enter REALIZED state by calling stop() or setMedia(). MediaPlayer can enter UNREALIZED state once again on close().

Since:

JDE 3.7.0

See Also:

MediaManager

Field Summary

static String	ID Identifier of the player used when calling MediaServices#getService
static int	REALIZED Represents the REALIZED state.
static int	STARTED Represents the STARTED state.
static int	UNREALIZED Represents the UNREALIZED state.

Constructor Summary

MediaPlayer()
The default constructor.

Method Summary

void	addMediaListener(MediaListener l) Registers a listener with the MediaPlayer.
void	close() Closes an instance of MediaPlayer.
Object	getMedia() Returns current media object.
long	getMediaTime() Returns the current media time.
int	getState() Returns the current state.
Object	getUI() Returns platform specific UI component into which the media will be loaded.
void	removeMediaListener(MediaListener l) Unregisters a listener from the MediaPlayer.
void	setMedia(Object media) Sets the already constructed media for the playback.
void	setMediaTime(long time) Sets the media time starting from 0.
void	start() Starts playback of the media content.
void	stop() Stops playback of the media.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNREALIZED

public static final int UNREALIZED

Represents the UNREALIZED state.

Since:

JDE 3.7.0

REALIZED

public static final int REALIZED

Represents the REALIZED state.

Since:

JDE 3.7.0

STARTED

public static final int STARTED

Represents the STARTED state.

Since:

JDE 3.7.0

ID

public static final String ID

Identifier of the player used when calling MediaServices#getService

Since:

JDE 4.1.0

Constructor Detail

MediaPlayer

public MediaPlayer()

The default constructor.

Since:

JDE 3.7.0

Method Detail

getState

public int getState()

Returns the current state.

One of UNREALIZED, REALIZED, STARTED.

Returns:

An integer representing the state.

Since:

JDE 3.7.0

start

public void start()
           throws MediaException

Starts playback of the media content. If MediaPlayer is in UNREALIZED state then this method will throw an exception. MediaPlayer enters the STARTED state when this method is called. This method does not reset the media time to 0.

Throws:

MediaException - Thrown if MediaPlayer is in the UNREALIZED state or if no media content exists.

Since:

JDE 3.7.0

stop

public void stop()

Stops playback of the media.

MediaPlayer enters the REALIZED state when this method is called.

Since:

JDE 3.7.0

setMediaTime

public void setMediaTime(long time)
                  throws MediaException

Sets the media time starting from 0. This method will throw an exception in case MediaPlayer is not in REALIZED state.

Parameters:

time - The specified time for which to set the media player.

Throws:

MediaException - Thrown if the media type is not supported

Since:

JDE 3.7.0

getMediaTime

public long getMediaTime()

Returns the current media time.

Returns:

A long representing the media time.

Since:

JDE 3.7.0

getMedia

public Object getMedia()

Returns current media object.

Returns:

An object representing the media.

Since:

JDE 3.7.0

setMedia

public void setMedia(Object media)
              throws MediaException

Sets the already constructed media for the playback. This method will throw a MediaException in case this player does not support given media.

The media object is created by calling the getMedia() method.

Parameters:

media - The media object to be set.

Throws:

MediaException - Thrown if the media type is not supported.

IllegalArgumentException - Thrown if media object is not compatible with the player

Since:

JDE 3.7.0

getUI

public Object getUI()

Returns platform specific UI component into which the media will be loaded.

This UI object does not provide any additional public interface.

Returns:

The UI object.

Since:

JDE 3.7.0

close

public void close()

Closes an instance of MediaPlayer.

This will dispose the current media and other resources and will put MediaPlayer into the UNREALIZED state. MediaPlayer can be used again.

Since:

JDE 3.7.0

addMediaListener

public void addMediaListener(MediaListener l)

Registers a listener with the MediaPlayer.

Parameters:

l - The listener to register.

Throws:

IllegalArgumentException - Throws if listener is null

Since:

JDE 3.7.0

removeMediaListener

public void removeMediaListener(MediaListener l)

Unregisters a listener from the MediaPlayer.

Parameters:

l - The MediaListener to add to the MediaPlayer.

Throws:

IllegalArgumentException - Throws if listener is null

Since:

JDE 3.7.0