com.docomostar.system
クラス ContentsDownloader

Object
  com.docomostar.system.ContentsDownloader

public final class ContentsDownloader
extends Object

コンテンツをダウンロードし、 ネイティブが管理しているストレージ領域に直接保存する機能を提供します。 また、端末によっては、 ダウンロードしたコンテンツをその場で再生することができます。

この機能を用いることで、Star アプリでは扱えなかった大容量コンテンツをダウンロードすることができます。 ダウンロードしたデータは直接ネイティブが管理している領域に保存されます。

このクラスのインスタンスは、以下の状態を持ちます。

ダウンロード可能状態:

コンストラクタ によりインスタンスが生成された直後の状態です。 以下のメソッドのみを呼び出すことができます。

• setQuery(String)
• setExpectedContentType(String)
• setRequestMethod(String)
• setPlayOptions(Hashtable)
• download()

例外が発生せずに download() メソッド呼び出しからリターンすると、ダウンロード完了状態へ遷移します。 download()呼び出し時に例外が発生した場合は、 ダウンロード可能状態のままとなります。

ダウンロード完了状態:

ダウンロードが完了している状態です。 この状態で呼び出し可能なメソッドはありません。 再度ダウンロードするには、 新しく生成したインスタンスを用いて行ってください。

導入されたバージョン:

Star-1.1

フィールドの概要

static String

DEFAULT_CONTENT_TYPE デフォルトのコンテントタイプです(="application/x-dcm-fullmusic")。

コンストラクタの概要

ContentsDownloader(String url)
コンストラクタです。

メソッドの概要

void	download() コンテンツのダウンロード、ならびに、ストレージ(端末メモリ、 または外部メモリ)への保存を行います。
void	setExpectedContentType(String contentType) ダウンロードしたいコンテンツの Content-Type を指定します。
void	setPlayOptions(java.util.Hashtable params) コンテンツ再生時の振る舞いを決定するオプションパラメータを指定します。
void	setQuery(String query) コンテンツダウンロード時に送出するクエリーを指定します。
void	setRequestMethod(String method) ダウンロード時に用いるリクエストメソッドを指定します。

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

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

フィールドの詳細

DEFAULT_CONTENT_TYPE

public static final String DEFAULT_CONTENT_TYPE

デフォルトのコンテントタイプです(="application/x-dcm-fullmusic")。

関連項目:

setExpectedContentType(String), 定数フィールド値

コンストラクタの詳細

ContentsDownloader

public ContentsDownloader(String url)

コンストラクタです。 コンテンツをダウンロードしたい URL を指定して、 ContentsDownloader インスタンスを生成します。

ADF に AccessUserInfo キーの指定が必要です。 また、ここで指定した URL との通信については、 ダウンロード可能なデータサイズの上限を除いては、 通常の Star アプリからの HTTP 通信と同様の制限が適用されます。 すなわち、ユーザによる通信可否設定や、 ダウンロード元 URL が正当かどうか、などのチェックが行われます。

パラメータ:

url - コンテンツをダウンロードする URL を指定します。 HTTP または HTTPS のみが指定できます。

例外:

IllegalArgumentException -
引数 url が不正、あるいは null である場合に発生します。 具体的には以下のケースで発生します。

• このコンストラクタの引数 url をそのまま指定して Connector.open(String) を呼び出すと IllegalArgumentException が発生する場合
• このコンストラクタの引数 url をそのまま指定して Connector.open(String) を呼び出すと ConnectionNotFoundException が発生する場合
• 引数 url に指定されたプロトコルスキームが http でも https でも無い場合
• 引数 url 中に '?' が含まれていた場合

SecurityException -
ADF に AccessUserInfo キーの指定がないアプリケーションが、 このコンストラクタを呼び出した場合に発生します。

SecurityException -
引数 url について、セキュリティ上の制約に触れた場合や、 UseNetwork キーが無い場合、 Star アプリ個別のユーザ設定により通信が許可されていない場合に発生します。

メソッドの詳細

setQuery

public void setQuery(String query)

