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()
          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
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 MediaPlayer is not in REALIZED state
Since:
JDE 4.0.2

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 MediaPlayer is in the STARTED state or if the media type is not supported.
IllegalArgumentException - Thrown if media object is not compatible with the player
Since:
JDE 4.0.2

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 4.0.2

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 4.0.2


Copyright 1999-2004 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.