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 int REALIZED
          Represents the REALIZED state.
static int STARTED
          Represents the STARTED state.
static int UNREALIZED
          Represents the UNREALIZED state.
 
Constructor Summary
MediaPlayer()
          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, as previously specified in the setMedia(java.lang.Object) method.
 long getMediaTime()
          Returns the current media time in milliseconds.
 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 in milliseconds.
 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


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

UNREALIZED

public static final int UNREALIZED
Represents the UNREALIZED state.
Since:
JDE 3.7.0
Constructor Detail

MediaPlayer

public MediaPlayer()
Constructor. Uses a @link { MediaField } as the default base component field.
Since:
JDE 3.7.0
Method Detail

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

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

getMedia

public Object getMedia()
Returns current media object, as previously specified in the setMedia(java.lang.Object) method.

Returns:
The current media object, or null if there is no media object currently set.
Since:
JDE 3.7.0
See Also:
setMedia(java.lang.Object)

getMediaTime

public long getMediaTime()
Returns the current media time in milliseconds.

Returns:
The current MediaPlayer time in milliseconds, or 0 if invoked prior to setMedia(java.lang.Object).
Since:
JDE 3.7.0

getState

public int getState()
Returns the current state.

One of UNREALIZED, REALIZED, STARTED.

Returns:
An integer representing the state.
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

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

setMedia

public void setMedia(Object media)
              throws MediaException
Sets the already constructed media for the playback. This method will throw a MediaException if this player does not support the given media.

The media object is created via one of the following methods:

Parameters:
media - The media object to be set. If null, then any current media object is disposed and the MediaPlayer state changes to UNREALIZED.
Throws:
MediaException - Thrown if the media type is not supported.
Since:
JDE 3.7.0

setMediaTime

public void setMediaTime(long time)
                  throws MediaException
Sets the media time in milliseconds. The MediaPlayer must be in the REALIZED state when this method is invoked. Media playback commences at time zero (0) so that specifying a negative time is equivalent to a start time delay.

Parameters:
time - The specified time in milliseconds used to set the MediaPlayer time.
Throws:
MediaException - Thrown if the MediaPlayer's state is not REALIZED
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



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.