com.docomostar.media
クラス MediaManager

Object
  com.docomostar.media.MediaManager

public final class MediaManager

extends Object

メディアリソースデータの管理オブジェクトを定義します。
リソースの取得と利用時の振舞は以下のようになります。

• MediaManager.getImage メソッドまたは、 MediaManager.getSound メソッド、MediaManager.getAvatarData メソッド 、MediaManager.getMovieメソッドでリソースオブジェクトを 取得します。引数のロケーション指定については、最低限のチェック ( 形式のチェック、アクセス禁止 URL のチェックなど ) が行われます。リソースオブジェクトは指定されたロケーションを保持します。
  ストリームやバイト配列を指定した場合は、 null チェックと引数の保存のみを行います。 これはストリームやバイト配列への参照の保存であって、 コンテンツの保存は行いません。
• MediaResource.use メソッドを発行すると、ロケーション またはストリーム、バイト配列 からリソースをロードし内部表現形式に変換します。 このとき、 ConnectionException または MediaException が発生する可能性があります。
• use メソッド発行後、リソースオブジェクトは利用可能になります。
• use メソッドを実行すると、 ロケーションから得られる入力ストリーム、指定された入力ストリーム、 またはバイト配列から、 メディアリソースのサイズ分のデータが読み込まれます。
• MediaResource.unuse メソッドを発行すると、 内部表現形式が破棄され、その表現の保持に必要なリソース （メモリなど)が解放されます。
• 内部表現形式に変換する必要のないデータについては、 内部表現形式への変換、破棄は行いません。
• ストリームを指定して MediaResource オブジェクトを取得し、 MediaResource.use メソッドを unuse メソッドを挟んで複数回呼び出した場合、 一つ目のメディアリソースに対応したオブジェクトのみ取得可能です。 2 回目の use メソッドでは、新たなストリームの読み込みは行わず、 一つ目のメディアリソースが再度利用可能状態になります。 これは、入力ストリームから複数のメディアリソースのデータが連続して得られる場合でも、 同様です。
• MediaResource.dispose メソッドが発行されると、リソースオブジェクトが内部で使用しているリソース ( メモリなど ) が破棄されます。このメソッドが発行されたあとは、 use メソッド、 unuse メソッドの発行はできません。

MediaResource.use() メソッド、 MediaResource.unuse() メソッド呼び出しによる、 メモリ確保・解放に関する振る舞いをモデル化するために、 以下の 2 つの領域を定義します。

オリジナルデータ領域:

内部表現形式に変換される前のデータイメージを保存しておく領域です。 例えば、 GIF 画像の場合は、 GIF フォーマットのデータそのものを保存しておく領域がこれにあたります。

内部データ領域:

メディアリソースに対して use メソッドを呼び出すと、 内部表現形式への変換を行いますが、 その変換後のデータの一部 ( または全て ) を保存しておく領域です。

use() 、 unuse() 時のメモリ確保・解放に関する振る舞いは、 getImage() 、 getSound() 、 getAvatarData()、getMovie() メソッドの引数に、何を指定するかによって、下記のように異なります。 ただし、データによっては内部表現形式に変換する必要のないものがあります。 そのようなデータについては「オリジナルデータ領域」のみが存在するものとし、 下記の説明の「オリジナルデータ領域」に関する説明のみ有効とします。

URL 指定により取得したメディアリソース:

1回目の use 時:

• 新しく「オリジナルデータ領域」を確保する。 URLで指定されたロケーションよりデータを読み込み、 そのデータを「オリジナルデータ領域」に保存する。
• 新しく「内部データ領域」を確保する。 「オリジナルデータ領域」内のデータを内部形式に変換して 「内部データ領域」に保持する。

unuse 時:

「内部データ領域」のみを解放する。

2回目以降の use 時:

新しく「内部データ領域」を確保する。 URLで指定されたロケーションからのデータ読み込みは行わず、 「オリジナルデータ領域」 内のデータを内部形式に変換して「内部データ領域」に保持する。

バイト配列指定により取得したメディアリソース:

1回目の use 時:

• 新しく「オリジナルデータ領域」を確保する。 参照しているバイト配列の内容を 「オリジナルデータ領域」へコピーし、保存する。
• 新しく「内部データ領域」を確保する。 「オリジナルデータ領域」内のデータを内部形式に変換して 「内部データ領域」に保持する

