com.docomostar.device.felica
クラス OnlineFelica

Object
  com.docomostar.device.felica.OnlineFelica

public final class OnlineFelica
extends Object

[iアプリオプションAPI]

オンライン処理によって、FeliCa カードにアクセスする手段を提供するクラスです。

オンライン処理の開始に先立って、 以下の操作を行う必要があります。

• setOnlineListener(OnlineListener) 呼び出しにてリスナを設定する
• 必要に応じて、addDevice(String, String) にてサーバとの通信時に操作可能なデバイスを追加する

このオブジェクトが生成された直後では、 オンライン処理におけるタイムアウト値としては 1000 [ms] が、 リトライ数としては 3 が、 それぞれ設定されています。 これらの値はサーバサイドより変更することが可能です。

導入されたバージョン:

Star-1.0

関連項目:

Felica.getOnlineFelica()

フィールドの概要

static int	DEVICE_ID_DISPLAY 汎用 Display のデバイスIDを表します(=0x0002)。
static int	DEVICE_ID_FELICA FeliCa用のデバイスIDを表します(=0x0001)。

メソッドの概要

int	addDevice(String type, String name) オンライン処理においてサーバ側から利用可能な端末側の実在、 あるいは仮想のデバイスを追加します。
void	clearDeviceList() デバイスリストをクリアします。
int	getDeviceID(String type, String name) デバイスIDを取得します。
String	getDeviceName(int deviceID) デバイスIDに対応したデバイスの名前を取得します。
String	getDeviceType(int deviceID) デバイスIDに対応したデバイスの種類を取得します。
void	setOnlineListener(OnlineListener listener) オンライン処理におけるイベントを受け取るリスナを設定します。
void	start(String url) オンライン処理を開始します。
void	stop() オンライン処理を中断します。

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

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

フィールドの詳細

DEVICE_ID_FELICA

public static final int DEVICE_ID_FELICA

FeliCa用のデバイスIDを表します(=0x0001)。

デバイスの名前:

"R/W"

デバイスの種類:

"FeliCa"

関連項目:

定数フィールド値

DEVICE_ID_DISPLAY

public static final int DEVICE_ID_DISPLAY

汎用 Display のデバイスIDを表します(=0x0002)。

デバイスの名前:

"Display"

デバイスの種類:

"Generic"

関連項目:

定数フィールド値

メソッドの詳細

setOnlineListener

public void setOnlineListener(OnlineListener listener)

オンライン処理におけるイベントを受け取るリスナを設定します。 設定できるリスナは一つだけです。 複数回呼び出された場合は最後のリスナが有効となります。

パラメータ:

listener - イベントを受け取るリスナ。

例外:

DeviceException -
(ILLEGAL_STATE)
オンライン処理が既に開始されている場合に発生します。

addDevice

public int addDevice(String type,
                     String name)

オンライン処理においてサーバ側から利用可能な端末側の実在、 あるいは仮想のデバイスを追加します。

追加されるデバイスの種類と名前はサーバ側に予め登録されている必要があり、 DeviceOperationRequestイベントが発生した場合に対象デバイスIDが使用されます。 start(String) メソッドの実行後に呼び出された場合には、デバイスが 追加されますが、サーバには通知されません。

なお、以下のデバイスは、このメソッドを呼び出さずとも利用可能です。

• FeliCa デバイス (DeviceID = 0x0001)
• 汎用 Display デバイス (DeviceID = 0x0002)

このメソッドで追加できるデバイス数は、 デフォルトで利用可能な FeliCa デバイス、 汎用 Display デバイスを含めて 64 です。

パラメータ:

type - デバイスの種類。 ASCII 図形文字 (0x21 〜 0x7E) のみで構成された、 1文字以上255文字以下の文字列が指定できます。

name - デバイスの名前。 ASCII 図形文字 (0x21 〜 0x7E) のみで構成された、 1文字以上255文字以下の文字列が指定できます。

戻り値:

追加されたデバイスID。 既に登録済みであった場合には、 その登録済みデバイスのデバイスIDが返ります。

例外:

NullPointerException -
引数 type、name のいずれかに null が指定された場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかに空文字列が指定された場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかが、256文字以上の場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかに、 ASCII 図形文字以外の文字が含まれていた場合に発生します。

