net.rim.plazmic.mediaengine
Class MediaManager

java.lang.Object
  |
  +--net.rim.plazmic.mediaengine.MediaManager
All Implemented Interfaces:
ResourceProvider

public class MediaManager
extends Object
implements ResourceProvider

MediaManager class for downloading media content from the Internet or local storage. MediaManager downloads media content and resources and instantiates media data object that can be passed to the MediaPlayer for playback using MediaPlayer.setMedia(java.lang.Object).

Since:
JDE 3.7.0
See Also:
MediaPlayer

Constructor Summary
MediaManager()
          The default constructor.
MediaManager(Connector c)
          Creates a MediaManager instance given a connector.
MediaManager(Connector c, boolean enableRelative)
          Creates a MediaManager instance given a connector and a boolean that indicates whether or not relative URLs are enabled.
 
Method Summary
 void addMediaListener(MediaListener listener)
          Adds a listener to the media.
 void cancel()
          Cancels the current download if one exists.
 Object createMedia(String uri)
          Loads media content from a given URI.
 Object createMedia(String uri, String suggestedType)
          Loads the suggested type of media content from a given URI (if it exists).
 void createMediaLater(String uri)
          Loads media content asynchronously given a Uniform Resource Indicator (URI).
 void dispose()
          Disposes the download if one exists.
 Connector getConnector()
          Returns the connector for this MediaManager.
 Connector getDefaultConnector()
          Returns the default connector associated with this MediaManager.
 void removeMediaListener(MediaListener listener)
          Removes a listener from the media.
 String resolveURL(String url)
          Converts a relative url or an absolute path to an absolute url.
 void setConnector(Connector connector)
          Sets the connector for this MediaManager.
 void setProperty(String name, String value)
          Set connection properties.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MediaManager

public MediaManager()
The default constructor.
Since:
JDE 3.7.0

MediaManager

public MediaManager(Connector c)
             throws NullPointerException
Creates a MediaManager instance given a connector.

Parameters:
c - The connector used to create the MediaManager.
Throws:
NullPointerException - if c is null.
Since:
JDE 3.7.0

MediaManager

public MediaManager(Connector c,
                    boolean enableRelative)
Creates a MediaManager instance given a connector and a boolean that indicates whether or not relative URLs are enabled.

Parameters:
c - The connector used to create the MediaManager.
enableRelative - A boolean indicating whether or not relative URLs are allowed.
Throws:
NullPointerException - if c is null.
Since:
JDE 3.7.0
Method Detail

addMediaListener

public void addMediaListener(MediaListener listener)
Adds a listener to the media.

If the specified listener is already in the list of listeners for the media then this method does nothing.

Parameters:
listener - The listener to add.
Throws:
IllegalArgumentException - if listener is null.
Since:
JDE 3.7.0

cancel

public void cancel()
Cancels the current download if one exists.

This stops the current download. The download can be restarted from the beginning after a call to cancel() has been made.

Since:
JDE 3.7.0

createMedia

public Object createMedia(String uri)
                   throws IOException,
                          MediaException
Loads media content from a given URI.

Parameters:
uri - A string representing the URI. URI can be relative or absolute URL. Must not be null.
Returns:
An object representing the media content.
Throws:
IOException - Currently throws a ConnectionNotFoundException (see below).
NullPointerException - Thrown if the "uri" argument is null.
IllegalArgumentException - Thrown if the "uri" argument is incorrectly formatted (eg. a URI of "zzyzx")
MediaException - Thrown if the media is not supported, the download has been cancelled, or a communication error occurs.
ConnectionNotFoundException - Thrown if the "uri" argument specifies an unsupported protocol (eg. a URI of "zhttp://www.google.com").
Since:
JDE 3.7.0

createMedia

public Object createMedia(String uri,
                          String suggestedType)
                   throws IOException,
                          MediaException
Loads the suggested type of media content from a given URI (if it exists). Use this method if the media content type is known to be "audio/midi". Throws an exception if the suggested type does not exist.

Parameters:
uri - A string representing the URI. URI can be relative or absolute URL. Must not be null.
suggestedType - A string representing the Media Type
Returns:
An object representing the media content.
Throws:
IOException - Currently throws a ConnectionNotFoundException (see below).
NullPointerException - Thrown if the "uri" argument is null.
IllegalArgumentException - Thrown if the "uri" argument is incorrectly formatted (eg. a URI of "zzyzx")
MediaException - Thrown if the media is not supported, the download has been cancelled, or a communication error occurs.
ConnectionNotFoundException - Thrown if the "uri" argument specifies an unsupported protocol (eg. a URI of "zhttp://www.google.com").
Since:
JDE 4.0.0

createMediaLater

public void createMediaLater(String uri)
Loads media content asynchronously given a Uniform Resource Indicator (URI).

Once download is complete the listeners will be notified with the event MediaListener.MEDIA_REALIZED. If download fails the listeners will be notified with the event MediaListener.MEDIA_LOADING_FAILED. Subsequent calls prior to download completion will automatically cancel the previous request.

Parameters:
uri - A string representing the URI.
Since:
JDE 3.7.0

dispose

public void dispose()
Disposes the download if one exists.

Calling dispose() releases all resources allocated by the manager. This method should be called when MediaManager is no longer needed.

Since:
JDE 3.7.0

getConnector

public Connector getConnector()
Returns the connector for this MediaManager.

Returns:
The connector instance.
Since:
JDE 3.7.0

getDefaultConnector

public Connector getDefaultConnector()
Returns the default connector associated with this MediaManager.

Returns:
The default connector.
Since:
JDE 3.7.0

removeMediaListener

public void removeMediaListener(MediaListener listener)
Removes a listener from the media.

Parameters:
listener - The listener to remove. If null this method does nothing.
Since:
JDE 3.7.0

resolveURL

public String resolveURL(String url)
Converts a relative url or an absolute path to an absolute url.
Parameters:
url - A relative or absolute path or absolute url.
Returns:
An absolute url based on the document base.
Since:
JDE 3.7.0

setConnector

public void setConnector(Connector connector)
Sets the connector for this MediaManager.

Parameters:
connector - The connector to set.
Since:
JDE 3.7.0

setProperty

public void setProperty(String name,
                        String value)
                 throws IllegalArgumentException
Set connection properties.

This method allows the user to set any connector specific properties as name value pairs. Set of supported properties is specific to the Connector.

Parameters:
name - The property name to set. Property "URI_BASE" requires value to be an absolute URL
value - The property value to set.
Throws:
IllegalArgumentException - Thrown if the specified property name is not supported, or if the specified property value is invalid.
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.