コンテンツダウンロード時に送出するクエリーを指定します。 application/x-www-form-urlencoded 形式にエンコード済みの文字列を指定してください。

ここで指定された文字列は、 リクエストメソッドが GET である場合はリクエストラインの一部として、 POST である場合にはボディとして、ダウンロード元サーバへ送信されます。

このメソッドは、 引数に指定された文字列が URL 中にクエリー文字列として記載できるかどうかのチェックは行いますが、 実際に application/x-www-form-urlencoded 形式かどうかのチェックは行いません。 したがって、application/x-www-form-urlencoded 形式でない文字列が指定されていた場合でも、 ダウンロード時に、指定された文字列をそのまま送出します。

デフォルトでは、クエリーは指定なし(null)の状態になっています。

パラメータ:

query - ダウンロード時に付与するクエリーを application/x-www-form-urlencoded 形式で指定します。 クエリーを指定しない場合には、空文字列、または null を指定します。

例外:

IllegalStateException -
ダウンロード完了状態で呼び出された場合に発生します。

IllegalArgumentException -
引数 query に指定された文字列が、 端末が許容する長さを超えている場合に発生します。

IllegalArgumentException -
引数 query に指定された文字列が、 RFC 2396 に規定されている <query> の文法規則に違反している場合に発生します。

setExpectedContentType

public void setExpectedContentType(String contentType)

ダウンロードしたいコンテンツの Content-Type を指定します。 コンテンツダウンロード時に、サーバが、ここで指定した Content-Type と異なる Content-Type (大文字小文字は区別しない)を応答した場合には、 ダウンロードに失敗します。

デフォルトでは、DEFAULT_CONTENT_TYPE が指定されている状態になっています。

パラメータ:

contentType - ダウンロードしたいコンテンツの Content-Type を指定します。

例外:

IllegalStateException -
ダウンロード完了状態で呼び出された場合に発生します。

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

UnsupportedOperationException -
引数に指定された contentType が未知、 あるいは未サポートの Content-Type である場合に発生します。

setRequestMethod

public void setRequestMethod(String method)

ダウンロード時に用いるリクエストメソッドを指定します。 文字列定数 HttpConnection.GET か HttpConnection.POST を指定できます。 指定可能な定数値と大文字小文字だけが異なる文字列を、 直接指定することも可能です。

デフォルトでは HttpConnection.GET が指定されている状態になっています。

パラメータ:

method - ダウンロード時に用いるリクエストメソッドを指定します。

例外:

IllegalStateException -
ダウンロード完了状態で呼び出された場合に発生します。

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

IllegalArgumentException -
引数 method に指定された文字列が、 HttpConnection.GET、HttpConnection.POST のいずれでもない(大文字小文字は区別しない)場合に発生します。

setPlayOptions

public void setPlayOptions(java.util.Hashtable params)

コンテンツ再生時の振る舞いを決定するオプションパラメータを指定します。 特に指定しない場合には null を指定してください。
デフォルトでは、パラメータは指定なし(null)の状態になっています。

このメソッドで指定したパラメータは、 ダウンロード・保存された当該コンテンツの再生時の振る舞いを決定するのに利用されます。
ダウンロードしたコンテンツをその場で再生できない端末でも、 本パラメータは有効であることに注意してください。 ここでのパラメータ指定は、 ダウンロード後にその場で再生する場合だけでなく、 後からネイティブ機能を用いて再生する場合にも影響します。

引数に指定するパラメータのキーと値は、 どちらも String 型を指定する必要があります。 String 型以外が指定された場合は例外が発生します。

なお、このメソッドでは、 パラメータの内容に踏み込んだ正当性チェックは行いません。 パラメータの内容に踏み込んだチェックについては download() メソッド呼び出し時に行われます。

パラメータ:

params - コンテンツ再生時の振る舞いを決定するオプションパラメータを指定します。 特に指定しない場合には null を指定します。

例外:

IllegalStateException -
ダウンロード完了状態で呼び出された場合に発生します。

