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 interface defines the capabilities that a datagram connection
033: * must have.
034: * <p>
035: * Reminder: Since the CLDC Specification does not define any
036: * actual network protocol implementations, the syntax for
037: * datagram addressing is not defined in the CLDC Specification.
038: * Rather, syntax definition takes place at the level of J2ME
039: * profiles such as MIDP.
040: * <p>
041: * In the sample implementation that is provided as part of the
042: * CLDC implementation, the following addressing scheme
043: * is used:
044: * <p>
045: * The parameter string describing the target of a connection
046: * in the CLDC implementation takes the following form:
047: *
048: * <pre>
049: * {protocol}://[{host}]:[{port}]
050: * </pre>
051: *
052: * A datagram connection can be opened in a "client" mode or "server" mode.
053: * If the "//{host}" part is missing then the connection is opened as
054: * a "server" (by "server", we mean that a client application initiates
055: * communication). When the "//{host}" part is specified, the connection
056: * is opened as a "client".
057: * <p>
058: * Examples:
059: * <p>
060: * A datagram connection for accepting datagrams<br>
061: * datagram://:1234<p>
062: * A datagram connection for sending to a server:<br>
063: * datagram://123.456.789.12:1234<p>
064: *
065: * Note that the port number in "server mode" (unspecified host name) is
066: * that of the receiving port. The port number in "client mode" (host name
067: * specified) is that of the target port. The reply-to port in both cases
068: * is never unspecified. In "server mode", the same port number is used for
069: * both receiving and sending. In "client mode", the reply-to port is
070: * always dynamically allocated.
071: * <p>
072: * Also note that the allocation of datagram objects is done in a
073: * more abstract way than in Java 2 Standard Edition (J2SE).
074: * Instead of providing a concrete <code>DatagramPacket</code> class,
075: * an abstract <code>Datagram</code> interface is provided. This
076: * is to allow a single platform to support several different datagram
077: * interfaces simultaneously. Datagram objects must be allocated by
078: * calling the <code>newDatagram</code> methods of the
079: * <code>DatagramConnection</code> object.
080: * The resulting object is defined using another interface type
081: * called <code>javax.microedition.io.Datagram</code>.
082: *
083: * @version 12/17/01 (CLDC 1.1)
084: * @since CLDC 1.0
085: */
086: public interface DatagramConnection extends Connection {
087:
088: /**
089: * Get the maximum length a datagram can be.
090: * Maximum length determines the maximum size
091: * of the datagram that can be created using
092: * the <code>newDatagram</code> method, and the
093: * maximum size of the datagram that can be sent
094: * or received.
095: *
096: * @return The maximum length of a datagram.
097: * @exception IOException If an I/O error occurs.
098: */
099: public int getMaximumLength() throws IOException;
100:
101: /**
102: * Get the nominal length of a datagram.
103: * Nominal length refers to the size of the
104: * datagram that is stored into the data buffer.
105: * Nominal length may be equal or
106: * less than the maximum length of the datagram.
107: *
108: * @return The nominal length of a datagram.
109: * @exception IOException If an I/O error occurs.
110: */
111: public int getNominalLength() throws IOException;
112:
113: /**
114: * Send a datagram. The <code>Datagram</code> object includes
115: * the information indicating the data to be sent, its length,
116: * and the address of the receiver. The method sends <code>length</code>
117: * bytes starting at the current <code>offset</code> of the
118: * <code>Datagram</code> object, where <code>length</code>
119: * and <code>offset</code> are internal state variables
120: * of the <code>Datagram</code> object.
121: *
122: * @param dgram A datagram.
123: * @exception IOException If an I/O error occurs.
124: * @exception InterruptedIOException Timeout or interrupt occurred.
125: */
126: public void send(Datagram dgram) throws IOException;
127:
128: /**
129: * Receive a datagram. When this method returns, the internal
130: * buffer in the <code>Datagram</code> object is filled with
131: * the data received, starting at the location determined by
132: * the <code>offset</code> state variable, and the data is
133: * ready to be read using the methods of the
134: * <code>DataInput</code> interface.
135: * <p>
136: * This method blocks until a datagram is received. The internal
137: * <code>length</code> state variable in the <code>Datagram</code>
138: * object contains the length of the received datagram. If the
139: * received data is longer than the length of the internal buffer
140: * minus offset, data is truncated.
141: * <p>
142: * This method does not change the internal <i>read/write<i> state
143: * variable of the <code>Datagram</code> object. Use method
144: * <code>Datagram.reset</code> to change the pointer before
145: * reading if necessary.
146: *
147: * @param dgram A datagram.
148: * @exception IOException If an I/O error occurs.
149: * @exception InterruptedIOException Timeout or interrupt occurred.
150: */
151: public void receive(Datagram dgram) throws IOException;
152:
153: /**
154: * Create a new datagram object.
155: *
156: * @param size The size of the buffer needed
157: * for the datagram
158: * @return A new datagram
159: * @exception IOException If an I/O error occurs.
160: * @exception IllegalArgumentException if the size is negative
161: * or larger than the maximum size
162: */
163: public Datagram newDatagram(int size) throws IOException;
164:
165: /**
166: * Create a new datagram object.
167: *
168: * @param size The size of the buffer needed
169: * for the datagram
170: * @param addr The I/O address to which the datagram
171: * will be sent
172: * @return A new datagram
173: * @exception IOException If an I/O error occurs.
174: * @exception IllegalArgumentException if the size is negative or
175: * larger than the maximum size, or if the
176: * address parameter is invalid
177: */
178: public Datagram newDatagram(int size, String addr)
179: throws IOException;
180:
181: /**
182: * Create a new datagram object.
183: *
184: * @param buf The buffer to be used for the datagram
185: * @param size The size of the buffer needed
186: * for the datagram
187: * @return A new datagram
188: * @exception IOException If an I/O error occurs.
189: * @exception IllegalArgumentException if the size is negative or
190: * larger than the maximum size or the given
191: * buffer's length, or if the buffer parameter
192: * is invalid
193: */
194: public Datagram newDatagram(byte[] buf, int size)
195: throws IOException;
196:
197: /**
198: * Make a new datagram object.
199: *
200: * @param buf The buffer to be used for the datagram
201: * @param size The size of the buffer needed
202: * for the datagram
203: * @param addr The I/O address to which the datagram
204: * will be sent
205: * @return A new datagram
206: * @exception IOException If an I/O error occurs.
207: * @exception IllegalArgumentException if the size is negative or
208: * larger than the maximum size or the given
209: * buffer's length, or if the address or
210: * buffer parameter is invalid
211: */
212: public Datagram newDatagram(byte[] buf, int size, String addr)
213: throws IOException;
214:
215: }
|