IllegalStateException -
登録できる最大数のデバイス(=64)が既に設定されている場合に発生します。

getDeviceName

public String getDeviceName(int deviceID)

デバイスIDに対応したデバイスの名前を取得します。

パラメータ:

deviceID - デバイスID。

戻り値:

デバイスの名前。デバイスが存在しない場合は null が返ります。

getDeviceType

public String getDeviceType(int deviceID)

デバイスIDに対応したデバイスの種類を取得します。

パラメータ:

deviceID - デバイスID。

戻り値:

デバイスの種類。デバイスが存在しない場合は null が返ります。

getDeviceID

public int getDeviceID(String type,
                       String name)

デバイスIDを取得します。

パラメータ:

type - デバイスの種類。

name - デバイスの名前。

戻り値:

デバイスID。デバイスが存在しない場合は-1が返ります。

例外:

NullPointerException -
引数 type、name のいずれかに null が指定された場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかに空文字列が指定された場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかが、256文字以上の場合に発生します。

IllegalArgumentException -
引数 type、name のいずれかに、 ASCII 図形文字以外の文字が含まれていた場合に発生します。

clearDeviceList

public void clearDeviceList()

デバイスリストをクリアします。
クリアされるのは addDevice(String, String) で追加されたデバイスのみであり、 デフォルトで利用可能な FeliCa デバイス、 汎用 Display デバイスは削除されません。

関連項目:

addDevice(String, String)

例外:

DeviceException -
(ILLEGAL_STATE)
オンライン処理が既に開始されている場合に発生します。

start

public void start(String url)
           throws ConnectionException,
                  javax.microedition.io.ConnectionNotFoundException

オンライン処理を開始します。このメソッドは即座にリターンします。 このメソッドが呼び出されてから、stop() メソッドが呼ばれるまでの間は、非同期に通信が行われている可能性があります。
その通信において例外が発生した場合にはリスナが起動されます。 詳細は、OnlineListener.onlineError(int, String) を参照して下さい。

パラメータ:

url - オンライン処理時に通信するサーバの URL を指定します。 指定する URL のプロトコル・ホスト名・ポート番号は、 許可されている URL の « プロトコル, ホスト名, ポート番号 » の組のいずれかと一致していているか、 もしくはダウンロード元URLと一致していなければなりません。

例外:

DeviceException -
(ILLEGAL_STATE)
FeliCaがオープンされていない状態の場合に発生します。

DeviceException -
(ILLEGAL_STATE)
オンライン処理が既に開始されている場合に発生します。

DeviceException -
(ILLEGAL_STATE)
OnlineListenerが設定されていない場合に発生します。

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

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

javax.microedition.io.ConnectionNotFoundException -
引数 url に指定された URL のプロトコルスキームが、 http、https のいずれでもない場合に発生します。

RuntimeException -
呼び出してはならない状態のときに呼び出された場合に発生します。 メソッドの内部処理中で不正な状態が発生した場合などが該当します。

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

IllegalArgumentException -
URLが、実装がサポートしているバイト数を超える場合に発生します。 上限値は、通常のhttp(s)通信と同様です。

IllegalArgumentException -
引数 url に指定された URL のホスト名が、 IPアドレス指定の場合に発生します。

SecurityException -
ADF に UseNetwork キーの指定がないアプリケーションから呼び出された場合に発生します。

SecurityException -
ADF に UseNetwork キーが指定されているが、 Star アプリ個別のユーザ設定により許可されない場合に発生します。

SecurityException -
https でダウンロードされた Star アプリにおいて、 引数 url で指定された URL のプロトコルスキームが http である場合に発生します。

SecurityException -
引数 url で指定された « プロトコル, ホスト名, ポート番号 » の組が、 許可されている « プロトコル, ホスト名, ポート番号 » のいずれにも一致 せず、ダウンロード元URLとも異なる場合に発生します。

stop

public void stop()

オンライン処理を中断します。

オンライン 通信処理中にこのメソッドを呼び出すと、 サーバサイドに中断通知を行った上で、強制的に通信を中断します。 サーバサイドへの中断通知を行わずに強制終了する場合には、 代わりに Felica.close() を呼び出して下さい。 オンライン処理開始前やオンライン処理終了後にこのメソッドを呼び出した場合は、 何も行われません。

関連項目:

OnlineListener.onlineError(int, String)