javax.microedition.io
インタフェース Datagram

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

DataInput, DataOutput

public interface Datagram
extends DataInput, DataOutput

このクラスはデータグラム・パケットのための抽象的なインタフェースを定義します。 このインタフェースの実装は、DatagramConnection から送信するか、または受信したデータを保持します。

これはインタフェース・クラスであるため、データグラム・パケットの内部構造をここでは定義しません。 しかし、このインタフェースの各実装が、以下のフィールド / 状態変数を提供するでしょう（実際の実装とこれらのフィールドの名前は異なるかもしれません）。

• buffef : データを保存する内部バッファ
• offset : 内部バッファの読み書きを行うためのオフセット
• length : データグラム・パケットのデータ長
• address : 送信元または送信先アドレス
• read/write pointer : 読み書き操作を行う際に、現在のデータ位置を示すために offset に加算するポインタ

読み出しと書き込み

Datagram インタフェースは、getData および setData メソッドを使用する代わりにデータグラム・バッファの内外のバイナリ・データを簡単に読み書きする手段を提供するためにインタフェース DataInput および DataOutput を継承します。 書き込みによって自動的に length は増加します。そして read/write pointer は length 以下において読み出しを継続することができます。 全ての書き込みもなされる前に reset を呼び出さなければなりません。 読み出しまたは書き込みに setData() を使用するつもりであるなら、0 以外の offset パラメータへの任意の値はサポートされません。

データグラムを書く例:

 datagram = connection.newDatagram(max);
 
 // データグラムに新しいメッセージを書き込む前にリセットします。
 datagram.reset();
 
 // writeUTF は自動的にデータグラムの長さを拡張します。
 datagram.writeUTF("hello world");
 

データグラムから読み出す例（１度の使用のみ）:

 datagram = connection.newDatagram(max);
 connection.receive(datagram);
 message = datagram.readUTF();
 

データグラムの再利用

getLength によって返される length は、時々によって異なる意味を持つことがあることに注目すべきです。 送信する時には length は送信バイト数です。 受信する前の length は受信することができる最大バイト数です。 受信した後の length は受信したバイト数です。 データグラムを受信した後に送信または受信するために再利用する時には、setLength(int) を使用して長さの最大値を設定しなおさなければなりません。

 datagram = connection.newDatagram(max);
 
 while (notDone) {
     // ループにおける最後の受信が長さを変更したため、
     // 最大の長さにそれを設定しなおします。
     datagram.setLength(max);
     connection.receive(datagram);
 
     data = datagram.getData();
     bytesReceived = datagram.getLength();
 
     // データグラムの処理....
 }
 

getData を使用せずに読み出しを行うなら、reset() メソッドを使用しなければなりません。

 datagram = connection.newDatagram(max);
 
 while (notDone) {
 
     // ループにおける最後の読み出しが読み出しポインタを変更したため、
     // ポインタをリセットします。
     datagram.reset();
     datagram.setLength(max);
     connection.receive(datagram);
 
     message = datagram.readUTF(message);
 
     // メッセージ処理....
 }
 

データグラムを再度読み出す例:

 connection.receive(datagram);
 message = datagram.readUTF(message);
 len = datagram.getLength();
 datagram.reset();
 datagram.setLength(len);
 copy = datagram.readUTF(message);
 

導入されたバージョン:

CLDC 1.0

getAddress

String getAddress()

データグラムのアドレスを返します。

戻り値:

アドレスを文字列形式で返します。アドレスが設定されていない場合は null を返します。

関連項目:

setAddress(java.lang.String)

getData

byte[] getData()

データグラムのデータ・バッファを返します。

実装によっては、このメソッドは内部バッファかそれのコピーのいずれかを返します。 しかし、ユーザーはこのメソッドで返されたデータを変更することによって内部データ・バッファの内容を変更することができると仮定してはなりません。 そうではなく、setData メソッドを使用することによって内部バッファの内容を変更すべきです。

戻り値:

データ・バッファを指す byte 配列を返します。

関連項目:

setData(byte[], int, int)

getLength

int getLength()

データグラムの長さを返します（データグラムの長さとはデータ・バッファ内のデータの長さのことを指します）。

戻り値:

データグラムの長さを返します。

関連項目:

setLength(int)

getOffset

int getOffset()

データ・バッファ内のオフセットを返します。

戻り値:

データ・バッファ内のオフセットを返します。

setAddress

void setAddress(String address)
                throws IOException

データグラムのアドレスを設定します。

アドレスは“{protocol}:{target}”の形式で指定します。 {protocol} の名前と {target} の記述形式についてはデバイスの実装に依存します。

データグラムのアドレスを設定しない場合、オープンした接続のアドレスを使用します。

パラメータ:

address - 設定するアドレスを渡します。

例外:

IllegalArgumentException - アドレスが無効な場合に throw します。

IOException - 入出力操作で問題が発生した場合に throw します。

関連項目:

getAddress()

setAddress

void setAddress(Datagram source)

指定したデータグラムのアドレスを新しいデータグラムのアドレスにコピーします。

パラメータ:

source - コピーするアドレスを含むデータグラムを渡します。

例外:

IllegalArgumentException - アドレスが無効な場合に throw します。

関連項目:

getAddress()

setLength

void setLength(int len)

データグラムの長さを設定します。 len による指定が負数な場合あるいはバッファを越えている場合には IllegalArgumentException を throw します。

パラメータ:

len - 設定するデータグラムの長さを渡します。

例外:

IllegalArgumentException - 指定された長さが不適切な場合に throw します。

関連項目:

getLength()

setData

void setData(byte[] buffer,
             int offset,
             int len)

データ・バッファ、バッファ内のオフセット、バッファ内のデータ長を設定します。 実装によって、この操作はバッファをコピーするか、または単純に buffer パラメータの値を内部の状態変数 buffer に設定することがあります。 しかし、ユーザーはこの操作で渡したバッファを変更することによって内部データ・バッファの内容を変更することができると仮定してはなりません。

パラメータ:

buffer - 設定するデータ・バッファを渡します。

offset - 設定するデータ・バッファ内のオフセットを渡します。

len - 設定するデータ・バッファ内のデータの長さを渡します。

例外:

IllegalArgumentException - offset あるいは len による指定が不適切な場合に throw します。

関連項目:

getData()

reset

void reset()

データの書き込みおよび読み取りのポインタ（read/write pointer）をリセットし、オフセット（offset）およびデータの長さ（length）をゼロにします。