unuse 時:

「内部データ領域」のみを解放する。

2 回目以降の use 時:

新しく「内部データ領域」を確保する。 「オリジナルデータ領域」 内のデータを内部形式に変換して「内部データ領域」に保持する。

ストリーム指定により取得したメディアリソース:

1 回目の use 時:

• 新しく「オリジナルデータ領域」を確保する。 データ1つ分をストリームより読み込み、 そのデータを「オリジナルデータ領域」に保存する。
• 新しく「内部データ領域」を確保する。 「オリジナルデータ領域」内のデータを内部形式に 変換して「内部データ領域」に保持する。

unuse 時:

「内部データ領域」を解放する。

2 回目以降の use 時:

新しく「内部データ領域」を確保する。 「オリジナルデータ領域」内のデータを内部形式に変換して 「内部データ領域」に保持する。

導入されたバージョン:

Star-1.0

関連項目:

MediaResource, MediaImage, MediaSound, MediaPresenter, AudioPresenter, VisualPresenter, NativeMoviePlayer, MediaMovie

メソッドの概要

static MediaImage	createMediaImage(int width, int height) 画像の幅・高さを指定して、 空のメディアイメージを生成します。
static MediaSound	createMediaSound(int bytes) サウンドのデータサイズ [bytes] を指定して、 空のメディアサウンドを生成します。
static AvatarData	getAvatarData(byte[] data) [iアプリオプションAPI] バイト配列を指定してアバターデータオブジェクトを取り出します。
static AvatarData	getAvatarData(java.io.InputStream in) [iアプリオプションAPI] ストリームを指定してアバターデータオブジェクトを取り出します。
static AvatarData	getAvatarData(String location) [iアプリオプションAPI] 場所を指定してアバターデータオブジェクトを取り出します。
static MediaImage	getImage(byte[] data) バイト配列を指定してメディアイメージオブジェクトを取り出します。
static MediaImage	getImage(java.io.InputStream in) ストリームを指定してメディアイメージオブジェクトを取り出します。
static MediaImage	getImage(String location) 場所を指定してメディアイメージオブジェクトを取り出します。
static MediaMovie	getMovie(byte[] data) バイト配列を指定してメディアムービーオブジェクトを取り出します。
static MediaMovie	getMovie(java.io.InputStream in) ストリームを指定してメディアムービーオブジェクトを取り出します。
static MediaMovie	getMovie(String location) 場所を指定してメディアムービーオブジェクトを取り出します。
static MediaSound	getSound(byte[] data) バイト配列を指定してメディアサウンドオブジェクトを取り出します。
static MediaSound	getSound(java.io.InputStream in) ストリームを指定してメディアサウンドオブジェクトを取り出します。
static MediaSound	getSound(String location) 場所を指定してメディアサウンドオブジェクトを取り出します。
static void	use(MediaImage[] images, boolean useOnce) 指定されたイメージを、 まとめて利用可能にします。
static void	use(MediaSound[] sounds, boolean useOnce) 指定されたサウンドを、 まとめて利用可能にします。

クラス Object から継承したメソッド

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

メソッドの詳細

getImage

public static final MediaImage getImage(String location)

場所を指定してメディアイメージオブジェクトを取り出します。 location 指定のフォーマット形式が正しくない場合 、引数指定誤りになります。

パラメータ:

location - 場所を指定します。

戻り値:

メディアイメージオブジェクトを返します。

例外:

NullPointerException -
引数 location が null の場合に発生します。

IllegalArgumentException -
引数 location に指定された文字列が "comm:" 、 "obex:" 、 "socket:" 、 "datagram:" で開始する場合に発生します。

IllegalArgumentException -
引数 location に不正な場所が指定された場合に発生します。

SecurityException -
セキュリティ上の制約に触れた場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getSound

public static final MediaSound getSound(String location)

場所を指定してメディアサウンドオブジェクトを取り出します。 location 指定のフォーマット形式が正しくない場合、 引数指定誤りになります。

パラメータ:

location - 場所を指定します。

戻り値:

メディアサウンドオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 location が null の場合に発生します。

