javax.microedition.media
インタフェース Player

すべてのスーパーインタフェース:

Controllable

public interface Player
extends Controllable

Player は時間ベースのメディア・データのレンダリングを制御します。 このインタフェースは Player のライフ・サイクルを管理するメソッドを提供し、再生進行の制御と表現部品の取得を行います。

簡単な再生

Manager の createPlayer メソッドの１つから Player を作成することができます。 Player の作成後に、start を呼び出すとできる限り即急に再生を開始します。 再生が開始するとメソッドから制御が戻ります。 再生はバックグラウンドで継続し、メディアの終端に到達すると自動的に停止します。

簡単な再生の例でこれを例示します。

Player のライフ・サイクル

Player には５つの状態があります： UNREALIZED、 REALIZED、 PREFETCHED、 STARTED、 CLOSED。

これらのライフ・サイクル状態の目的は、潜在的に時間のかかる操作のプログラムに沿った制御を提供することにあります。 例えば Player が構築された直後には、それは UNREALIZED 状態にあります。 UNREALIZED から REALIZED への移行では、Player が機能するために必要なリソースの全ての対象（サーバーとの通信やファイル・システムなど）へ必要な通信を実行します。 アプリケーションは realize() メソッドによって適当な機会に、この潜在的に時間のかかる処理に着手することができます。

通常、Player が UNREALIZED 状態から REALIZED 状態まで移行する、その時に PREFETCHED 状態になり、そして最終的に STARTED 状態になります。

Player は、それがメディアの終端に達すると停止します; または stop() メソッドを呼び出します。 これが起こると、Player は STARTED 状態から PREFETCHED 状態へ逆に遷移します。 これによってサイクルを繰り返す準備が完了します。

Player の使用にあたっては、これらのライフ・サイクルの状態を通したその動きと、その時の状態を通して Player の状態遷移メソッドを使用し、状態を移行させ、管理するためのパラメータを設定しなければなりません。

Player の状態

このセクションではそれぞれの Player の状態の意味について説明します。

UNREALIZED 状態

Player は UNREALIZED 状態で始まります。 この状態の Player には、それが機能するために必要とする全てのリソースを取得できるほどの情報を得ていません。

Player が UNREALIZED 状態にあるときには以下のメソッドを使用してはなりません。

• getContentType
• setMediaTime
• getControls
• getControl

使用すると IllegalStateException を throw します。

realize メソッドは UNREALIZED 状態から REALIZED 状態へ Player を遷移させます。

REALIZED 状態

メディア・リソースを取得するのに必要な情報を得ると、Player は REALIZED 状態になります。 これはリソースと時間のかかる処理であることがあります。 Player はサーバーと通信しなければならないか、ファイルを読み出さなければならないか、あるいは１セットのオブジェクトとやり取りしなければならないかもしれません。

REALIZED 状態の Player は何もリソースを取得する必要はありませんが、それは限られたシステム・リソースの排他的な使用について意味するものを除き、おそらくそれが必要とするオーディオ・デバイスのようなリソースの全てを取得します。

通常、Player は UNREALIZED 状態から REALIZED 状態へ遷移します。 以前に realize を呼び出した Player が、UNREALIZED 状態に戻すことができる唯一の方法は realize が完了する前に deallocate を呼び出すことです。 一度 Player が REALIZED 状態に到達すると、二度と UNREALIZED 状態に戻ることはありません。 それは４つの状態のうちの１つになります: REALIZED、PREFETCHED、STARTED、または CLOSED。

PREFETCHED 状態

一度 REALIZED 状態になると、Player は、さらに開始する準備を完了する前に、多くの時間がかかるタスクを実行する必要があるかもしれません。 例えばそれは、限られたまたは排他的なリソースを取得するか、メディア・データでバッファを満たすか、または他の開始処理を実行する必要があるかもしれません。 Player の prefetch を呼び出すとこれらのタスクを行います。

一度 Player が PREFETCHED 状態になると、それを開始することができます。 プリフェッチ（先読み）は Player を開始するのにかかる遅延をできる限り最小限に減少させます。

STARTED 状態の Player が停止するとき、それは PREFETCHED 状態へ戻ります。

STARTED 状態

