com.docomostar.media
インタフェース MediaResource

既知のサブインタフェースの一覧:

AvatarData, MediaImage, MediaMovie, MediaSound

public interface MediaResource

メディアリソースデータを定義します。 このメディアリソースインタフェースは、 メディアデータクラスが必ず実装しなければならないインタフェースを定めます。

メディアリソースは、使用する前に use() で使用開始を宣言し、 使用した後に unuse() で使用終了を宣言しなければなりません。 また、もはやメディアリソースを使用しない場合は dispose() で破棄しなければなりません。 dispose() を呼ばない限り、 メディアリソースで使用したメモリが解放されない場合があります。

なお、既に use() されているメディアリソースを再度 use() しても何もしません。 dispose() メソッドを呼び出した後にそのオブジェクトに対して dispose() 以外の何らかのメソッドを呼び出した場合 MediaException が投げられます。 破棄されていないメディアリソースが GC によって回収されようとしている場合の動作は機種依存です。

メディアリソースが確保するメモリを効率的に利用できる use(MediaResource, boolean) が利用可能です。 詳細は、そのメソッドの説明を参照して下さい。 また、 use() 、 unuse() メソッド呼び出しによる、 メモリ確保・解放に関する振る舞いについては MediaManager クラスの説明を参照してください。

導入されたバージョン:

Star-1.0

関連項目:

MediaManager

メソッドの概要

void	dispose() メディアリソースを破棄します。
String	getProperty(String key) 指定されたキーに該当するプロパティ値を取得します。
boolean	isRedistributable() このメディアリソースが再配布可能かどうかを取得します。
void	setProperty(String key, String value) [iアプリオプションAPI] 指定されたキーに該当するプロパティ値を設定します。
boolean	setRedistributable(boolean redistributable) このメディアリソースの再配布を可能にするかどうかを設定します。
void	unuse() メディアリソースの使用終了を宣言します。
void	use() メディアリソースの使用開始を宣言します。
void	use(MediaResource overwritten, boolean useOnce) メモリ領域を再利用したいメディアリソース、および 、一度きりの利用であるかどうかを指定して、 このメディアリソースの使用開始を宣言します。

メソッドの詳細

use

public void use()
         throws ConnectionException

メディアリソースの使用開始を宣言します。 use(null, false) を呼び出した場合と同じ振る舞いをします。 詳細は use(MediaResource, boolean) を参照して下さい。

例外:

MediaException -
(ILLEGAL_STATE)
既に dispose されているメディアリソースに対して呼び出された場合に発生します。

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

ConnectionException -
ネットワーク通信などで例外が発生した場合に発生します。 ネットワークサービスがないか圏外の場合、 ステータスには OUT_OF_SERVICE が設定されています。 タイムアウトの場合には、TIMEOUT が設定されています。 定額制ユーザのデータ通信規制中の場合にも、 ステータスには OUT_OF_SERVICE が設定されています。

MediaException -
(UNSUPPORTED_FORMAT)
端末で再生できないようなデータフォーマットの場合に発生します。 データの長さが 0 の場合など、 フォーマットが不正と見なされる場合にも発生します。

MediaException -
(ILLEGAL_STATE)
このオブジェクトが、「一度きり」と指定して use され、その後 unuse されていた場合に発生します。

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

use

public void use(MediaResource overwritten,
                boolean useOnce)
         throws ConnectionException

メモリ領域を再利用したいメディアリソース、および 、一度きりの利用であるかどうかを指定して、 このメディアリソースの使用開始を宣言します。 このメソッドが発行されると、実際にメディアリソースがロードされ、 内部表現形式に変換されます。

第 1 引数には、メモリ領域を再利用したいメディアリソースを指定します。 このメソッドが発行されると、実際にメディアリソースがロードされ、 内部表現形式に変換されますが、 この引数に非 null を指定すると、 変換後の内部表現形式を格納する領域として、 引数 overwritten で指定されたメディアリソースの 「内部データ領域」 を再利用します 既に確保されている領域を再利用するため、以下の点に注意してください。

• 引数で指定するメディアリソースは利用可能状態でなければなりません。
• 引数で指定されたメディアリソースが確保している 「内部データ領域」の容量以上の領域を確保しなければならない場合には、 このメソッド呼び出しは失敗し、例外を発生します。
• このメソッドを呼び出すと ( 例外発生の有無に関わらず ) 、 引数で指定されたメディアリソースは利用不可状態 (unuse() された状態 ) になります。
• このメソッドを呼び出したオブジェクトの実行時の型と、 引数で指定したオブジェクトの実行時の型は、 一致していなければなりません。 そうでない場合には例外が発生します。