IllegalArgumentException -
引数 location に指定された文字列が "comm:" 、 "obex:" 、 "socket:" 、 "datagram:" で開始する場合に発生します。

IllegalArgumentException -
引数 location に不正な場所が指定された場合に発生します。

SecurityException -
セキュリティ上の制約に触れた場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getAvatarData

public static final AvatarData getAvatarData(String location) [iアプリオプションAPI]

場所を指定してアバターデータオブジェクトを取り出します。 location 指定のフォーマット形式が正しくない場合 、引数指定誤りになります。

端末によっては、このメソッドをサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。

パラメータ:

location - 場所を指定します。

戻り値:

アバターデータオブジェクトを返します。

例外:

UnsupportedOperationException -
端末がこのメソッドをサポートしていない場合に発生します。

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 location が null の場合に発生します。

IllegalArgumentException -
引数 location に指定された文字列が "comm:" 、 "obex:" 、 "socket:" 、 "datagram:" で開始する場合に発生します。

IllegalArgumentException -
引数 location に不正な場所が指定された場合に発生します。

SecurityException -
セキュリティ上の制約に触れた場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getMovie

public static final MediaMovie getMovie(String location)

場所を指定してメディアムービーオブジェクトを取り出します。

location 指定のフォーマット形式が正しくない場合 、引数指定誤りになります。

パラメータ:

location - 場所を指定します。

戻り値:

メディアムービーオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 location が null の場合に発生します。

IllegalArgumentException -
引数 location に指定された文字列が "comm:" 、 "obex:" 、 "socket:" 、 "datagram:" で開始する場合に発生します。

IllegalArgumentException -
引数 location に不正な場所が指定された場合に発生します。

SecurityException -
セキュリティ上の制約に触れた場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getImage

public static final MediaImage getImage(java.io.InputStream in)

ストリームを指定してメディアイメージオブジェクトを取り出します。 ストリームからは、メディアイメージのファイルイメージを取り出せる必要があります。

パラメータ:

in - 入力ストリームを指定します。

戻り値:

メディアイメージオブジェクトを返します。

例外:

NullPointerException -
引数 in が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getSound

public static final MediaSound getSound(java.io.InputStream in)

ストリームを指定してメディアサウンドオブジェクトを取り出します。 ストリームからは、メディアサウンドのファイルイメージを取り出せる必要があります。

パラメータ:

in - 入力ストリームを指定します。

戻り値:

メディアサウンドオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 in が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getAvatarData

public static final AvatarData getAvatarData(java.io.InputStream in) [iアプリオプションAPI]

ストリームを指定してアバターデータオブジェクトを取り出します。 ストリームからは、アバターデータのファイルイメージを取り出せる必要があります。

端末によっては、このメソッドをサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。

パラメータ:

in - 入力ストリームを指定します。

戻り値:

アバターデータオブジェクトを返します。

例外:

UnsupportedOperationException -
端末がこのメソッドをサポートしていない場合に発生します。

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 in が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getMovie

public static final MediaMovie getMovie(java.io.InputStream in)

ストリームを指定してメディアムービーオブジェクトを取り出します。 ストリームからは、メディアムービーのファイルイメージを取り出せる必要があります。

パラメータ:

in - 入力ストリームを指定します。

戻り値:

メディアムービーオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 in が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getImage

public static final MediaImage getImage(byte[] data)

バイト配列を指定してメディアイメージオブジェクトを取り出します。 バイト配列には、メディアイメージのファイルイメージが格納されている必要があります。

パラメータ:

data - 入力バイト配列を指定します。

戻り値:

メディアイメージオブジェクトを返します。

例外:

NullPointerException -
引数 data が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getSound

public static final MediaSound getSound(byte[] data)

バイト配列を指定してメディアサウンドオブジェクトを取り出します。 バイト配列には、メディアサウンドのファイルイメージが格納されている必要があります。

パラメータ:

data - 入力バイト配列を指定します。

戻り値:

メディアサウンドオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 data が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getAvatarData

public static final AvatarData getAvatarData(byte[] data) [iアプリオプションAPI]

バイト配列を指定してアバターデータオブジェクトを取り出します。 バイト配列には、アバターデータのファイルイメージが格納されている必要があります。

端末によっては、このメソッドをサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。

パラメータ:

data - 入力バイト配列を指定します。