IllegalArgumentException -
引数 params にシステムが提供している以外のオブジェクト (Hashtable クラスを継承した未知のクラスのオブジェクト) が渡された場合に発生します。

ClassCastException -
引数 params のキーや値に、 String 型以外のオブジェクトが含まれていた場合に発生します。

download

public void download()
              throws InterruptedOperationException,
                     ContentsException

コンテンツのダウンロード、ならびに、ストレージ(端末メモリ、 または外部メモリ)への保存を行います。

このメソッドを呼び出すと、Star アプリケーションはサスペンドし、 コンテンツのダウンロード、ストレージへの保存を行います。 端末によっては、 ダウンロードしたコンテンツを、 ユーザ操作によって再生できるものもあります。
一連の処理が完了(失敗やユーザによる中断を含む)すると、 Star アプリケーションはレジュームします。

ダウンロード、ならびにストレージへの保存が正常に完了した場合 (通信中断等により部分保存となった場合も含む。以下同様。) は、このメソッドは例外を発生せずにリターンします。 特に、ストレージへの保存完了後であれば、 何らかの原因で処理に失敗した場合でも、 例外は発生しないことに注意してください。
言い換えると、このメソッド呼び出しにおいて例外が発生した場合は、 コンテンツの保存が完了していないことを意味します。

コンテンツをダウンロードする際にサーバへ送出されるリクエストは、 setRequestMethod(String) にて指定されているリクエストメソッドの種類により異なります。

リクエストメソッド	GET	POST
接続先 URL	クエリーが指定されていない(空文字列、または null)場合: ContentsDownloader(String) の引数で指定された URL クエリーが指定されている場合: 先頭から以下の順に連結して得られる文字列 ContentsDownloader(String) の引数で指定された URL '?' (0x3F) setQuery(String) の引数で指定された文字列	ContentsDownloader(String) の引数で指定された URL
Content-Type リクエストヘッダの値	N/A	application/x-www-form-urlencoded
HTTP リクエストボディ	N/A	setQuery(String) の引数で指定された文字列

以下の機能については、端末によってサポートされていない場合があります。 サポートされていない端末では、 このメソッド呼び出しによるサスペンド中に、 ユーザはその機能を利用することができません。

• ダウンロードしたコンテンツの再生

例外:

IllegalStateException -
ダウンロード完了状態で呼び出された場合に発生します。

IllegalArgumentException -
setPlayOptions(Hashtable) で指定されているパラメータが不正である場合に発生します。

SecurityException -
ネイティブ独自のセキュリティ設定により、 ダウンロード・保存処理が禁止されている場合に発生します。

ContentsException -
(ILLEGAL_CONTENT)
ダウンロード対象コンテンツが保存不可能である場合に発生します。 具体的には以下のケースで発生します。

• ダウンロード対象コンテンツのサイズが制限を超えている場合
  (Content-Lengthヘッダの値が上限を超えている場合を含みます)
• ダウンロード対象コンテンツの種別が、 Star アプリが期待している種別とは異なる場合
  (Content-Typeヘッダの値が、 setExpectedContentType(String)で設定した値と一致しない場合を含みます)
• ダウンロード対象コンテンツの種別が判定不能な場合
• ダウンロード対象コンテンツの再生回数制限が0回の場合
• その他、 サーバレスポンスのボディ部の内容に起因してダウンロードに失敗した場合

ContentsException -
(RESPONSE_ERROR)
ダウンロード時における、サーバからのレスポンスについて、 ステータスコードやヘッダが不正である場合に発生します。

ContentsException -
(NETWORK_ERROR)
ネットワークの問題による通信断や、 i-mode 圏外・i-mode 未契約の場合など、 ダウンロード時にサーバとの通信に失敗した場合や、 サーバに接続できなかった場合に発生します。

ContentsException -
(USER_ABORT)
コンテンツのダウンロード、ならびに保存完了前に、 ユーザ操作により中断要求が発生した場合に発生します。

InterruptedOperationException -
コンテンツのダウンロードならびに保存完了前に、 競合条件などにより、 ネイティブ機能が異常終了した場合に発生します。