socketconnection.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)SocketConnection.java	1.18 02/07/24 @(#)
 *
 * Copyright (c) 2001-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.io;

import java.lang.IllegalArgumentException;
import java.io.IOException;
import java.lang.String;

/**
 * This interface defines the socket stream connection.
 * <P>
 * A socket is accessed using a generic connection string with an explicit host 
 * and port number. The host may be specified as a fully qualified host name or 
 * IPv4 number.
 * e.g. <code>socket://host.com:79</code> defines a target socket on the 
 * <code>host.com</code> system at 
 * port <code>79</code>.
 * <P>Note that 
 * RFC1900 recommends the use of names rather than IP numbers for best results
 * in the event of IP number reassignment. </P>
 * <H3> Closing Streams </H3>
 * <P>
 * Every <code>StreamConnection</code> provides a <code>Connection</code>
 * object as well as an <code>InputStream</code> and <code>OutputStream</code>
 * to handle the I/O associated with the connection. Each of these interfaces
 * has its own <code>close()</code> method. For systems that support
 * duplex communication over the socket connection, closing of the 
 * input or output stream SHOULD shutdown just that side of the 
 * connection. e.g. closing the <code>InputStream</code> will permit the
 * <code>OutputStream</code> to continue sending data.
 * </P>
 * <P>
 * Once the input or output stream has been closed, it can only be reopened
 * with a call to <code>Connector.open()</code>. The application will receive
 * an <code>IOException</code> if an attempt is made to reopen the stream.
 * </P>
 * <H2>
 * BNF Format for Connector.open() string
 * </H2>
 * <P>
 * The URI must conform to the BNF syntax specified below.  If the URI
 * does not conform to this syntax, an <code>IllegalArgumentException</code>
 * is thrown.
 * </P>
 * <TABLE BORDER="1">
 * <TR>
 * <TD>&lt;socket_connection_string&gt; </TD>
 * <TD>::= "<strong>socket://</strong>"&lt;hostport&gt; </TD>
 * </TR>
 * <TR>
 * <TD>&lt;hostport&gt; </TD>
 * <TD>::= <I>host</I> ":" <I>port </I> </TD>
 * </TR>
 * <TR>
 * <TD>&lt;host&gt; </TD>
 * <TD>::= <I>host name or IP address </I> (omitted for inbound connections,
 * See <a href="ServerSocketConnection.html">ServerSocketConnection</a>)
 * </TD>
 * </TR>
 * <TR>
 * <TD>&lt;port&gt; </TD>
 * <TD>::= <I>numeric port number </I> </TD>
 * </TR>
 * </TABLE>
 * <H3>
 * Examples
 * </H3>
 * <P>
 * The following examples show how a <code>SocketConnection</code>
 * would be used to access a sample loopback program.
 * </P>
 * <PRE>
 *   SocketConnection sc = (SocketConnection)
 *                         Connector.open("socket://host.com:79");
 *   sc.setSocketOption(SocketConnection.LINGER, 5);
 *
 *   InputStream is  = sc.openInputStream();
 *   OutputStream os = sc.openOutputStream();
 *
 *   os.write("\r\n".getBytes());
 *   int ch = 0;
 *   while(ch != -1) {
 *       ch = is.read();
 *   }
 *
 *   is.close();
 *   os.close();
 *   sc.close();
 * </PRE>
 * @since MIDP 2.0
 */
public interface SocketConnection
    extends StreamConnection  {

    /**
     * Socket option for the small buffer <em>writing delay</em> (0).
     * Set to zero to disable Nagle algorithm for 
     * small buffer operations.
     * Set to a non-zero value to enable.
     */
    public final byte DELAY = 0; 
 
    /**
     * Socket option for the <em>linger time</em> to wait in seconds
     * before closing a connection with
     * pending data output (1). Setting the linger time to zero
     * disables the linger wait interval.
     */
    public final byte LINGER = 1;

    /**
     * Socket option for the <em>keep alive</em> feature (2).
     * Setting KEEPALIVE to zero will disable the feature.
     * Setting KEEPALIVE to a non-zero value will enable the feature.
     */
    public final byte KEEPALIVE = 2;


    /**
     * Socket option for the size of the <em>receiving buffer</em> (3).
     */
    public final byte RCVBUF = 3;

    /**
     * Socket option for the size of the <em>sending buffer</em> (4).
     */
    public final byte SNDBUF = 4;

    /**
     * Set a socket option for the connection.
     * <P>
     * Options inform the low level networking code about intended
     * usage patterns that the application will use in dealing with
     * the socket connection.
     * </P>
     * <P>
     * Calling <code>setSocketOption</code> to assign buffer sizes
     * is a hint to the platform of the sizes to set the underlying 
     * network I/O buffers.
     * Calling <code>getSocketOption</code> can  be used to see what 
     * sizes the system is using.
     * The system MAY adjust the buffer sizes to account for 
     * better throughput available from Maximum Transmission Unit
     * (MTU) and Maximum Segment Size (MSS) data available 
     * from current network information.
     * </P>
     *
     * @param option socket option identifier (KEEPALIVE, LINGER,
     * SNDBUF, RCVBUF, or DELAY)
     * @param value numeric value for specified option
     * @exception  IllegalArgumentException if  the value is not
     *              valid (e.g. negative value) or if the option
     *              identifier is not valid
     * @exception  IOException  if the connection was closed
     *
     * @see #getSocketOption
     */
    public void setSocketOption(byte option,  int value)
	throws IllegalArgumentException, IOException;

    /**
     * Get a socket option for the connection.
     *
     * @param option socket option identifier (KEEPALIVE, LINGER,
     * SNDBUF, RCVBUF, or DELAY)
     * @return  numeric value for specified option or -1 if the
     *  value is not available.
     * @exception IllegalArgumentException if the option identifier is
     *  not valid
     * @exception  IOException  if the connection was closed
     * @see #setSocketOption
     */
    public  int getSocketOption(byte option)
	throws IllegalArgumentException, IOException;

    /**
     * Gets the local address to which the socket is bound.
     *
     * <P>The host address(IP number) that can be used to connect to this
     * end of the socket connection from an external system.
     * Since IP addresses may be dynamically assigned, a remote application
     * will need to be robust in the face of IP number reasssignment.</P>
     * <P> The local hostname (if available) can be accessed from
     * <code> System.getProperty("microedition.hostname")</code>
     * </P>
     *
     * @return the local address to which the socket is bound.
     * @exception  IOException  if the connection was closed.
     * @see ServerSocketConnection
     */
    public  String getLocalAddress() throws IOException;

    /**
     * Returns the local port to which this socket is bound.
     *
     * @return the local port number to which this socket is connected.
     * @exception  IOException  if the connection was closed.
     * @see ServerSocketConnection
     */
    public  int  getLocalPort() throws IOException;

    /**
     * Gets the remote address to which the socket is bound.
     * The address can be either the remote host name or the IP
     * address(if available).
     *
     * @return the remote address to which the socket is bound.
     * @exception  IOException  if the connection was closed.
     */
    public  String getAddress() throws IOException;

    /**
     * Returns the remote port to which this socket is bound.
     *
     * @return the remote port number to which this socket is connected.
     * @exception  IOException  if the connection was closed.
     */
    public  int  getPort() throws IOException;
}