戻り値:

アバターデータオブジェクトを返します。

例外:

UnsupportedOperationException -
端末がこのメソッドをサポートしていない場合に発生します。

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 data が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

getMovie

public static final MediaMovie getMovie(byte[] data)

バイト配列を指定してメディアムービーオブジェクトを取り出します。 バイト配列には、メディアムービーのファイルイメージが格納されている必要があります。

パラメータ:

data - 入力バイト配列を指定します。

戻り値:

メディアムービーオブジェクトを返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 data が null の場合に発生します。

MediaException -
(NO_RESOURCES)
システムリソースの不足などでオブジェクトが生成できなかった場合に発生します。

use

public static final void use(MediaImage[] images,
                             boolean useOnce)
                      throws IterationAbortedException

指定されたイメージを、 まとめて利用可能にします。

第 1 引数で指定された全イメージについて「一度きりの利用」 とするかどうかを第 2 引数 useOnce で指定できます。 「一度きりの利用」についての詳細は MediaResource.use(MediaResource, boolean) の第 2 引数についての説明を参照してください。

メディアイメージの中には、 通信を行わないと利用可能に出来ないものも存在しますが、 引数の中にそのようなメディアイメージが指定されていても正しく動作します。

指定されたメディアイメージのうち、 1 つでも use に失敗した場合には、例外 IterationAbortedException が発生します。 その場合、IterationAbortedException.getAbortedIndex() によって、use に失敗したメディアイメージが格納されていた 配列のインデックス値が取得できます。 また、IterationAbortedException.getCause() によって、 use に失敗した原因となった例外オブジェクトを取得できます。 なお、以下の 2 点について注意してください。

• IterationAbortedException.getCause() によって取得できる 「 use に失敗した原因となった例外オブジェクト」には、 use に失敗したメディアイメージを単独で MediaResource.use() した場合に発生するであろう例外オブジェクトと同じものです。
• 失敗するまでに use に成功したメディアイメージは、 利用可能状態のままとなっています。
• 後述するように、 配列に格納されているメディアイメージが処理される順番は機種依存です。 したがって、IterationAbortedException.getAbortedIndex() で取得したインデックス値より小さい要素に格納されている全てのメディアイメージが利用可能状態になっているわけではありません。

このメソッド呼び出しにより、配列に格納されているメディアイメージが、 どのような順番で利用可能となるかは機種依存です。 このメソッド呼び出しからリターンした時点で、 全てのメディアイメージが利用可能状態になっていることのみが保証されています。

配列の中に、既に利用可能状態のメディアイメージが含まれている場合、 そのメディアイメージに対しては何も行われません。 また、配列中の null が指定された要素は単に無視され、 非 null の要素のみが処理対象となります。

パラメータ:

images - 利用可能にしたいメディアイメージの集合を格納した配列を指定します。

useOnce - 引数 images で指定した全イメージについて、 「一度きりの利用」としたい場合には true を、 そうでない場合には false を指定します。

例外:

NullPointerException -
引数 images に null が指定された場合に発生します。

IterationAbortedException -
配列 images に格納されているメディアイメージのいずれかが、 use に失敗した場合に発生します。

use

public static final void use(MediaSound[] sounds,
                             boolean useOnce)
                      throws IterationAbortedException

指定されたサウンドを、 まとめて利用可能にします。

引数に指定できるのがメディアサウンドである事以外は、 use(MediaImage[], boolean) と同じです。

パラメータ:

sounds - 利用可能にしたいメディアサウンドの集合を格納した配列を指定します。

useOnce - 引数 sounds で指定した全サウンドについて、 「一度きりの利用」としたい場合には true を、 そうでない場合には false を指定します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

NullPointerException -
引数 sounds に null が指定された場合に発生します。

IterationAbortedException -
配列 sounds に格納されているメディアサウンドのいずれかが、 use に失敗した場合に発生します。

createMediaImage

public static final MediaImage createMediaImage(int width,
                                                int height)

画像の幅・高さを指定して、 空のメディアイメージを生成します。

これによって生成されたメディアイメージの振る舞いは以下の通りです。

