javax.microedition.io
Interface Datagram

All Superinterfaces:
DataInput, DataOutput
All Known Implementing Classes:
DatagramBase

public interface Datagram
extends DataInput, DataOutput

This is the generic datagram interface. It represents an object that will act as the holder of data to be sent or received from a datagram connection.

The DataInput and DataOutput interfaces are extended by this interface to provide a simple way to read and write binary data in and out of the datagram buffer. An additional function reset() may be called to reset the read/write point to the beginning of the buffer.

It should be noted that in the interests of reducing space and speed concerns, these mechanisms are very simple. In order to use them correctly the following restrictions should be observed:

1) The use of the standard DataInput and DataOutput interfaces is done in order to provide a familiar API for reading and writing data into and out of a Datagram buffer. It should be understood however that this is not an API to a Java stream and does not exhibit all of the features normally associated with one. The most important difference here is that a Java stream is either an InputStream or an OutputStream. The interface presented here is, essentially, both at the same time. As the datagram object does not have a mode for reading and writing, it is necessary for the application programmer to realize that no automatic detection of the wrong mode usage can be done.

2) The DataInput and DataOutput interfaces will not work with any arbitrary settings of the Datagram state variables. The main restriction here is that the offset state variable must at all times be zero. Datagrams may be used in the normal way where the offset is non-zero but when this is done the DataInput and DataOutput interfaces cannot be used.

3) The DataInput and DataOutput read() and write() functions work by using an invisible state variable of the Datagram object. Before any data is read from or written to the datagram buffer, this state variable must be zeroed using the reset() function. This variable is not the offset state variable but an additional state variable used only for the read() and write() functions.

4) Before data is to be received into the datagram's buffer, the offset state variable and the length state variable must first be set up to the part of the buffer the data should be written to. If the intention is to use the read() functions, the offset must be zero. After receive() is called, the data can be read from the buffer using the read() functions until an EOF condition is found. This will occur when the number of characters represented by the length parameter have been read.

5) To write data into the buffer prior to a send() operation, the reset() function should first be called. This will zero the read/write pointer along with the offset and length parameters of the Datagram object. Then the data can be written using the write() functions. When this process is complete, the length state variable will be set to the correct value for the send() function of the datagram's connection, and so the send operation can take place. An IndexOutOfBoundsException will be thrown if the number of characters written exceeds the size of the buffer.

Blocking Operations

This interface performs blocking Input and Output operations. An application will lock if an implementation of this interface opens a connection from within the main event thread. Prevent an application from locking by opening a connection from within a thread that is separate from the main event thread. SeeConnector for more information.


Method Summary
 String getAddress()
          Get the address in the datagram
 byte[] getData()
          Get the buffer
 int getLength()
          Get the length
 int getOffset()
          Get the offset
 void reset()
          Zero the read/write pointer as well as the offset and length parameters.
 void setAddress(Datagram reference)
          Set datagram address, copying the address from another datagram.
 void setAddress(String addr)
          Set the datagram address.
 void setData(byte[] buffer, int offset, int len)
          Set the buffer, offset and length
 void setLength(int len)
          Set the length
 
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 in the datagram
Returns:
the address in string form, or null if no address was set

getData

public byte[] getData()
Get the buffer
Returns:
the data buffer

getLength

public int getLength()
Get the length
Returns:
the length of the data

getOffset

public int getOffset()
Get the offset
Returns:
the offset into the data buffer

reset

public void reset()
Zero the read/write pointer as well as the offset and length parameters.

setAddress

public void setAddress(Datagram reference)
Set datagram address, copying the address from another datagram.
Parameters:
reference - the datagram who's address will be copied as the new target address for this datagram.
Throws:
IllegalArgumentException - if the address is not valid

setAddress

public void setAddress(String addr)
                throws IOException
Set the datagram address.

The address string needs to be in the form: "[//IP_ADDRESS][:DEST_PORT][;SRC_PORT][/APN][|TYPE(s)][;tunnelauthusername=/APN_USERNAME]] [;tunnelauthpassword=/APN_PASSWORD]]", where:

  • IP_ADDRESS -- IP address in dotted, ASCII-decimal form
  • DEST_PORT -- Destination port in ASCII-decimal form
  • SRC_PORT -- Source port in ASCII-decimal form
  • APN -- Access point name in string form
  • TYPE -- Packet type: UDP, GPAK, or GCMP. APN_USERNAME -- Access point authentication credentials: username APN_PASSWORD -- Access point authentication credentials: password

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

setData

public void setData(byte[] buffer,
                    int offset,
                    int len)
Set the buffer, offset and length
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 fall outside the buffer

setLength

public void setLength(int len)
Set the length
Parameters:
len - the new length of the data
Throws:
IllegalArgumentException - if the length is negative or larger than the buffer



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.