001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.io.*;
030:
031: /**
032: * This class defines an abstract interface for datagram packets.
033: * The implementations of this interface hold data to be
034: * sent or received from a <code>DatagramConnection</code> object.
035: * <p>
036: * Since this is an interface class, the internal structure
037: * of the datagram packets is not defined here. However, it is
038: * assumed that each implementation of this interface will
039: * provide the following fields / state variables (the actual
040: * implementation and the names of these fields may vary):
041: * <ul>
042: * <li><i>buffer</i>: the internal buffer in which data is stored
043: * <li><i>offset</i>: the read/write offset for the internal buffer
044: * <li><i>length</i>: the length of the data in datagram packet
045: * <li><i>address</i>: the destination or source address
046: * <li><i>read/write pointer</i>: a pointer that is added to the
047: * <i>offset</i> to point to the current data location during a
048: * read or write operation
049: * </ul>
050: * <p>
051: * <strong>Reading and Writing</strong>
052: * <p>
053: * The <code>Datagram</code> interface extends interfaces
054: * <code>DataInput</code> and <code>DataOutput</code> in order
055: * to provide a simple way to read and write binary data in and out of
056: * the datagram buffer instead of using <code>getData</code> and
057: * <code>setData</code> methods. Writing automatically increments
058: * <i>length</i> and reading will continue while the <i>read/write pointer</i>
059: * is less than <i>length</i>. Before any writing is done reset must be called.
060: * If <code>setData()</code> is to be used when reading or writing, any value
061: * for the <code>offset</code> parameter other than 0 is not supported.
062: * <p>
063: * For example to write to datagram:
064: * <pre>
065: * datagram = connection.newDatagram(max);
066: *
067: * // Reset prepares the datagram for writing new message.
068: * datagram.reset();
069: *
070: * // writeUTF automatically increases the datagram length.
071: * datagram.writeUTF("hello world");
072: *
073: * connection.send(datagram);
074: * </pre>
075: * For example to read from a datagram (single use only):
076: * <pre>
077: * datagram = connection.newDatagram(max);
078: *
079: * connection.receive(datagram);
080: *
081: * message = datagram.readUTF();
082: * </pre>
083: * <strong>Reusing Datagrams</strong>
084: * <p>
085: * It should be noted the <i>length</i> above is returned
086: * from <code>getLength</code> and can have different meanings at different
087: * times. When sending <i>length</i> is the number of bytes to send. Before
088: * receiving <i>length</i> is the maximum number of bytes to receive.
089: * After receiving <i>length</i> is the number of bytes that were received.
090: * So when reusing a datagram to receive after sending or receiving, length
091: * must be set back to the maximum using <code>setLength</code>.
092: * <pre>
093: * datagram = connection.newDatagram(max);
094: *
095: * while (notDone) {
096: *
097: * // The last receive in the loop changed the length
098: * // so put it back to the maximum length.
099: * datagram.setLength(max);
100: * connection.receive(datagram);
101: *
102: * data = datagram.getData();
103: * bytesReceived = datagram.getLength();
104: *
105: * // process datagram ...
106: * }
107: * </pre>
108: * When reading instead of using <code>getData</code> the <code>reset</code>
109: * method must be used.
110: * <pre>
111: * datagram = connection.newDatagram(max);
112: *
113: * while (notDone) {
114: *
115: * // The last read in the loop changed the read pointer
116: * // so reset the pointer.
117: * datagram.reset();
118: * datagram.setLength(max);
119: * connection.receive(datagram);
120: *
121: * message = datagram.readUTF(message);
122: *
123: * // process message ...
124: * }
125: * </pre>
126: * For example to reread a datagram:
127: * <pre>
128: * connection.receive(datagram);
129: *
130: * message = datagram.readUTF(message);
131: *
132: * len = datagram.getLength();
133: *
134: * datagram.reset();
135: *
136: * datagram.setLength(len);
137: *
138: * copy = datagram.readUTF(message);
139: * </pre>
140: *
141: * @version 12/17/01 (CLDC 1.1)
142: * @since CLDC 1.0
143: */
144: public interface Datagram extends DataInput, DataOutput {
145:
146: /**
147: * Get the address of the datagram.
148: *
149: * @return the address in string form, or null if no address was set
150: *
151: * @see #setAddress
152: */
153: public String getAddress();
154:
155: /**
156: * Get the contents of the data buffer.
157: * <p>
158: * Depending on the implementation, this operation may return
159: * the internal buffer or a copy of it. However, the user
160: * must not assume that the contents of the internal data
161: * buffer can be manipulated by modifying the data returned by
162: * this operation. Rather, the <code>setData</code> operation
163: * should be used for changing the contents of the internal
164: * buffer.
165: *
166: * @return the data buffer as a byte array
167: *
168: * @see #setData
169: */
170: public byte[] getData();
171:
172: /**
173: * Get the length of the datagram.
174: *
175: * @return the length state variable
176: *
177: * @see #setLength
178: */
179: public int getLength();
180:
181: /**
182: * Get the offset.
183: *
184: * @return the offset state variable
185: */
186: public int getOffset();
187:
188: /**
189: * Set datagram address.
190: * <p>
191: * The actual addressing scheme is implementation-dependent.
192: * Please read the general comments on datagram addressing
193: * in <code>DatagramConnection.java</code>.
194: * <p>
195: * Note that if the address of a datagram is not specified, then
196: * it defaults to that of the connection.
197: *
198: * @param addr the new target address as a URL
199: * @exception IllegalArgumentException if the address is not valid
200: * @exception IOException if a some kind of I/O error occurs
201: *
202: * @see #getAddress
203: */
204: public void setAddress(String addr) throws IOException;
205:
206: /**
207: * Set datagram address, copying the address from another datagram.
208: *
209: * @param reference to the datagram whose address will be copied as
210: * the new target address for this datagram.
211: * @exception IllegalArgumentException if the address is not valid
212: *
213: * @see #getAddress
214: */
215: public void setAddress(Datagram reference);
216:
217: /**
218: * Set the <code>length</code> state variable.
219: *
220: * @param len the new length of the datagram
221: * @exception IllegalArgumentException if the length or length plus offset
222: * fall outside the buffer
223: *
224: * @see #getLength
225: */
226: public void setLength(int len);
227:
228: /**
229: * Set the <code>buffer</code>, <code>offset</code> and <code>length</code>
230: * state variables. Depending on the implementation, this operation may
231: * copy the buffer or just set the state variable <code>buffer</code>
232: * to the value of the <code>buffer</code> argument. However,
233: * the user must not assume that the contents of the internal data
234: * buffer can be manipulated by modifying the buffer passed on to
235: * this operation.
236: *
237: * @param buffer the data buffer
238: * @param offset the offset into the data buffer
239: * @param len the length of the data in the buffer
240: * @exception IllegalArgumentException if the length or offset
241: * or offset plus length fall outside the
242: * buffer, or if the buffer parameter is invalid
243: * @see #getData
244: */
245: public void setData(byte[] buffer, int offset, int len);
246:
247: /**
248: * Zero the <code>read/write pointer</code> as well as the
249: * <code>offset</code> and <code>length</code> state variables.
250: */
251: public void reset();
252:
253: }
|