• 生成されたメディアイメージは、 MediaImage.use(MediaResource, boolean) により上書き可能な静止画(アニメ GIF を除く)です。
• 生成されたメディアイメージは、 既に利用可能状態になっており、 指定された幅・高さを持つ内部データ領域のみを保持しています。
• 生成されたメディアイメージは、 「一度きり」の利用しかできません。 すなわち、一度 MediaResource.unuse() してしまうと、 再度 use() した時点で例外が発生します。
• 生成されたメディアイメージの各画素は、全て黒色で初期化されています。
• 生成されたメディアイメージは、 便宜上常に再配布不可として扱われます。
• 生成されたメディアイメージに対するプロパティの設定や取得はできません。 すなわち、MediaResource.setProperty(String, String) 呼び出しは常に ( 例外が発生しない条件であれば ) 無視され、 MediaResource.getProperty(String) は、引数に何を指定して呼び出しても ( 例外が発生しない条件であれば ) null を返します。

このメソッドは、まだどの画像を使うかは決まっていないが、 必要な内部データ領域の最大サイズが分かっている場合に有用です。 例えば、ひとつのメディアイメージで、 画像 a, b, c を使い回す場合を考えます。 画像は a, b, c の順番で利用するが、 縦・横サイズの一番大きな画像は b である場合に、 以下のようなコードを書くことで、 サイズオーバになることなく、a, b, c 全ての画像を使い回すことが出来ます。

 // 画像 b の縦・横サイズで内部データ領域を確保
 MediaImage empty = MediaManager.createMediaImage(画像 b の縦・横サイズ);
 MediaImage a = MediaManager.getImage(画像 a のデータ);
 a.use(empty, true); // emptyで確保した内部データ領域を画像 a で上書き
 // ここで画像 a を利用する
 MediaImage b = MediaManager.getImage(画像 b のデータ);
 b.use(a, true); // a で使っていた内部データ領域を画像 b で利用
 // ここで画像 b を利用する
 MediaImage c = MediaManager.getImage(画像 c のデータ);
 c.use(b, true); // b で使っていた内部データ領域を画像 c で利用
 // ここで画像 c を利用する

パラメータ:

width - 生成したい空のメディアイメージの幅を指定します。

height - 生成したい空のメディアイメージの高さを指定します。

戻り値:

空のメディアイメージを生成して返します。

例外:

IllegalArgumentException -
引数 width 、 height のいずれかに 0 または 負の値が指定された場合に発生します。

MediaException -
(NO_RESOURCES)
必要なリソースが確保できなかった場合に発生します。

createMediaSound

public static final MediaSound createMediaSound(int bytes)

サウンドのデータサイズ [bytes] を指定して、 空のメディアサウンドを生成します。

これによって生成されたメディアサウンドの振る舞いは以下の通りです。

• 生成されたメディアサウンドは、 既に利用可能状態になっており、 指定されたデータサイズ [bytes] のメディアサウンドを格納するのに必要十分な内部データ領域のみを保持しています。
• 生成されたメディアサウンドは 「一度きり」の利用しかできません。 すなわち、一度 MediaResource.unuse() してしまうと、 再度 use() した時点で例外が発生します。
• 生成された直後のメディアサウンドを AudioPresenter で再生しても音は鳴りませんが、再生自体は可能です。 その場合、 例外は発生せず、再生開始・停止・完了イベントも通常通り発生しますが、 再生時間は機種依存です。
• 生成されたメディアサウンドは、 便宜上常に再配布不可として扱われます。
• 生成されたメディアサウンドに対するプロパティの設定や取得はできません。 すなわち、MediaResource.setProperty(String, String) 呼び出しは常に ( 例外が発生しない条件であれば ) 無視され、 MediaResource.getProperty(String) は、引数に何を指定して呼び出しても ( 例外が発生しない条件であれば ) null を返します。

このメソッドは、まだどのサウンドを使うかは決まっていないが、 必要な内部データ領域の最大サイズが分かっている場合に有用です。 具体的な使用例については createMediaImage(int, int) を参考にしてください。

パラメータ:

bytes - 生成したい空のメディアサウンドのデータサイズ [bytes] を指定します。

戻り値:

空のメディアサウンドを生成して返します。

例外:

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

IllegalArgumentException -
引数 bytes に 0 または 負の値が指定された場合に発生します。

MediaException -
(NO_RESOURCES)
必要なリソースが確保できなかった場合に発生します。