Datagram (Foundation Profile, version 1.1.2)

Datagram インタフェースは、DataInput インタフェースと DataOutput インタフェースを拡張することにより、getData メソッドや setData メソッドを使用しないで、データグラムバッファーのバイナリデータの読み取り/書き込みを単純に実行できるようにします。書き込みを行うと、length の値が自動的に大きくなります。読み取りは、read/write pointer の値が length の値より小さい間、続行されます。書き込みの実行前に、reset を呼び出す必要があります。読み取り/書き込み時に setData() を使用した場合、offset パラメータの値として使用できるのはゼロだけになります。

次に、データグラムへの書き込みの例を示します。

    datagram = connection.newDatagram(max);

    // reset により、データグラムに新しいメッセージを書き込む準備を行う。
    datagram.reset();

    // writeUTF はデータグラムの長さの値を自動的に大きくする。
    datagram.writeUTF("hello world");

    connection.send(datagram);

次に、データグラムからの読み取りの例を示します (単独使用のみ)。

    datagram = connection.newDatagram(max);

    connection.receive(datagram);

    message = datagram.readUTF();

データグラムの再利用

前述の length は getLength によって返され、そのつど意味が異なる可能性があることに注意してください。たとえば送信時、length は送信バイト数を表します。受信前、length は最大受信可能バイト数を表します。受信後、length は受信済みバイト数を表します。このため、送受信を行なったあと、データグラムを再利用して受信を行う場合は、setLength を使用して、length を最大受信可能バイト数に設定し直してください。

    datagram = connection.newDatagram(max);

    while (notDone) {

        // ループ内の前回の受信で length が変更されたので
        // この値を最大受信可能バイト数に戻す
        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

メソッドの概要
`String`	`getAddress()` データグラムのアドレスを取得します。
`byte[]`	`getData()` データバッファーの内容を取得します。
`int`	`getLength()` データグラムの長さを取得します。
`int`	`getOffset()` オフセットを取得します。
`void`	`reset()` `read/write pointer` と、状態変数 `offset` および `length` の値をゼロにします。
`void`	`setAddress(Datagram reference)` データグラムアドレスを設定して、別のデータグラムからアドレスをコピーします。
`void`	`setAddress(String addr)` データグラムアドレスを設定します。
`void`	`setData(byte[] buffer, int offset, int len)` 状態変数 `buffer`、`offset`、および `length` を設定します。
`void`	`setLength(int len)` `length` 状態変数を設定します。

インタフェース java.io.DataInput から継承されたメソッド
`readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes`

インタフェース java.io.DataOutput から継承されたメソッド
`write, write, write, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF`

メソッドの詳細

getAddress

String getAddress()

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

戻り値:: 「datagram://{host}:{port}」の形式のアドレス。アドレスが設定されていない場合は null
関連項目:: setAddress(java.lang.String)

getData

byte[] getData()

データバッファーの内容を取得します。

実装によっては、この操作を実行すると、内部バッファーかそのコピーが返されることがあります。しかし、この操作の実行後に返されたデータを変更して、内部データバッファーの内容を操作できるとは考えてはいけません。内部バッファーの内容を変更するには、setData 操作を使用してください。

戻り値:: byte 配列として返されるデータバッファー
関連項目:: setData(byte[], int, int)

getLength

int getLength()

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

戻り値:: length 状態変数
関連項目:: setLength(int)

getOffset

int getOffset()

オフセットを取得します。

戻り値:: offset 状態変数

setAddress

void setAddress(String addr)
                throws IOException

データグラムアドレスを設定します。アドレスは「datagram://{host}:{port}」の形式にします。

データグラムのアドレスを指定しないと、そのアドレスのデフォルト値は接続のアドレスになります。

パラメータ:: addr - URL として指定する新しいターゲットアドレス
例外:: IllegalArgumentException - アドレスが無効な場合; IOException - なんらかの入出力エラーが発生した場合
関連項目:: getAddress()

setAddress

void setAddress(Datagram reference)

データグラムアドレスを設定して、別のデータグラムからアドレスをコピーします。

パラメータ:: reference - このデータグラムの新しいターゲットアドレスとしてコピーされるアドレスを持つデータグラム
例外:: IllegalArgumentException - アドレスが無効な場合
関連項目:: getAddress()

setLength

void setLength(int len)

length 状態変数を設定します。

パラメータ:: len - データグラムの新しい長さ
例外:: IllegalArgumentException - 長さまたは長さとオフセットの和がバッファーの大きさを超える場合
関連項目:: getLength()

setData

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

状態変数 buffer、offset、および length を設定します。実装により、この操作を実行すると、バッファーがコピーされる場合も、状態変数 buffer に buffer 引数の値が設定されるだけの場合もあります。しかし、この操作に渡されたバッファーを変更して、内部データバッファーの内容を操作できるとは考えてはいけません。

パラメータ:: buffer - データバッファー; offset - データバッファー内のオフセット; len - バッファー内のデータの長さ
例外:: IllegalArgumentException - 長さ、オフセット、またはオフセットと長さの和がバッファーの大きさを超える場合、あるいはバッファーパラメータが無効な場合
関連項目:: getData()