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

void use()
         throws ConnectionException

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

例外:

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

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

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

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

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

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

use

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 が設定されています。

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

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

unuse

void unuse()

メディアリソースの使用終了を宣言します。 メデ