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.lang.IllegalArgumentException;
030: import java.io.IOException;
031: import java.lang.String;
032:
033: /**
034: * This interface defines the socket stream connection.
035: * <P>
036: * A socket is accessed using a generic connection string with an explicit host
037: * and port number. The host may be specified as a fully qualified host name or
038: * IPv4 number.
039: * e.g. <code>socket://host.com:79</code> defines a target socket on the
040: * <code>host.com</code> system at
041: * port <code>79</code>.
042: * <P>Note that
043: * RFC1900 recommends the use of names rather than IP numbers for best results
044: * in the event of IP number reassignment. </P>
045: * <H3> Closing Streams </H3>
046: * <P>
047: * Every <code>StreamConnection</code> provides a <code>Connection</code>
048: * object as well as an <code>InputStream</code> and <code>OutputStream</code>
049: * to handle the I/O associated with the connection. Each of these interfaces
050: * has its own <code>close()</code> method. For systems that support
051: * duplex communication over the socket connection, closing of the
052: * input or output stream SHOULD shutdown just that side of the
053: * connection. e.g. closing the <code>InputStream</code> will permit the
054: * <code>OutputStream</code> to continue sending data.
055: * </P>
056: * <P>
057: * Once the input or output stream has been closed, it can only be reopened
058: * with a call to <code>Connector.open()</code>. The application will receive
059: * an <code>IOException</code> if an attempt is made to reopen the stream.
060: * </P>
061: * <H2>
062: * BNF Format for Connector.open() string
063: * </H2>
064: * <P>
065: * The URI must conform to the BNF syntax specified below. If the URI
066: * does not conform to this syntax, an <code>IllegalArgumentException</code>
067: * is thrown.
068: * </P>
069: * <TABLE BORDER="1">
070: * <TR>
071: * <TD><socket_connection_string> </TD>
072: * <TD>::= "<strong>socket://</strong>"<hostport> </TD>
073: * </TR>
074: * <TR>
075: * <TD><hostport> </TD>
076: * <TD>::= <I>host</I> ":" <I>port </I> </TD>
077: * </TR>
078: * <TR>
079: * <TD><host> </TD>
080: * <TD>::= <I>host name or IP address </I> (omitted for inbound connections,
081: * See <a href="ServerSocketConnection.html">ServerSocketConnection</a>)
082: * </TD>
083: * </TR>
084: * <TR>
085: * <TD><port> </TD>
086: * <TD>::= <I>numeric port number </I> </TD>
087: * </TR>
088: * </TABLE>
089: * <H3>
090: * Examples
091: * </H3>
092: * <P>
093: * The following examples show how a <code>SocketConnection</code>
094: * would be used to access a sample loopback program.
095: * </P>
096: * <PRE>
097: * SocketConnection sc = (SocketConnection)
098: * Connector.open("socket://host.com:79");
099: * sc.setSocketOption(SocketConnection.LINGER, 5);
100: *
101: * InputStream is = sc.openInputStream();
102: * OutputStream os = sc.openOutputStream();
103: *
104: * os.write("\r\n".getBytes());
105: * int ch = 0;
106: * while(ch != -1) {
107: * ch = is.read();
108: * }
109: *
110: * is.close();
111: * os.close();
112: * sc.close();
113: * </PRE>
114: */
115: public interface SocketConnection extends StreamConnection {
116:
117: /**
118: * Socket option for the small buffer <em>writing delay</em> (0).
119: * Set to zero to disable Nagle algorithm for
120: * small buffer operations.
121: * Set to a non-zero value to enable.
122: */
123: public final byte DELAY = 0;
124:
125: /**
126: * Socket option for the <em>linger time</em> to wait in seconds
127: * before closing a connection with
128: * pending data output (1). Setting the linger time to zero
129: * disables the linger wait interval.
130: */
131: public final byte LINGER = 1;
132:
133: /**
134: * Socket option for the <em>keep alive</em> feature (2).
135: * Setting KEEPALIVE to zero will disable the feature.
136: * Setting KEEPALIVE to a non-zero value will enable the feature.
137: */
138: public final byte KEEPALIVE = 2;
139:
140: /**
141: * Socket option for the size of the <em>receiving buffer</em> (3).
142: */
143: public final byte RCVBUF = 3;
144:
145: /**
146: * Socket option for the size of the <em>sending buffer</em> (4).
147: */
148: public final byte SNDBUF = 4;
149:
150: /**
151: * Set a socket option for the connection.
152: * <P>
153: * Options inform the low level networking code about intended
154: * usage patterns that the application will use in dealing with
155: * the socket connection.
156: * </P>
157: * <P>
158: * Calling <code>setSocketOption</code> to assign buffer sizes
159: * is a hint to the platform of the sizes to set the underlying
160: * network I/O buffers.
161: * Calling <code>getSocketOption</code> can be used to see what
162: * sizes the system is using.
163: * The system MAY adjust the buffer sizes to account for
164: * better throughput available from Maximum Transmission Unit
165: * (MTU) and Maximum Segment Size (MSS) data available
166: * from current network information.
167: * </P>
168: *
169: * @param option socket option identifier (KEEPALIVE, LINGER,
170: * SNDBUF, RCVBUF, or DELAY)
171: * @param value numeric value for specified option
172: * @exception IllegalArgumentException if the value is not
173: * valid (e.g. negative value) or if the option
174: * identifier is not valid
175: * @exception IOException if the connection was closed
176: *
177: * @see #getSocketOption
178: */
179: public void setSocketOption(byte option, int value)
180: throws IllegalArgumentException, IOException;
181:
182: /**
183: * Get a socket option for the connection.
184: *
185: * @param option socket option identifier (KEEPALIVE, LINGER,
186: * SNDBUF, RCVBUF, or DELAY)
187: * @return numeric value for specified option or -1 if the
188: * value is not available.
189: * @exception IllegalArgumentException if the option identifier is
190: * not valid
191: * @exception IOException if the connection was closed
192: * @see #setSocketOption
193: */
194: public int getSocketOption(byte option)
195: throws IllegalArgumentException, IOException;
196:
197: /**
198: * Gets the local address to which the socket is bound.
199: *
200: * <P>The host address(IP number) that can be used to connect to this
201: * end of the socket connection from an external system.
202: * Since IP addresses may be dynamically assigned, a remote application
203: * will need to be robust in the face of IP number reassignment.</P>
204: * <P> The local hostname (if available) can be accessed from
205: * <code> System.getProperty("microedition.hostname")</code>
206: * </P>
207: *
208: * @return the local address to which the socket is bound.
209: * @exception IOException if the connection was closed.
210: * @see ServerSocketConnection
211: */
212: public String getLocalAddress() throws IOException;
213:
214: /**
215: * Returns the local port to which this socket is bound.
216: *
217: * @return the local port number to which this socket is connected.
218: * @exception IOException if the connection was closed.
219: * @see ServerSocketConnection
220: */
221: public int getLocalPort() throws IOException;
222:
223: /**
224: * Gets the remote address to which the socket is bound.
225: * The address can be either the remote host name or the IP
226: * address(if available).
227: *
228: * @return the remote address to which the socket is bound.
229: * @exception IOException if the connection was closed.
230: */
231: public String getAddress() throws IOException;
232:
233: /**
234: * Returns the remote port to which this socket is bound.
235: *
236: * @return the remote port number to which this socket is connected.
237: * @exception IOException if the connection was closed.
238: */
239: public int getPort() throws IOException;
240: }
|