第 2 引数は、 このメディアイメージの利用 (use) が 「一度きり」であるかどうかを指定します。 「一度きり」であると指定した場合 (true を指定した場合 ) 、 use 完了と同時に、内部形式に変換される前のリソースを破棄します。

メディアリソースの実装によっては、use メソッドを呼び出してから、 一旦 unuse メソッドを呼び出し、 再度 use メソッドを呼び出せるようにするためだけに、 1回目の use メソッド呼び出し時に 「オリジナルデータ領域」 を確保するするものがあります。 「一度きり」であると指定した場合は、 このメソッド呼び出しによって内部形式への変換が完了した直後に、 その領域を解放します。

その場合、このメソッド呼び出しにより、 実装によっては、早い段階で不要なメモリを解放することができますが、 以下のような制限があります。

• この方法で use した後に unuse メソッドを呼び出してしまうと、 二度と利用可能状態には戻れなくなります (use メソッドを呼び出すと例外が発生します )。 なお、破棄の方法そのものには変更はありません。 破棄する場合には、 unuse() だけでなく dispose() も呼び出してください。
• この方法で use した場合には、オリジナルデータ領域が存在しないため、 データ BOX への保存ができなくなります。 なお、以下のメソッドは通常通り実行可能です。
  • setRedistributable(boolean)
  • isRedistributable()
  • setProperty(String, String)
  • getProperty(String)

第 2 引数に false を指定した場合は、 「オリジナルデータ領域」は dispose されるまで保持されたままとなります。 その代わり、一旦 unuse() してから、 再度 use メソッドによって利用可能状態にすることができます。

内部表現形式に変換する必要のないデータについては、オリジナルデータ領域のみが存在します。 そのようなデータの場合、第 2 引数に true を指定してもオリジナルデータ領域は削除されません。 メモリ節約の効果もありません。その場合でも、 一旦 unuse() してから use() した場合には例外が発生します。

このメディアリソースが利用可能状態の時にこのメソッドが呼ばれると、 何も行われずに無視されます。

このインタフェースのサブインタフェースによっては、 このメソッドをサポートしていない場合があります。 あわせて各サブインタフェースのメソッド説明も参照してください。 また、ここで規定している以上に詳細な動作についても、 各サブインタフェースのメソッド説明を参照してください。

パラメータ:

overwritten - 領域を再利用したいメディアリソースを指定します。 null を指定すると、このメディアリソースの 「内部データ領域」は新規に確保されます。

useOnce - このメディアリソースの利用が「一度きり」の場合には true を、そうでない場合には false を指定します。

例外:

MediaException -
(ILLEGAL_STATE)
既に dispose されているメディアリソースに対して呼び出された場合に発生します。

IllegalArgumentException -
引数 overwritten に このオブジェクト自身が設定された場合に発生します。

ClassCastException -
引数 overwritten の実行時の型と、 このオブジェクトの実行時の型が異なる場合に発生します。

MediaException -
(ILLEGAL_STATE)
引数 overwritten が利用可能状態でない場合に発生します。

MediaException -
(ILLEGAL_STATE)
このオブジェクトが、「一度きり」と指定して use され、その後 unuse されていた場合に発生します。

MediaException -
(NO_RESOURCES)
このオブジェクトを利用可能状態にするのに必要な領域が、 引数 overwritten が確保している領域よりも大きい場合に発生します。

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

ConnectionException -
ネットワーク通信などで例外が発生した場合に発生します。 ネットワークサービスがないか圏外の場合、 ステータスには OUT_OF_SERVICE が設定されています。 タイムアウトの場合には、TIMEOUT が設定されています。 定額制ユーザのデータ通信規制中の場合にも、 ステータスには OUT_OF_SERVICE が設定されています。

MediaException -
(UNSUPPORTED_FORMAT)
端末で再生できないようなデータフォーマットの場合に発生します。 データの長さが 0 の場合など、 フォーマットが不正と見なされる場合を含みます。

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

unuse

public void unuse()

メディアリソースの使用終了を宣言します。 メディアリソースをメディアプレゼンタで再生している最中にこのメソッドを呼び出した場合は利用不可状態となります。

例外:

MediaException -
(ILLEGAL_STATE)
既に dispose されているメディアリソースに対して呼び出された場合に発生します。

dispose

public void dispose()

メディアリソースを破棄します。 メディアリソースをメディアプレゼンタで再生している最中にこのメソッドを呼び出した場合はリソース破棄状態となります。 このメソッドを呼び出した後に dispose 以外のメソッドを呼び出した場合は MediaException が発生します (ILLEGAL_STATE)。 このメソッドを呼び出した後に dispose メソッドを呼び出した場合は何もしません。

