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.IOException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032: import java.io.DataInputStream;
033: import java.io.DataOutputStream;
034:
035: /**
036: * This interface defines the server socket stream connection.
037: * <P>
038: * A server socket is accessed using a generic connection string
039: * with the host omitted. For example, <code>socket://:79</code>
040: * defines an inbound server socket on port <code>79</code>.
041: * The host can be discovered using the <code>getLocalAddress</code>
042: * method.
043: * </P>
044: * <P>
045: * The <code>acceptAndOpen()</code> method returns a
046: * <code>SocketConnection</code> instance. In addition to the
047: * normal <code>StreamConnection</code> behavior, the
048: * <code>SocketConnection</code> supports accessing the IP
049: * end point addresses of the live connection and access
050: * to socket options that control the buffering and timing delays
051: * associated with specific application usage of the connection.
052: * </P>
053: * <P>
054: * Access to server socket connections may be restricted by the
055: * security policy of the device. <code>Connector.open</code> MUST
056: * check access for the initial server socket connection and
057: * <code>acceptAndOpen</code> MUST check before returning
058: * each new <code>SocketConnection</code>.
059: * </P>
060: * <P>
061: * A server socket can be used to dynamically select an
062: * available port by omitting both the host and the port
063: * parameters in the connection URL string.
064: * For example, <code>socket://</code>
065: * defines an inbound server socket on a port which is allocated
066: * by the system.
067: * To discover the assigned port number use the
068: * <code>getLocalPort</code> method.
069: * </P>
070: * <H2>
071: * BNF Format for Connector.open() string
072: * </H2>
073: * <P>
074: * The URI must conform to the BNF syntax specified below. If the URI
075: * does not conform to this syntax, an <code>IllegalArgumentException</code>
076: * is thrown.
077: * </P>
078: * <TABLE BORDER="1">
079: * <TR>
080: * <TD><socket_connection_string> </TD>
081: * <TD>::= "<strong>socket://</strong>" |
082: * "<strong>socket://</strong>"<hostport> </TD>
083: * </TR>
084: * <TR>
085: * <TD><hostport> </TD>
086: * <TD>::= <I>host</I> ":" <I>port </I> </TD>
087: * </TR>
088: * <TR>
089: * <TD><host> </TD>
090: * <TD>::= omitted for inbound connections,
091: * See <a href="SocketConnection.html">SocketConnection</a>
092: * </TD>
093: * </TR>
094: * <TR>
095: * <TD><port> </TD>
096: * <TD>::= <I>numeric port number </I>(omitted for system assigned port) </TD>
097: * </TR>
098: * </TABLE>
099: * <H2>
100: * Examples
101: * </H2>
102: * <P>
103: * The following examples show how a <code>ServerSocketConnection</code>
104: * would be used to access a sample loopback program.
105: * </P>
106: * <PRE>
107: * // Create the server listening socket for port 1234
108: * ServerSocketConnection scn = (ServerSocketConnection)
109: * Connector.open("socket://:1234");
110: *
111: * // Wait for a connection.
112: * SocketConnection sc = (SocketConnection) scn.acceptAndOpen();
113: *
114: * // Set application specific hints on the socket.
115: * sc.setSocketOption(DELAY, 0);
116: * sc.setSocketOption(LINGER, 0);
117: * sc.setSocketOption(KEEPALIVE, 0);
118: * sc.setSocketOption(RCVBUF, 128);
119: * sc.setSocketOption(SNDBUF, 128);
120: *
121: * // Get the input stream of the connection.
122: * DataInputStream is = sc.openDataInputStream();
123: *
124: * // Get the output stream of the connection.
125: * DataOutputStream os = sc.openDataOutputStream();
126: *
127: * // Read the input data.
128: * String result = is.readUTF();
129: *
130: * // Echo the data back to the sender.
131: * os.writeUTF(result);
132: *
133: * // Close everything.
134: * is.close();
135: * os.close();
136: * sc.close();
137: * scn.close();
138: * ..
139: * </PRE>
140: */
141: public interface ServerSocketConnection extends
142: StreamConnectionNotifier {
143:
144: /**
145: * Gets the local address to which the socket is bound.
146: *
147: * <P>The host address(IP number) that can be used to connect to this
148: * end of the socket connection from an external system.
149: * Since IP addresses may be dynamically assigned, a remote application
150: * will need to be robust in the face of IP number reassignment.</P>
151: * <P> The local hostname (if available) can be accessed from
152: * <code> System.getProperty("microedition.hostname")</code>
153: * </P>
154: *
155: * @return the local address to which the socket is bound.
156: * @exception IOException if the connection was closed
157: * @see SocketConnection
158: */
159: public String getLocalAddress() throws IOException;
160:
161: /**
162: * Returns the local port to which this socket is bound.
163: *
164: * @return the local port number to which this socket is connected.
165: * @exception IOException if the connection was closed
166: * @see SocketConnection
167: */
168: public int getLocalPort() throws IOException;
169:
170: }
|