FileDocCategorySizeDatePackage
Manager.javaAPI DocJ2ME MIDP 2.012282Thu Nov 07 12:02:30 GMT 2002javax.microedition.media

Manager

public final class Manager extends Object
Manager is the access point for obtaining system dependent resources such as Players for multimedia processing.

A Player is an object used to control and render media that is specific to the content type of the data.

Manager provides access to an implementation specific mechanism for constructing Players.

For convenience, Manager also provides a simplified method to generate simple tones.

Simple Tone Generation

The playTone function is defined to generate tones. Given the note and duration, the function will produce the specified tone.

Creating Players

Manager provides two methods to create a Player for playing back media:
  • Create from a media locator.
  • Create from an InputStream.
The Player returned can be used to control the presentation of the media.

Content Types

Content types identify the type of media data. They are defined to be the registered MIME types ( http://www.iana.org/assignments/media-types/); plus some user-defined types that generally follow the MIME syntax (RFC 2045, RFC 2046).

For example, here are a few common content types:

  1. Wave audio files: audio/x-wav
  2. AU audio files: audio/basic
  3. MP3 audio files: audio/mpeg
  4. MIDI files: audio/midi
  5. Tone sequences: audio/x-tone-seq

Media Locator

Media locators are specified in URI syntax which is defined in the form:

    <scheme>:<scheme-specific-part>

The "scheme" part of the locator string identifies the name of the protocol being used to deliver the data.

see
Player

Fields Summary
public static final String
TONE_DEVICE_LOCATOR
The locator to create a tone Player to play back tone sequences. e.g. 
try {
Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR);
p.realize();
ToneControl tc = (ToneControl)p.getControl("ToneControl");
tc.setSequence(mySequence);
p.start();
} catch (IOException ioe) {
} catch (MediaException me) {}
If a tone sequence is not set on the tone Player via its ToneControl, the Player does not carry any sequence. getDuration returns 0 for this Player.

The content type of the Player created from this locator is audio/x-tone-seq.

A Player for this locator may not be supported for all implementations.

Value "device://tone" is assigned to TONE_DEVICE_LOCATOR.

Constructors Summary
private Manager()
This private constructor keeps anyone from actually getting a Manager.
Methods Summary
public static PlayercreatePlayer(java.lang.String locator)
Create a Player from an input locator.

param
locator A locator string in URI syntax that describes the media content.
return
A new Player.
exception
IllegalArgumentException Thrown if locator is null.
exception
MediaException Thrown if a Player cannot be created for the given locator.
exception
IOException Thrown if there was a problem connecting with the source pointed to by the locator.
exception
SecurityException Thrown if the caller does not have security permission to create the Player.


	if (locator == null)
	    throw new IllegalArgumentException("locator: null");

	BasicPlayer p = null;
	boolean conn = true;
	if (locator.equals(TONE_DEVICE_LOCATOR)) {
	    p = new TonePlayer();
	    conn = false;
	} else {
	    if (locator.toLowerCase().endsWith(".wav") ||
		locator.startsWith("http:")) {
		p = new WavPlayer();
	    }
	}

	if (p == null)
	    throw new MediaException("Unsupported type.");
	
	p.setLocator(locator, conn);
	
	return p;
public static PlayercreatePlayer(java.io.InputStream stream, java.lang.String type)
Create a Player to play back media from an InputStream.

The type argument specifies the content-type of the input media. If null is given, Manager will attempt to determine the type. However, since determining the media type is non-trivial for some media types, it may not be feasible in some cases. The Manager may throw a MediaException to indicate that.