一度 PREFETCHED 状態になると、Player は start メソッドを呼ぶことによって STARTED 状態に入ることができます。 PREFETCHED 状態の Player は、Player がデータの処理を実行していることを意味します。 このときに stop() メソッドが呼び出されるか、またはメディアの終端に達すると、Player は PREFETCHED 状態へ戻ります。

Player が PREFETCHED 状態から STARTED 状態へ遷移するとき、STARTED イベントを通知します。 STARTED 状態から PREFETCHED 状態へ遷移するとき、停止の理由に応じて STOPPED または END_OF_MEDIA イベントを通知します。

Player が STARTED 状態にあるときには以下のメソッドを使用してはなりません：

• setLoopCount

使用すると IllegalStateException を throw します。

CLOSED 状態

Player の close() を呼び出すと、それは CLOSED 状態になります。 CLOSED 状態では、Player はリソースの大部分を開放し、再びの使用はできなくなります。

Player の５つの状態遷移をまとめた図を以下に示します：

Player のイベント

Player イベントは Player の状態変化と Player の Control からの他の関連情報に応じて非同期に情報を通知します。

イベントを受け取るには、オブジェクトは PlayerListener インタフェースを実装し、Player イベントに対して addPlayerListener メソッドを使用して登録しなければなりません。 全ての Player イベントが登録されたそれぞれのリスナーに通知されます。

イベントは、イベントが表現する動作が起こった順序で通知されることが保証されます。 例えば、Player が非常に短いメディア・ファイルを再生し、開始直後に停止したなら、STARTED イベントは END_OF_MEDIA イベントよりも常に先に通知しなければなりません。

復旧困難なエラーが発生すると ERROR イベントをいつでも通知することができます。 それが発生すると、Player は CLOSED 状態になります。

Player イベント・メカニズムは拡張することができます。そして Player によっては、ここで説明した以外のイベントを定義しています。 既定の Player イベントのリストが存在するか否か、PlayerListener インタフェースを確認してください。

Player が使用するリソースの管理

prefetch メソッドは、オーディオ・デバイスなどの限られたまたは排他的なリソースを取得するために使用します。 逆に、deallocate() メソッドを使用して、限られたまたは排他的なリソースを開放することができます。 これら２つのメソッドを使用することによって、アプリケーションはプログラムに基づいて Player のリソースを管理することができます。

例えば、排他的なオーディオ・デバイスによる実装では、アプリケーションは複数の Player を切り替えるために、個々の Player を選択的に deallocate および prefetch() することができます。

Player の Control

Player はいくつかのタイプ特有の Control インタフェースを通じて、付加的な制御を提供する Controllable を実装します。 Player が UNREALIZED または CLOSED 状態にあるときは、getControl および getControls を呼び出すことはできません。 呼び出すと IllegalStateException を throw します。

簡単な再生の例

 try {
     Player p = Manager.createPlayer("http://abc.wav");
     p.start();
 } catch (MediaException pe) {
 } catch (IOException ioe) {
 }

UNREALIZED

static final int UNREALIZED

Player の状態が機能するためのリソースと情報をまだ取得していないことを示します。

UNREALIZED には値として 100 が割り当てられます。

関連項目:

定数フィールド値

REALIZED

static final int REALIZED

Player の状態が機能するため情報を取得し、リソースをまだ取得していないことを示します。

REALIZED には値として 200 が割り当てられます。

関連項目:

定数フィールド値

PREFETCHED

static final int PREFETCHED

Player が再生を開始するために全てのリソースを取得したことを示す状態です。

PREFETCHED には値として 300 が割り当てられます。

関連項目:

定数フィールド値

STARTED

static final int STARTED

Player が再生を既に開始したことを示す、Player の状態です。

STARTED には値として 400 が割り当てられます。

関連項目:

定数フィールド値

CLOSED

static final int CLOSED

Player が閉じられたことを示す、Player の状態です。

CLOSED には値として 0 が割り当てられます。

関連項目:

定数フィールド値

TIME_UNKNOWN

static final long TIME_UNKNOWN

要求された時間が不明であることを示すために返す値です。

TIME_UNKNOWN には値として -1 が割り当てられます。

関連項目:

定数フィールド値

realize

void realize()
             throws MediaException

