Manager (Java(TM) ME Embedded Profile, Final Release)

java.lang.Object
- javax.microedition.media.Manager

```
public final class Manager
extends java.lang.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.
The simplest way to create a Player is from a locator in the URI syntax. Given a locator, createPlayer will create a Player suitable to handle the media identified by the locator.
A second version of createPlayer creates a Player from an InputStream. This can be used to interface with other Java APIs which use InputStreams such as the java.io package. It should be noted that InputStream does not provide the necessary random seeking functionality. So a Player created from an InputStream may not support random seeking (ala Player.setMediaTime).
System Time Base

All Players need a TimeBase. Many use a system-wide TimeBase, often based on a time-of-day clock. Manager provides access to the system TimeBase through getSystemTimeBase.

Content Types
Content types identify the type of media data. They are defined to be the registered MIME types (see [IANAMEDIA]); plus some user-defined types that generally follow the MIME syntax ([RFC2045], [RFC2046]).
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
Data Delivery Protocol

A data delivery protocol specifies how media data is delivered to the media processing systems. Some common protocols are: local file, disk I/O, HTTP, RTP streaming, live media capture etc.
Media locators are used to identify the delivery protocol (as well as the identifier/name of the media).

Media Locator
Media locators are specified in URL 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 Also:
Player, TimeBase

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String TONE_DEVICE_LOCATOR
The locator to create a tone Player to play back tone sequences.

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`TONE_DEVICE_LOCATOR` The locator to create a tone `Player` to play back tone sequences.

Method Summary

Methods
Modifier and Type	Method and Description
`static Player`	`createPlayer(java.io.InputStream stream, java.lang.String type)` Create a `Player` to play back media from an `InputStream`.
`static Player`	`createPlayer(java.lang.String locator)` Create a `Player` from an input locator.
`static java.lang.String[]`	`getSupportedContentTypes(java.lang.String protocol)` Return the list of supported content types for the given protocol.
`static java.lang.String[]`	`getSupportedProtocols(java.lang.String content_type)` Return the list of supported protocols given the content type.
`static TimeBase`	`getSystemTimeBase()` Get the time-base object for the system.
`static void`	`playTone(int note, int duration, int volume)` Play back a tone as specified by a note and its duration.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TONE_DEVICE_LOCATOR

public static final java.lang.String TONE_DEVICE_LOCATOR

The locator to create a tone Player to play back tone sequences. For example,

 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.

See Also:: Constant Field Values

Method Detail
- createPlayer
```
public static Player createPlayer(java.io.InputStream stream,
                  java.lang.String type)
                           throws java.io.IOException,
                                  MediaException
```
  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.
  
  Parameters:
  stream - the InputStream that delivers the input media
  type - the content type of the media
  
  Returns:
  a new Player
  
  Throws:
  
  java.lang.IllegalArgumentException - if stream is null
  
  java.lang.SecurityException - if the caller does not have security permission to create the Player
  
  java.io.IOException - if there was a problem reading data from the InputStream
  
  {@link - MediaException} if a Player cannot be created for the given stream and type
  
  MediaException
- createPlayer
```
public static Player createPlayer(java.lang.String locator)
                           throws java.io.IOException,
                                  MediaException
```
  Create a Player from an input locator.
  
  Parameters:
  locator - A locator string in URI syntax that describes the media content.
  
  Returns:
  A new Player.
  
  Throws:
  
  java.lang.IllegalArgumentException - if locator is null.
  
  java.lang.SecurityException - if the caller does not have security permission to create the Player
  
  java.io.IOException - if there was a problem connecting with the source pointed to by the locator
  
  {@link - MediaException} if a Player cannot be created for the given locator
  
  MediaException
- getSupportedContentTypes
```
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.
  
  Parameters:
  protocol - the input protocol for the supported content types
  
  Returns:
  the list of supported content types for the given protocol
- getSupportedProtocols
```
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 Players.
  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.
  
  Parameters:
  content_type - the content type for the supported protocols
  
  Returns:
  the list of supported protocols for the given content type
- getSystemTimeBase
```
public static TimeBase getSystemTimeBase()
```
  Get the time-base object for the system.
  
  Returns:
  the system time base
- playTone
```
public static void playTone(int note,
            int duration,
            int volume)
                     throws MediaException
```
  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.
  Parameters:
  note - defines the tone of the note as specified by the above formula
  duration - the duration of the tone in milli-seconds. Duration must be positive.
  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.
  
  Throws:
  
  {@link - MediaException} if the tone cannot be played due to a device-related problem
  
  java.lang.IllegalStateException - if the given note or duration is out of range
  
  MediaException

Class Manager

Simple Tone Generation

Creating Players

System Time Base

Content Types

Data Delivery Protocol

Media Locator

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TONE_DEVICE_LOCATOR

Method Detail

createPlayer

createPlayer

getSupportedContentTypes

getSupportedProtocols

getSystemTimeBase

playTone