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

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

DataInput, DataOutput

public interface Datagram
extends DataInput, DataOutput

このクラスは、データグラムパケットの抽象インタフェースを定義します。このインタフェースの実装には、DatagramConnection オブジェクトとの間で送受信されるデータが格納されます。

これはインタフェースクラスなので、データグラムパケットの内部構造は、ここでは定義されません。しかし、このインタフェースの各実装は、次のフィールド/状態変数 (実際の実装とこれらのフィールドの名前は異なる可能性がある) を提供することになっています。

• buffer:データが格納される内部バッファー
• offset:内部バッファーの読み取り/書き込みオフセット
• length:データグラムパケット内のデータの長さ
• address:送信先アドレスまたはソースアドレス
• read/write pointer:offset に追加するポインタ (読み取りまたは書き込み操作中に現在のデータ位置をポイント可能)

読み取りと書き込み

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()

reset

void reset()

read/write pointer と、状態変数 offset および length の値をゼロにします。