javax.microedition.io.Datagram Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 219: Foundation Profile 1.1. In the event of a discrepency between this work and the JSR 219 specification, which is available at http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence. */ package javax.microedition.io; import java.io.*; /** * 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);
 * 

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

* 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 ...
 *    }
 * 

 *    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 ...
 *    }
 * 

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

* 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. * * @return the data buffer as a byte array * * @see #setData */ public byte[] getData(); /** * Get the length of the datagram. * * @return the length state variable * * @see #setLength */ public int getLength(); /** * Get the offset. * * @return the offset state variable */ public int getOffset(); /** * Set datagram address. * *The address must be in the form "datagram://{host}:{port}". * *