1. /*

  2.  * @(#)SocketOptions.java	1.20 00/02/02

  3.  *

  4.  * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.net;

  12. 

  13. /**

  14.  * Interface of methods to get/set socket options.  This interface is

  15.  * implemented by: <B>SocketImpl</B> and  <B>DatagramSocketImpl</B>.

  16.  * Subclasses of these should override the methods

  17.  * of this interface in order to support their own options.

  18.  * <P>

  19.  * The methods and constants which specify options in this interface are

  20.  * for implementation only.  If you're not subclassing SocketImpl or

  21.  * DatagramSocketImpl, <B>you won't use these directly.</B> There are

  22.  * type-safe methods to get/set each of these options in Socket, ServerSocket,

  23.  * DatagramSocket and MulticastSocket.

  24.  * <P>

  25.  * A subset of the standard BSD-style socket options are supported in the

  26.  * base classes, <B>PlainSocketImpl</B> and <B>PlainDatagramSocketImpl</B>.

  27.  * A brief description of each and their use is provided.

  28.  * <P>

  29.  * @version 1.20, 02/02/00

  30.  * @author David Brown

  31.  */

  32. 

  33. 

  34. public interface SocketOptions {

  35. 

  36.     /**

  37.      * Enable/disable the option specified by <I>optID</I>.  If the option

  38.      * is to be enabled, and it takes an option-specific "value",  this is

  39.      * passed in <I>value</I>.  The actual type of value is option-specific,

  40.      * and it is an error to pass something that isn't of the expected type:

  41.      * <BR><PRE>

  42.      * SocketImpl s;

  43.      * ...

  44.      * s.setOption(SO_LINGER, new Integer(10));

  45.      *    // OK - set SO_LINGER w/ timeout of 10 sec.

  46.      * s.setOption(SO_LINGER, new Double(10));

  47.      *    // ERROR - expects java.lang.Integer

  48.      *</PRE>

  49.      * If the requested option is binary, it can be set using this method by

  50.      * a java.lang.Boolean:

  51.      * <BR><PRE>

  52.      * s.setOption(TCP_NODELAY, new Boolean(true));

  53.      *    // OK - enables TCP_NODELAY, a binary option

  54.      * </PRE>

  55.      * <BR>

  56.      * Any option can be disabled using this method with a Boolean(false):

  57.      * <BR><PRE>

  58.      * s.setOption(TCP_NODELAY, new Boolean(false));

  59.      *    // OK - disables TCP_NODELAY

  60.      * s.setOption(SO_LINGER, new Boolean(false));

  61.      *    // OK - disables SO_LINGER

  62.      * </PRE>

  63.      * <BR>

  64.      * For an option that has a notion of on and off, and requires 

  65.      * a non-boolean parameter, setting its value to anything other than

  66.      * <I>Boolean(false)</I> implicitly enables it.

  67.      * <BR>

  68.      * Throws SocketException if the option is unrecognized,

  69.      * the socket is closed, or some low-level error occurred

  70.      * <BR>

  71.      * @param optID identifies the option

  72.      * @param value the parameter of the socket option

  73.      * @throws SocketException if the option is unrecognized,

  74.      * the socket is closed, or some low-level error occurred

  75.      * @see #getOption(int)

  76.      */

  77.     public void

  78. 	setOption(int optID, Object value) throws SocketException;

  79. 

  80.     /**

  81.      * Fetch the value of an option.

  82.      * Binary options will return java.lang.Boolean(true)

  83.      * if enabled, java.lang.Boolean(false) if disabled, e.g.:

  84.      * <BR><PRE>

  85.      * SocketImpl s;

  86.      * ...

  87.      * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));

  88.      * if (noDelay.booleanValue()) {

  89.      *     // true if TCP_NODELAY is enabled...

  90.      * ...

  91.      * }

  92.      * </PRE>

  93.      * <P>

  94.      * For options that take a particular type as a parameter,

  95.      * getOption(int) will return the paramter's value, else

  96.      * it will return java.lang.Boolean(false):

  97.      * <PRE>

  98.      * Object o = s.getOption(SO_LINGER);

  99.      * if (o instanceof Integer) {

  100.      *     System.out.print("Linger time is " + ((Integer)o).intValue());

  101.      * } else {

  102.      *   // the true type of o is java.lang.Boolean(false);

  103.      * }

  104.      * </PRE>

  105.      *

  106.      * @param optID an <code>int</code> identifying the option to fetch

  107.      * @return the value of the option

  108.      * @throws SocketException if the socket is closed

  109.      * @throws SocketException if <I>optID</I> is unknown along the

  110.      *         protocol stack (including the SocketImpl)

  111.      * @see #setOption(int, java.lang.Object)

  112.      */

  113.     public Object getOption(int optID) throws SocketException;

  114. 

  115.     /**

  116.      * The java-supported BSD-style options.

  117.      */

  118. 

  119.     /**

  120.      * Disable Nagle's algorithm for this connection.  Written data

  121.      * to the network is not buffered pending acknowledgement of

  122.      * previously written data.

  123.      *<P>

  124.      * Valid for TCP only: SocketImpl.

  125.      * <P>

  126.      * @see Socket#setTcpNoDelay

  127.      * @see Socket#getTcpNoDelay

  128.      */

  129. 

  130.     public final static int TCP_NODELAY = 0x0001;

  131. 

  132.     /**

  133.      * Fetch the local address binding of a socket (this option cannot

  134.      * be "set" only "gotten", since sockets are bound at creation time,

  135.      * and so the locally bound address cannot be changed).  The default local

  136.      * address of a socket is INADDR_ANY, meaning any local address on a

  137.      * multi-homed host.  A multi-homed host can use this option to accept

  138.      * connections to only one of its addresses (in the case of a

  139.      * ServerSocket or DatagramSocket), or to specify its return address

  140.      * to the peer (for a Socket or DatagramSocket).  The parameter of

  141.      * this option is an InetAddress.

  142.      * <P>

  143.      * This option <B>must</B> be specified in the constructor.

  144.      * <P>

  145.      * Valid for: SocketImpl, DatagramSocketImpl

  146.      * <P>

  147.      * @see Socket#getLocalAddress

  148.      * @see DatagramSocket#getLocalAddress

  149.      */

  150. 

  151.     public final static int SO_BINDADDR = 0x000F;

  152. 

  153.     /** Sets SO_REUSEADDR for a socket.  This is used only for MulticastSockets

  154.      * in java, and it is set by default for MulticastSockets.

  155.      * <P>

  156.      * Valid for: DatagramSocketImpl

  157.      */

  158. 

  159.     public final static int SO_REUSEADDR = 0x04;

  160. 

  161.     /** Set which outgoing interface on which to send multicast packets.

  162.      * Useful on hosts with multiple network interfaces, where applications

  163.      * want to use other than the system default.  Takes/returns an InetAddress.

  164.      * <P>

  165.      * Valid for Multicast: DatagramSocketImpl

  166.      * <P>

  167.      * @see MulticastSocket#setInterface

  168.      * @see MulitcastSocket#getInterface

  169.      */

  170. 

  171.     public final static int IP_MULTICAST_IF = 0x10;

  172. 

  173.     /**

  174.      * Specify a linger-on-close timeout.  This option disables/enables

  175.      * immediate return from a <B>close()</B> of a TCP Socket.  Enabling

  176.      * this option with a non-zero Integer <I>timeout</I> means that a

  177.      * <B>close()</B> will block pending the transmission and acknowledgement

  178.      * of all data written to the peer, at which point the socket is closed

  179.      * <I>gracefully</I>.  Upon reaching the linger timeout, the socket is

  180.      * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a

  181.      * timeout of zero does a forceful close immediately. If the specified

  182.      * timeout value exceeds 65,535 it will be reduced to 65,535.

  183.      * <P>

  184.      * Valid only for TCP: SocketImpl

  185.      * 

  186.      * @see Socket#setSoLinger

  187.      * @see Socket#getSoLinger

  188.      */

  189.     public final static int SO_LINGER = 0x0080;

  190. 

  191.     /** Set a timeout on blocking Socket operations:

  192.      * <PRE>

  193.      * ServerSocket.accept();

  194.      * SocketInputStream.read();

  195.      * DatagramSocket.receive();

  196.      * </PRE>

  197.      *

  198.      * <P> The option must be set prior to entering a blocking

  199.      * operation to take effect.  If the timeout expires and the

  200.      * operation would continue to block,

  201.      * <B>java.io.InterruptedIOException</B> is raised.  The Socket is

  202.      * not closed in this case.

  203.      *

  204.      * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl

  205.      *

  206.      * @see Socket#setSoTimeout

  207.      * @see ServerSocket#setSoTimeout

  208.      * @see DatagramSocket#setSoTimeout

  209.      */

  210.     public final static int SO_TIMEOUT = 0x1006;

  211. 

  212.     /**

  213.      * Set a hint the size of the underlying buffers used by the

  214.      * platform for outgoing network I/O. When used in set, this is a

  215.      * suggestion to the kernel from the application about the size of

  216.      * buffers to use for the data to be sent over the socket. When

  217.      * used in get, this must return the size of the buffer actually

  218.      * used by the platform when sending out data on this socket.

  219.      *

  220.      * Valid for all sockets: SocketImpl, DatagramSocketImpl

  221.      *

  222.      * @see Socket#setSendBufferSize

  223.      * @see Socket#getSendBufferSize

  224.      * @see DatagramSocket#setSendBufferSize

  225.      * @see DatagramSocket#getSendBufferSize

  226.      */

  227.     public final static int SO_SNDBUF = 0x1001;

  228. 

  229.     /**

  230.      * Set a hint the size of the underlying buffers used by the

  231.      * platform for incoming network I/O. When used in set, this is a

  232.      * suggestion to the kernel from the application about the size of

  233.      * buffers to use for the data to be received over the

  234.      * socket. When used in get, this must return the size of the

  235.      * buffer actually used by the platform when receiving in data on

  236.      * this socket.

  237.      *

  238.      * Valid for all sockets: SocketImpl, DatagramSocketImpl

  239.      *

  240.      * @see Socket#setReceiveBufferSize

  241.      * @see Socket#getReceiveBufferSize

  242.      * @see DatagramSocket#setReceiveBufferSize

  243.      * @see DatagramSocket#getReceiveBufferSize

  244.      */

  245.     public final static int SO_RCVBUF = 0x1002;

  246. 

  247.     /**

  248.      * When the keepalive option is set for a TCP socket and no data

  249.      * has been exchanged across the socket in either direction for 

  250.      * 2 hours (NOTE: the actual value is implementation dependent),

  251.      * TCP automatically sends a keepalive probe to the peer. This probe is a 

  252.      * TCP segment to which the peer must respond. 

  253.      * One of three responses is expected:

  254.      * 1. The peer responds with the expected ACK. The application is not 

  255.      *    notified (since everything is OK). TCP will send another probe 

  256.      *    following another 2 hours of inactivity.

  257.      * 2. The peer responds with an RST, which tells the local TCP that

  258.      *    the peer host has crashed and rebooted. The socket is closed.

  259.      * 3. There is no response from the peer. The socket is closed. 

  260.      *

  261.      * The purpose of this option is to detect if the peer host crashes. 

  262.      *

  263.      * Valid only for TCP socket: SocketImpl

  264.      *

  265.      * @see Socket#setKeepAlive

  266.      * @see Socket#getKeepAlive

  267.      */

  268.     public final static int SO_KEEPALIVE = 0x0008;

  269. }

  270. 

  271. 

  272. 

  273. 

  274. 

  275.