限られたおよび排他的なリソースを取得せずに、Player の一部を構成します。 これはメディア・データの調査を含むことがあり、完全な確認をするかもしれません。

realize が正常に完了すると、Player は REALIZED 状態になります。

Player が REALIZED、PREFETCHED、または STARTED 状態にあるときに realize が呼ばれると、要求は無視されます。

例外:

IllegalStateException - Player が CLOSED 状態ならば throw します。

MediaException - この Player でこのメソッドを実行できなければ throw します。

SecurityException - 呼び出し元が Player でこのメソッドを実行するセキュリティ権限を持っていなければ throw します。

prefetch

void prefetch()
              throws MediaException

限れたおよび排他的なリソースを取得し、開始の遅延を抑えるために必要となる多くのデータを処理します。

prefetch が正常に完了すると、Player は PREFETCHED 状態になります。

Player が UNREALIZED 状態にあるときに prefetch が呼び出されたなら、realize が暗黙のうちに呼び出されます。

Player が既に PREFETCHED 状態にあるときに prefetch が呼び出されたなら、開始の遅延を抑えるために必要となる多くのデータを処理します。 これは、最小限の遅延で開始できることを保証するためのものです。

Player が STARTED 状態にあるときに prefetch が呼び出されると、要求は無視します。

Player が必要とするリソースの全てを得ることができないのであれば、MediaException を throw します。 これが発生すると、Player は開始することができません。 しかしながら、別のアプリケーションまたは Player が必要とするリリースを開放してから、再び prefetch が呼び出されることができます。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

MediaException - Player が prefetch を実行できないなら throw します。

SecurityException - 呼び出し元が Player でこのメソッドを実行するセキュリティ権限を持っていなければ throw します。

start

void start()
           throws MediaException

できる限りすばやく Player を開始します。 Player が以前 stop を呼び出されて停止していたなら、それは以前に停止していたところから再生を再開します。 Player がメディアの終端に達していたのなら、start の呼び出しはメディアの最初からの再生を自動的に開始します。

start が正常に処理を戻すとき、Player は開始します。そして、STARTED イベントを登録された PlayerListener に通知します。 しかしながら、Player は STARTED 状態にあることは保証されません。 メディアがゼロか非常に短い場合には、Player は既に（PREFETCHED 状態にて）停止しているかもしれません。

もし start が呼ばれたときに Player が UNREALIZED または REALIZED 状態にあるなら、暗黙のうちに prefetch が呼ばれます。

Player が STARTED 状態のときに start が呼び出されると、要求は無視します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

MediaException - Player が start を実行できないなら throw します。

SecurityException - 呼び出し元が Player でこのメソッドを実行するセキュリティ権限を持っていなければ throw します。

stop

void stop()
          throws MediaException

Player を停止します。 それは現在のメディア時間で再生を一時停止します。

stop から処理が戻ると、Player は PREFETCHED 状態になります。 STOPPED イベントを登録された PlayerListener に通知します。

Player が停止しているときに stop が呼び出されると、要求は無視します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

MediaException - Player が stop を実行できないなら throw します。

deallocate

void deallocate()

Player が入手したオーディオ・デバイスのような限られたまたは排他的なリソースを開放します。

deallocate から処理が戻ると、Player は UNREALIZED または REALIZED 状態になります。

もし、Player が realize の呼び出しによるブロック中に deallocate を呼び出すと、realize() のブロックは解除されて制御が戻り、Player は UNREALIZED 状態になります。 さもなければ、deallocate の呼び出しは Player を REALIZED 状態へ戻します。

Player が UNREALIZED または REALIZED 状態のときに deallocate が呼び出されると、要求は無視します。

もし deallocate が呼ばれたときに Player が STARTED 状態にあるなら、暗黙のうちに stop が呼ばれます。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

close

void close()

Player を閉じてリソースを開放します。

このメソッドから処理が帰るとき、Player は CLOSED 状態にあり、これ以上使用することはできません。 CLOSED イベントを登録された PlayerListener に通知します。

Player が閉じているときに close が呼び出されると、要求は無視します。

setMediaTime

long setMediaTime(long now)
                  throws MediaException

Player のメディア時間を設定します。

いくつかのメディア・タイプにおいて、メディア時間の設定はそれほど正確ではないかもしれません。 戻り値は、実際のメディアが設定した時間を示します。