param
stream The InputStream that delivers the input media.
param
type The ContentType of the media.
return
A new Player.
exception
IllegalArgumentException Thrown if stream is null.
exception
MediaException Thrown if a Player cannot be created for the given stream and type.
exception
IOException Thrown if there was a problem reading data from the InputStream.
exception
SecurityException Thrown if the caller does not have security permission to create the Player.

	if (stream == null)
	    throw new IllegalArgumentException("stream: null");

	BasicPlayer p = null;

	if (type != null) {
	    type = type.toLowerCase();
	}
	if ((type == null) || 
	    ((type != null) && (type.equals("audio/x-wav")))) {
	    p = new WavPlayer();
	}

	if ((type != null) && (type.equals("audio/x-tone-seq"))) {
	    p = new TonePlayer();
	}

	if (p != null) {
	    p.setStrm(stream);
	    p.setLocator(null, false);
	    return p;
	} 

	throw new MediaException("Unsupported type.");
public static java.lang.String[]getSupportedContentTypes(java.lang.String protocol)
Return the list of supported content types for the given protocol.

See content types for the syntax of the content types returned. See protocol name for the syntax of the protocol used.

For example, if the given protocol is "http", then the supported content types that can be played back with the http protocol will be returned.

If null is passed in as the protocol, all the supported content types for this implementation will be returned. The returned array must be non-empty.

If the given protocol is an invalid or unsupported protocol, then an empty array will be returned.

param
protocol The input protocol for the supported content types.
return
The list of supported content types for the given protocol.

	if (protocol == null)
	    return new String [] { "audio/x-wav", "audio/x-tone-seq" };
	if (protocol.equals("device"))
	    return new String [] { "audio/x-tone-seq" };
	if (protocol.equals("http"))
	    return new String [] { "audio/x-wav" };
	return new String[0];
public static java.lang.String[]getSupportedProtocols(java.lang.String content_type)
Return the list of supported protocols given the content type. The protocols are returned as strings which identify what locators can be used for creating Player's.

See protocol name for the syntax of the protocols returned. See content types for the syntax of the content type used.

For example, if the given content_type is "audio/x-wav", then the supported protocols that can be used to play back audio/x-wav will be returned.

If null is passed in as the content_type, all the supported protocols for this implementation will be returned. The returned array must be non-empty.

If the given content_type is an invalid or unsupported content type, then an empty array will be returned.

param
content_type The content type for the supported protocols.
return
The list of supported protocols for the given content type.

	if (content_type == null)
	    return new String [] { "device", "http" };
	if (content_type.equals("audio/x-tone-seq"))
	    return new String [] { "device" };
	if (content_type.equals("audio/x-wav"))
	    return new String [] { "http" };
	return new String[0];
private static native intnPlayTone(int note, int dur, int vol)
The native implementation method to play a tone.

param
note Defines the tone of the note.
param
dur The duration of the tone in milli-seconds.
param
vol Audio volume range from 0 to 100.
return
the status. <= 0 means it failed to play the tone

public static voidplayTone(int note, int duration, int volume)
Play back a tone as specified by a note and its duration.
A note is given in the range of 0 to 127 inclusive. The frequency
of the note can be calculated from the following formula:

SEMITONE_CONST = 17.31234049066755 = 1/(ln(2^(1/12)))
note = ln(freq/8.176)*SEMITONE_CONST
The musical note A = MIDI note 69 (0x45) = 440 Hz.


This call is a non-blocking call. Notice that this method may
utilize CPU resources significantly on devices that don't
have hardware support for tone generation.
param
note Defines the tone of the note as specified by the
above formula.
param
duration The duration of the tone in milli-seconds.
Duration must be positive.
param
volume Audio volume range from 0 to 100. 100 represents
the maximum
volume at the current hardware level. Setting the volume to a
value less
than 0 will set the volume to 0. Setting the volume to greater than
100 will set the volume to 100.
exception
IllegalArgumentException Thrown if the given note or
duration is out of range.
exception
MediaException Thrown if the tone cannot be played
due to a device-related problem.
	if (note < 0 || note > 127 || duration <= 0)
	    throw new IllegalArgumentException("playTone");

	if (nPlayTone(note, duration, volume) <= 0)
	    throw new MediaException("can't play tone");