Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.io
Interface Datagram

All Superinterfaces:
  DataInput, DataOutput

public interface Datagram
extends DataInput, DataOutput

This class defines an abstract interface for datagram packets. The implementations of this interface hold data to be sent or received from a `DatagramConnection` object.

Since this is an interface class, the internal structure of the datagram packets is not defined here. However, it is assumed that each implementation of this interface will provide the following fields / state variables (the actual implementation and the names of these fields may vary):

- buffer: the internal buffer in which data is stored
- offset: the read/write offset for the internal buffer
- length: the length of the data in datagram packet
- address: the destination or source address
- read/write pointer: a pointer that is added to the offset to point to the current data location during a read or write operation

Reading and Writing

The `Datagram` interface extends interfaces `DataInput` and `DataOutput` in order to provide a simple way to read and write binary data in and out of the datagram buffer instead of using `getData` and `setData` methods. Writing automatically increments length and reading will continue while the read/write pointer is less than length. Before any writing is done reset must be called. If `setData()` is to be used when reading or writing, any value for the `offset` parameter other than 0 is not supported.

For example to write to datagram:

        datagram = connection.newDatagram(max);

        // Reset prepares the datagram for writing new message.
        datagram.reset();

        // writeUTF automatically increases the datagram length.
        datagram.writeUTF("hello world");

        connection.send(datagram);

For example to read from a datagram (single use only):

        datagram = connection.newDatagram(max);

        connection.receive(datagram);

        message = datagram.readUTF();

Reusing Datagrams

It should be noted the length above is returned from `getLength` and can have different meanings at different times. When sending length is the number of bytes to send. Before receiving length is the maximum number of bytes to receive. After receiving length is the number of bytes that were received. So when reusing a datagram to receive after sending or receiving, length must be set back to the maximum using `setLength`.

        datagram = connection.newDatagram(max);

        while (notDone) {

            // The last receive in the loop changed the length
            // so put it back to the maximum length.
            datagram.setLength(max);
            connection.receive(datagram);

            data = datagram.getData();
            bytesReceived = datagram.getLength();

            // process datagram ...
        }

When reading instead of using `getData` the `reset` method must be used.

        datagram = connection.newDatagram(max);

        while (notDone) {

            // The last read in the loop changed the read pointer
            // so reset the pointer.
            datagram.reset();
            datagram.setLength(max);
            connection.receive(datagram);

            message = datagram.readUTF(message);

            // process message ...
        }

For example to reread a datagram:

        connection.receive(datagram);

        message = datagram.readUTF(message);

        len = datagram.getLength();

        datagram.reset();

        datagram.setLength(len);

        copy = datagram.readUTF(message);

Since:
  CLDC 1.0

Method Summary
`String` | `getAddress()` Get the address of the datagram.
`byte[]` | `getData()` Get the contents of the data buffer.
`int` | `getLength()` Get the length of the datagram.
`int` | `getOffset()` Get the offset.
`void` | `reset()` Zero the `read/write pointer` as well as the `offset` and `length` state variables.
`void` | `setAddress(Datagram reference)` Set datagram address, copying the address from another datagram.
`void` | `setAddress(String addr)` Set datagram address.
`void` | `setData(byte[] buffer, int offset, int len)` Set the `buffer`, `offset` and `length` state variables.
`void` | `setLength(int len)` Set the `length` state variable.

Methods inherited from interface java.io.DataInput
`readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes`

Methods inherited from interface java.io.DataOutput
`write, write, write, writeBoolean, writeByte, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF`

Method Detail

### getAddress

    public String getAddress()

  Get the address of the datagram.

  Returns:
    the address in string form, or null if no address was set
  See Also:
    `setAddress(java.lang.String)`

### getData

    public byte[] getData()

  Get the contents of the data buffer.

  Depending on the implementation, this operation may return the internal buffer or a copy of it. However, the user must not assume that the contents of the internal data buffer can be manipulated by modifying the data returned by this operation. Rather, the `setData` operation should be used for changing the contents of the internal buffer.

  Returns:
    the data buffer as a byte array
  See Also:
    `setData(byte[], int, int)`

### getLength

    public int getLength()

  Get the length of the datagram.

  Returns:
    the length state variable
  See Also:
    `setLength(int)`

### getOffset

    public int getOffset()

  Get the offset.

  Returns:
    the offset state variable

### setAddress

    public void setAddress(String addr)
                    throws IOException

  Set datagram address.

  The actual addressing scheme is implementation-dependent. Please read the general comments on datagram addressing in `DatagramConnection.java`.

  Note that if the address of a datagram is not specified, then it defaults to that of the connection.

  Parameters:
    `addr` - the new target address as a URL
  Throws:
    `IllegalArgumentException` - if the address is not valid
    `IOException` - if a some kind of I/O error occurs
  See Also:
    `getAddress()`

### setAddress

    public void setAddress(Datagram reference)

  Set datagram address, copying the address from another datagram.

  Parameters:
    `reference` - to the datagram whose address will be copied as the new target address for this datagram.
  Throws:
    `IllegalArgumentException` - if the address is not valid
  See Also:
    `getAddress()`

### setLength

    public void setLength(int len)

  Set the `length` state variable.

  Parameters:
    `len` - the new length of the datagram
  Throws:
    `IllegalArgumentException` - if the length or length plus offset fall outside the buffer
  See Also:
    `getLength()`

### setData

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

  Set the `buffer`, `offset` and `length` state variables. Depending on the implementation, this operation may copy the buffer or just set the state variable `buffer` to the value of the `buffer` argument. However, the user must not assume that the contents of the internal data buffer can be manipulated by modifying the buffer passed on to this operation.

  Parameters:
    `buffer` - the data buffer
    `offset` - the offset into the data buffer
    `len` - the length of the data in the buffer
  Throws:
    `IllegalArgumentException` - if the length or offset or offset plus length fall outside the buffer, or if the buffer parameter is invalid
  See Also:
    `getData()`

### reset

    public void reset()

  Zero the `read/write pointer` as well as the `offset` and `length` state variables.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of IM Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.