1. /*
  2. * @(#)SocketOptions.java 1.13 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.net;
  8. /**
  9. * Interface of methods to get/set socket options. This interface is
  10. * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>.
  11. * Subclasses of these should override the methods
  12. * of this interface in order to support their own options.
  13. * <P>
  14. * The methods and constants which specify options in this interface are
  15. * for implementation only. If you're not subclassing SocketImpl or
  16. * DatagramSocketImpl, <B>you won't use these directly.</B> There are
  17. * type-safe methods to get/set each of these options in Socket, ServerSocket,
  18. * DatagramSocket and MulticastSocket.
  19. * <P>
  20. * A subset of the standard BSD-style socket options are supported in the
  21. * JDK base classes, <B>PlainSocketImpl</B> and <B>PlainDatagramSocketImpl</B>.
  22. * A brief description of each and their use is provided.
  23. * <P>
  24. * @version 1.13, 11/29/01
  25. * @author David Brown
  26. */
  27. public interface SocketOptions {
  28. /**
  29. * Enable/disable the option specified by <I>optID</I>. If the option
  30. * is to be enabled, and it takes an option-specific "value", this is
  31. * passed in <I>value</I>. The actual type of value is option-specific,
  32. * and it is an error to pass something that isn't of the expected type:
  33. * <BR><PRE>
  34. * SocketImpl s;
  35. * ...
  36. * s.setOption(SO_LINGER, new Integer(10));
  37. * // OK - set SO_LINGER w/ timeout of 10 sec.
  38. * s.setOption(SO_LINGER, new Double(10));
  39. * // ERROR - expects java.lang.Integer
  40. *</PRE>
  41. * If the requested option is binary, it can be set using this method by
  42. * a java.lang.Boolean:
  43. * <BR><PRE>
  44. * s.setOption(TCP_NODELAY, new Boolean(true));
  45. * // OK - enables TCP_NODELAY, a binary option
  46. * </PRE>
  47. * <BR>
  48. * Any option can be disabled using this method with a Boolean(false):
  49. * <BR><PRE>
  50. * s.setOption(TCP_NODELAY, new Boolean(false));
  51. * // OK - disables TCP_NODELAY
  52. * s.setOption(SO_LINGER, new Boolean(false));
  53. * // OK - disables SO_LINGER
  54. * </PRE>
  55. * <BR>
  56. * For an option that requires a particular parameter,
  57. * setting its value to anything other than
  58. * <I>Boolean(false)</I> implicitly enables it.
  59. * <BR>
  60. * Throws SocketException if the option is unrecognized,
  61. * the socket is closed, or some low-level error occurred
  62. * <BR>
  63. * @param optID identifies the option
  64. * @param value the parameter of the socket option
  65. * @throws SocketException if the option is unrecognized,
  66. * the socket is closed, or some low-level error occurred
  67. */
  68. public void
  69. setOption(int optID, Object value) throws SocketException;
  70. /**
  71. * Fetch the value of an option.
  72. * Binary options will return java.lang.Boolean(true)
  73. * if enabled, java.lang.Boolean(false) if disabled, e.g.:
  74. * <BR><PRE>
  75. * SocketImpl s;
  76. * ...
  77. * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
  78. * if (noDelay.booleanValue()) {
  79. * // true if TCP_NODELAY is enabled...
  80. * ...
  81. * }
  82. * </PRE>
  83. * <P>
  84. * For options that take a particular type as a parameter,
  85. * getOption(int) will return the paramter's value, else
  86. * it will return java.lang.Boolean(false):
  87. * <PRE>
  88. * Object o = s.getOption(SO_LINGER);
  89. * if (o instanceof Integer) {
  90. * System.out.print("Linger time is " + ((Integer)o).intValue());
  91. * } else {
  92. * // the true type of o is java.lang.Boolean(false);
  93. * }
  94. * </PRE>
  95. *
  96. * @throws SocketException if the socket is closed
  97. * @throws SocketException if <I>optID</I> is unknown along the
  98. * protocol stack (including the SocketImpl)
  99. */
  100. public Object getOption(int optID) throws SocketException;
  101. /**
  102. * The java-supported BSD-style options.
  103. */
  104. /**
  105. * Disable Nagle's algorithm for this connection. Written data
  106. * to the network is not buffered pending acknowledgement of
  107. * previously written data.
  108. *<P>
  109. * Valid for TCP only: SocketImpl.
  110. * <P>
  111. * @see Socket#setTcpNoDelay
  112. * @see Socket#getTcpNoDelay
  113. */
  114. public final static int TCP_NODELAY = 0x0001;
  115. /**
  116. * Fetch the local address binding of a socket (this option cannot
  117. * be "set" only "gotten", since sockets are bound at creation time,
  118. * and so the locally bound address cannot be changed). The default local
  119. * address of a socket is INADDR_ANY, meaning any local address on a
  120. * multi-homed host. A multi-homed host can use this option to accept
  121. * connections to only one of its addresses (in the case of a
  122. * ServerSocket or DatagramSocket), or to specify its return address
  123. * to the peer (for a Socket or DatagramSocket). The parameter of
  124. * this option is an InetAddress.
  125. * <P>
  126. * This option <B>must</B> be specified in the constructor.
  127. * <P>
  128. * Valid for: SocketImpl, DatagramSocketImpl
  129. * <P>
  130. * @see Socket#getLocalAddress
  131. * @see Server#getLocalAddress
  132. * @see DatagramSocket#getLocalAddress
  133. */
  134. public final static int SO_BINDADDR = 0x000F;
  135. /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets
  136. * in java, and it is set by default for MulticastSockets.
  137. * <P>
  138. * Valid for: DatagramSocketImpl
  139. */
  140. public final static int SO_REUSEADDR = 0x04;
  141. /** Set which outgoing interface on which to send multicast packets.
  142. * Useful on hosts with multiple network interfaces, where applications
  143. * want to use other than the system default. Takes/returns an InetAddress.
  144. * <P>
  145. * Valid for Multicast: DatagramSocketImpl
  146. * <P>
  147. * @see MulticastSocket#setInterface
  148. * @see MulitcastSocket#getInterface
  149. */
  150. public final static int IP_MULTICAST_IF = 0x10;
  151. /**
  152. * Specify a linger-on-close timeout. This option disables/enables
  153. * immediate return from a <B>close()</B> of a TCP Socket. Enabling
  154. * this option with a non-zero Integer <I>timeout</I> means that a
  155. * <B>close()</B> will block pending the transmission and acknowledgement
  156. * of all data written to the peer, at which point the socket is closed
  157. * <I>gracefully</I>. Upon reaching the linger timeout, the socket is
  158. * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
  159. * timeout of zero does a forceful close immediately. If the specified
  160. * timeout value exceeds 65,535 it will be reduced to 65,535.
  161. * <P>
  162. * Valid only for TCP: SocketImpl
  163. *
  164. * @see Socket#setSoLinger
  165. * @see Socket#getSoLinger
  166. */
  167. public final static int SO_LINGER = 0x0080;
  168. /** Set a timeout on blocking Socket operations:
  169. * <PRE>
  170. * ServerSocket.accept();
  171. * SocketInputStream.read();
  172. * DatagramSocket.receive();
  173. * </PRE>
  174. *
  175. * <P> The option must be set prior to entering a blocking
  176. * operation to take effect. If the timeout expires and the
  177. * operation would continue to block,
  178. * <B>java.io.InterruptedIOException</B> is raised. The Socket is
  179. * not closed in this case.
  180. *
  181. * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
  182. *
  183. * @see Socket#setSoTimeout
  184. * @see ServerSocket#setSoTimeout
  185. * @see DatagramSocket#setSoTimeout
  186. */
  187. public final static int SO_TIMEOUT = 0x1006;
  188. /**
  189. * Set a hint the size of the underlying buffers used by the
  190. * platform for outgoing network I/O. When used in set, this is a
  191. * suggestion to the kernel from the application about the size of
  192. * buffers to use for the data to be sent over the socket. When
  193. * used in get, this must return the size of the buffer actually
  194. * used by the platform when sending out data on this socket.
  195. *
  196. * Valid for all sockets: SocketImpl, DatagramSocketImpl
  197. *
  198. * @see Socket#setSendSize
  199. * @see Socket#getSendBufferSize
  200. * @see DatagramSocket#setSendSize
  201. * @see DatagramSocket#getSendBufferSize
  202. */
  203. public final static int SO_SNDBUF = 0x1001;
  204. /**
  205. * Set a hint the size of the underlying buffers used by the
  206. * platform for incoming network I/O. When used in set, this is a
  207. * suggestion to the kernel from the application about the size of
  208. * buffers to use for the data to be received over the
  209. * socket. When used in get, this must return the size of the
  210. * buffer actually used by the platform when receiving in data on
  211. * this socket.
  212. *
  213. * Valid for all sockets: SocketImpl, DatagramSocketImpl
  214. *
  215. * @see Socket#setReceiveSize
  216. * @see Socket#getReceiveBufferSize
  217. * @see DatagramSocket#setReceiveSize
  218. * @see DatagramSocket#getReceiveBufferSize
  219. */
  220. public final static int SO_RCVBUF = 0x1002;
  221. }