com.nttdocomo.lang
クラス XObject

Object
  |
  +--com.nttdocomo.lang.XObject

直系の既知のサブクラス:

XString

public abstract class XObject

extends Object

携帯電話のネイティブが管理しているデータで、 携帯電話外に持ち出せないデータを表すオブジェクトの基底クラスです。

XObjectの役割
XObjectは、 電話帳のデータなど携帯電話のネイティブの機能により管理されているデータをiアプリから取得した場合に、 そのデータを携帯電話外に持ち出せないように導入された 特別な型のオブジェクトです。 XObjectは、 携帯電話のネイティブの管理データのうち 携帯電話外に持ち出すべきでないデータを取得した場合に生成されます。 アプリケーションが直接コンストラクタにより生成することはできません。 その内容を携帯電話外へ持ち出せないようにするために、 通常の型のオブジェクトと比べて限られた操作しか許されていません。 例えば文字列を表す通常の型はString型ですが、 String型のオブジェクトはHTTP接続やOBEX接続を用いて その内容を携帯電話外に送信することができます。 一方、文字列を表すXObjectはXString型ですが、 このオブジェクトに対しては長さの取得のみが許されており、 String型のようにHTTP接続やOBEX接続を用いて その内容を携帯電話外に送信することはできません。

携帯電話ネイティブのデータへのアクセス方法
携帯電話のネイティブが管理しているデータへのアクセス方法 およびそのXObjectとの関係を電話帳へのアクセスを例にとって説明します。

クラスメソッドとインスタンスの関係

電話帳へのアクセスを提供する機能は、 PhoneBookクラスにより提供されます。 このクラスのクラスメソッドにより、 電話帳データ(エントリ)の取得(選択および参照)、登録機能を提供します。 このクラスのオブジェクトは、 クラスメソッドにより取得された電話帳データのエントリを表します。

XObjectによるデータの保護

電話帳における名前、読み仮名、電話番号、メールアドレス、グループ名などを PhoneBookオブジェクトから取り出すことができますが、 それらは原則的にXObject またはそのサブクラスのオブジェクトとして取得されます。 すなわち、これらの電話帳データを携帯電話外へ持ち出すことはできません。

エントリID

電話帳の各エントリにはユニークなIDがつけられています。 これはメモリ番号などとは別のものです。 また、電話帳のエントリIDとブックマークのエントリIDは無関係であり、 値が重複していることがあります。 参照するアプリケーションによって 同じエントリに対して異なるIDが与えられることはありません。
また、0, -1 は有効なエントリIDではなく、 特別な用途(登録の失敗を示す等)に使用されます。

エントリの取得(選択または参照)

エントリは、 selectEntry()、 getEntry(int) メソッドにより取得することができます。
selectEntryメソッドは、 ユーザの選択によりエントリを取得するメソッドです。 このメソッドを呼び出すと、 アプリケーションがサスペンドして ネイティブのユーザインタフェース(電話帳選択画面)が起動し、 取得するエントリをユーザが選択します。 選択後、アプリケーションはレジュームし、 戻り値としてPhoneBookオブジェクトが得られます。
getEntry(int)メソッドは、 ユーザの選択によらず、IDを指定してエントリを取得するメソッドです。 アプリケーションがサスペンドすることなく指定されたIDのエントリを取得します。

エントリの新規登録

エントリの新規登録は、クラスメソッド addEntry により行うことができます。 このメソッドを呼び出すと、 アプリケーションがサスペンドして ネイティブのユーザインタフェース(電話帳登録画面)が起動します。 登録画面には addEntry メソッドの引数に指定した内容が反映されています。 ユーザは、このネイティブのユーザインタフェースを通して、 登録内容をそのままあるいは変更して登録することができます。 登録後、アプリケーションはレジュームし、 戻り値から登録された電話帳エントリのIDが得られます。
登録するデータの内容によって、 引数の異なる複数のaddEntryメソッドが提供されることがあります。 PhoneBookクラスの場合、 電話帳グループを名前で指定する addEntry(String, String, String[], String[], String)メソッドと、 電話帳グループをIDで指定する addEntry(String, String, String[], String[], int)メソッドがあります。
addEntryメソッドにより電話帳エントリを登録すると、 戻り値から登録されたエントリのIDが得られます。 getEntry(int)メソッドの引数に このエントリIDを指定すると、 登録した電話帳エントリを得ることができます。

新規登録用オブジェクト

電話帳のように、1件のエントリにつき多くのデータが指定できる場合、 新規登録専用のオブジェクトが定義されます。 電話帳の場合には、PhoneBookParamクラスになります。 新規登録用オブジェクトは、コンストラクタにより生成することができます。 addEntry(PhoneBookParam) メソッドにより、 上記の新規登録と同様に電話帳データを登録することができます。

登録時の文字列

各クラスにおいて特別の規定をしない限り、 文字列はデフォルトのエンコーディングで評価されます。 電話帳の名前などとして渡された文字列が 端末が想定している範囲から外れている文字を含んでいる場合、 その文字を除いてネイティブの登録機能に渡されます。 また、端末が規定している最大文字数を超える文字列を設定した場合は、 超過分の文字は削除されます。
また、各クラスにおいて特別の規定をしない限り、 必須の指定項目(例えばブックマークのURL)以外のデータに対しては、 nullや空文字を指定することが可能です。 その場合、ネイティブの登録画面のユーザが入力できるフィールドにおいて、 そのフィールドは空白になっています。 ただし、複数個の指定が可能である項目 (電話帳の電話番号)では、空文字の要素が無視されることがあります。

取得時の文字列

各クラスにおいて特別の規定をしない限り、 エントリから登録されていない要素を取得した場合、 空文字列(または空文字列を表すXString)を返します。

既存エントリの上書き

新規登録において既存エントリの上書きは原則許可されません。 ただし、登録可能容量を超えて登録を試みたときに、 ユーザ確認の上で上書きをするようなネイティブの実装になっているのであれば、 そのような場合に限り上書きが許可されることがあります。

導入されたバージョン:

DoJa-3.0

関連項目:

XString

メソッドの概要

boolean	equals(Object obj) インスタンスの同一性をチェックします。
int	hashCode() このオブジェクトのハッシュ値を取得します。
String	toString() オブジェクトの文字列表現を取得します。

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

getClass, notify, notifyAll, wait, wait, wait

メソッドの詳細

equals

public final boolean equals(Object obj)

インスタンスの同一性をチェックします。 オブジェクトの内容についての同一性チェックは行いません。
(this == obj) と同じ結果を返します。

オーバーライド:

クラス Object 内の equals

パラメータ:

obj - 比較するオブジェクトを指定します。

戻り値:

同じオブジェクトである場合、true を返します。

hashCode

public final int hashCode()

このオブジェクトのハッシュ値を取得します。 ハッシュ値の計算には、オブジェクトの内容を使用しません。
java.lang.ObjectクラスのhashCodeメソッドで定義される規則は、 このクラスおよびそのサブクラスにも適用されます。

オーバーライド:

クラス Object 内の hashCode

戻り値:

このオブジェクトのハッシュ値を返します。

toString

public final String toString()

オブジェクトの文字列表現を取得します。 文字列表現には、オブジェクトの内容は反映されません。
java.lang.ObjectクラスのtoStringメソッドと同じ値を返します。

オーバーライド:

クラス Object 内の toString

戻り値:

このオブジェクトの文字列表現を返します。