メディア時間に負数を指定すると、結果的にメディア時間にはゼロが設定されます。 メディア時間へメディアの所要時間を設定すると、時間はメディアの終端に設定されます。

メディア時間の設定をサポートしないいくつかのメディア・タイプが存在します。 それらの場合は setMediaTime を呼び出すと MediaException を throw します。

パラメータ:

now - 新しいマイクロ秒単位のメディア時間を渡します。

戻り値:

実際に設定されたマイクロ秒単位のメディア時間を返します。

例外:

IllegalStateException - Player が UNREALIZED または CLOSED 状態にあるならば throw します。

MediaException - メディア時間の設定を行うことができない場合に throw します。

関連項目:

getMediaTime()

getMediaTime

long getMediaTime()

この Player の現在のメディア時間を取得します。 もしもメディア時間を決定することができないのなら、getMediaTime は TIME_UNKNOWN を返します。

戻り値:

マイクロ秒単位で現在のメディア時間を返すか、または TIME_UNKNOWN を返します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

関連項目:

setMediaTime(long)

getState

int getState()

この Player の現在の状態を取得します。 ありうる状態は以下の通りです： UNREALIZED、REALIZED、PREFETCHED、STARTED、CLOSED。

戻り値:

Player の現在の状態を返します。

getDuration

long getDuration()

メディアの所要時間を取得します。 デフォルトの速度で再生した場合のメディアの所要時間を返します。

所要時間が決定できない（例えば、Player は生放送のメディアを提供している）なら、getDuration は TIME_UNKNOWN を返します。

戻り値:

マイクロ秒単位で所要時間を返すか、または TIME_UNKNOWN を返します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

getContentType

String getContentType()

この Player によって再生されるメディアの Content-Type を取得します。

Content-Type のための書式を参照してください。この書式による Content-Type を返します。

戻り値:

この Player によって再生される Content-Type を返します。

例外:

IllegalStateException - Player が UNREALIZED または CLOSED 状態にあるならば throw します。

setLoopCount

void setLoopCount(int count)

Player がコンテンツをループして再生する回数を設定します。

デフォルトのループ回数は 1 です。 すなわち、一度開始すると、Player は現在のメディア時間からメディアの終端までを１度だけ再生します。

ループカウント N が 1 より大きな N を設定すると、Player が開始すると、現在のメディア時間からメディアの終端まで内容を再生します。 次にそれは、内容の最初（メディア時間ゼロ）からループしてメディアの終端まで再生します。 それが最初までループして、メディアの終端までプレイする回数は N-1 になります。

ループカウントを 0 にすることはできません。 IllegalArgumentException を throw します。

ループカウントを -1 に設定すると、内容を無限にループして再生します。

Player が事前にセットされたループカウントに到達する前に stop の呼び出しによって停止したならば、start の呼び出しによって再び再生が停止したところから再開し、設定されたループカウントに到達するまでループ再生を行います。

Player がメディアの終端に達すると、常に END_OF_MEDIA イベントを通知します。 ループカウントを終了せずに、Player が再び再生を開始するか、ループによって最初に戻って再生をするなら、STARTED イベントを通知します。

パラメータ:

count - 内容を再生する回数を示す数を渡します。 デフォルトで 1 です。 0 は無効です。 -1 は無限ループを示します。

例外:

IllegalArgumentException - パラメータ count が無効ならば throw します。

IllegalStateException - Player が STARTED または CLOSED 状態にあるならば throw します。

addPlayerListener

void addPlayerListener(PlayerListener playerListener)

この Player のためのプレイヤー・リスナーを加えます。

パラメータ:

playerListener - 加えるリスナーを渡します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

関連項目:

removePlayerListener(javax.microedition.media.PlayerListener)

removePlayerListener

void removePlayerListener(PlayerListener playerListener)

この Player のためのプレイヤー・リスナーを削除します。

パラメータ:

playerListener - 削除するリスナーを渡します。 null が使用されるか、指定された playerListener がこの Player のためのリスナでなければ、要求は無視します。

例外:

IllegalStateException - Player が CLOSED 状態にあるならば throw します。

関連項目:

addPlayerListener(javax.microedition.media.PlayerListener)