関連項目:

use(), unuse()

setProperty

public void setProperty(String key,
                        String value) [iアプリオプションAPI]

指定されたキーに該当するプロパティ値を設定します。

同一キーに対して複数回、このメソッドを使用した場合には、 後から指定されたプロパティ値が有効となります。また、 MediaMovie.MP4_AUDIOTRACK、 MediaMovie.MP4_TEXTTRACK、 MediaMovie.MP4_VIDEOTRACK、 MediaSound.AUDIO_3D_RESOURCES、 及び未サポートのキーが指定された場合には、このメソッドの呼び出しは無視されます。

プロパティ値 に null が指定された場合には、キーを削除します。

unuse() によりメディアリソースの使用終了を宣言した場合でも、 本メソッドで設定したプロパティ値が破棄されることはありません。

パラメータ:

key - プロパティを指定する文字列を指定します。 大文字小文字の区別はありません。

value - プロパティ値の文字列を指定します。

関連項目:

getProperty(String)

例外:

MediaException -
(ILLEGAL_STATE)
メディアリソースの使用開始を宣言していないメディアリソースに対して呼び出された場合に発生します。

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

IllegalArgumentException -
引数 key に空文字列が指定された場合に発生します。

getProperty

public String getProperty(String key)

指定されたキーに該当するプロパティ値を取得します。 取得できるプロパティのキーはリソースの種類に依存します。 無効なキーが指定された場合は null を返します。 また、指定されたキーに該当するプロパティ値が存在しない場合にも null を返します。 キーには大文字小文字の区別はありません。

パラメータ:

key - プロパティを指定する文字列を指定します。

戻り値:

プロパティ値を文字列で返します。

関連項目:

setProperty(String, String)

例外:

MediaException -
(ILLEGAL_STATE)
メディアリソースの使用開始を宣言していないメディアリソースに対して呼び出された場合に発生します。

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

IllegalArgumentException -
引数 key に空文字列が指定された場合に発生します。

isRedistributable

public boolean isRedistributable()

このメディアリソースが再配布可能かどうかを取得します。 再配布不可能なメディアリソースを「データ BOX 」に保存した場合、 そのメディアリソースは、 このアプリケーション以外の Java アプリケーションからは利用できなくなり、 ネイティブ機能のメールや赤外線を用いて端末の外へ持ち出すこともできなくなります。

再配布不可識別子が設定可能なメディアリソースの場合は、 再配布不可識別子が設定されていないときは true を、 再配布不可識別子が設定されているときは false を、 それぞれ返します。
再配布不可識別子が設定できないメディアリソースの場合は、 ネイティブ機能から再配布可能として扱われるものは true を、 再配布不可能として扱われるものは false を、それぞれ返します。

戻り値:

このメディアリソースが再配布可能である場合は true を、 再配布不可能である場合は false を返します。

例外:

MediaException -
(ILLEGAL_STATE)
メディアリソースの使用開始を宣言していないメディアリソースに対して呼び出された場合に発生します。

setRedistributable

public boolean setRedistributable(boolean redistributable)

このメディアリソースの再配布を可能にするかどうかを設定します。 再配布を禁止したメディアリソースを「データ BOX 」に保存した場合、 そのメディアリソースは、 このアプリケーション以外の Java アプリケーションからは利用できなくなり、 ネイティブ機能のメールや赤外線を用いて端末の外へ持ち出すこともできなくなります。

再配布を可能に設定すると再配布不可識別子が削除され、 再配布を禁止すると再配布不可識別子が新たに設定されます。

なお、メディアリソースの種類によっては、 再配布不可識別子を設定できないものも存在します。 そのようなメディアリソースに対してはこのメソッドは何もしません。 (GIF87a、 Flash^® コンテンツ、BMP が該当する)

また、メディアリソースの種類によっては、 再配布不可識別子を設定できるが、 その設定に関わらず常に再配布不可として取り扱われるものも存在します。 そのようなメディアリソースに対しても、 このメソッドは再配布不可識別子を設定します。 (アバターデータが該当する)

パラメータ:

redistributable - このメディアリソースの再配布を可能にする場合には true を、 再配布を禁止する場合には false を、それぞれ指定します。

戻り値:

再配布不可識別子の変更に成功したか、 変更の必要が無かった場合に true を、 そうでない場合に false を返します。 具体的には、このメソッドを呼び出した直後に
isRedistributable() == redistributable
を評価した値と同じ値を返します。

例外:

MediaException -
(ILLEGAL_STATE)
メディアリソースの使用開始を宣言していないメディアリソースに対して呼び出された場合に発生します。