src/share/classes/java/net/SocketOptions.java

Print this page




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.net;
  27 


  28 /**
  29  * Interface of methods to get/set socket options.  This interface is
  30  * implemented by: <B>SocketImpl</B> and  <B>DatagramSocketImpl</B>.
  31  * Subclasses of these should override the methods
  32  * of this interface in order to support their own options.
  33  * <P>
  34  * The methods and constants which specify options in this interface are
  35  * for implementation only.  If you're not subclassing SocketImpl or
  36  * DatagramSocketImpl, <B>you won't use these directly.</B> There are
  37  * type-safe methods to get/set each of these options in Socket, ServerSocket,
  38  * DatagramSocket and MulticastSocket.
  39  * <P>
  40  * @author David Brown
  41  */
  42 
  43 
  44 public interface SocketOptions {
  45 
  46     /**
  47      * Enable/disable the option specified by <I>optID</I>.  If the option


 120      *         protocol stack (including the SocketImpl)
 121      * @see #setOption(int, java.lang.Object)
 122      */
 123     public Object getOption(int optID) throws SocketException;
 124 
 125     /**
 126      * The java-supported BSD-style options.
 127      */
 128 
 129     /**
 130      * Disable Nagle's algorithm for this connection.  Written data
 131      * to the network is not buffered pending acknowledgement of
 132      * previously written data.
 133      *<P>
 134      * Valid for TCP only: SocketImpl.
 135      * <P>
 136      * @see Socket#setTcpNoDelay
 137      * @see Socket#getTcpNoDelay
 138      */
 139 
 140     public final static int TCP_NODELAY = 0x0001;
 141 
 142     /**
 143      * Fetch the local address binding of a socket (this option cannot
 144      * be "set" only "gotten", since sockets are bound at creation time,
 145      * and so the locally bound address cannot be changed).  The default local
 146      * address of a socket is INADDR_ANY, meaning any local address on a
 147      * multi-homed host.  A multi-homed host can use this option to accept
 148      * connections to only one of its addresses (in the case of a
 149      * ServerSocket or DatagramSocket), or to specify its return address
 150      * to the peer (for a Socket or DatagramSocket).  The parameter of
 151      * this option is an InetAddress.
 152      * <P>
 153      * This option <B>must</B> be specified in the constructor.
 154      * <P>
 155      * Valid for: SocketImpl, DatagramSocketImpl
 156      * <P>
 157      * @see Socket#getLocalAddress
 158      * @see DatagramSocket#getLocalAddress
 159      */
 160 
 161     public final static int SO_BINDADDR = 0x000F;
 162 
 163     /** Sets SO_REUSEADDR for a socket.  This is used only for MulticastSockets
 164      * in java, and it is set by default for MulticastSockets.
 165      * <P>
 166      * Valid for: DatagramSocketImpl
 167      */
 168 
 169     public final static int SO_REUSEADDR = 0x04;
 170 
 171     /**
 172      * Sets SO_BROADCAST for a socket. This option enables and disables
 173      * the ability of the process to send broadcast messages. It is supported
 174      * for only datagram sockets and only on networks that support
 175      * the concept of a broadcast message (e.g. Ethernet, token ring, etc.),
 176      * and it is set by default for DatagramSockets.
 177      * @since 1.4
 178      */
 179 
 180     public final static int SO_BROADCAST = 0x0020;
 181 
 182     /** Set which outgoing interface on which to send multicast packets.
 183      * Useful on hosts with multiple network interfaces, where applications
 184      * want to use other than the system default.  Takes/returns an InetAddress.
 185      * <P>
 186      * Valid for Multicast: DatagramSocketImpl
 187      * <P>
 188      * @see MulticastSocket#setInterface(InetAddress)
 189      * @see MulticastSocket#getInterface()
 190      */
 191 
 192     public final static int IP_MULTICAST_IF = 0x10;
 193 
 194     /** Same as above. This option is introduced so that the behaviour
 195      *  with IP_MULTICAST_IF will be kept the same as before, while
 196      *  this new option can support setting outgoing interfaces with either
 197      *  IPv4 and IPv6 addresses.
 198      *
 199      *  NOTE: make sure there is no conflict with this
 200      * @see MulticastSocket#setNetworkInterface(NetworkInterface)
 201      * @see MulticastSocket#getNetworkInterface()
 202      * @since 1.4
 203      */
 204     public final static int IP_MULTICAST_IF2 = 0x1f;
 205 
 206     /**
 207      * This option enables or disables local loopback of multicast datagrams.
 208      * This option is enabled by default for Multicast Sockets.
 209      * @since 1.4
 210      */
 211 
 212     public final static int IP_MULTICAST_LOOP = 0x12;
 213 
 214     /**
 215      * This option sets the type-of-service or traffic class field
 216      * in the IP header for a TCP or UDP socket.
 217      * @since 1.4
 218      */
 219 
 220     public final static int IP_TOS = 0x3;
 221 
 222     /**
 223      * Specify a linger-on-close timeout.  This option disables/enables
 224      * immediate return from a <B>close()</B> of a TCP Socket.  Enabling
 225      * this option with a non-zero Integer <I>timeout</I> means that a
 226      * <B>close()</B> will block pending the transmission and acknowledgement
 227      * of all data written to the peer, at which point the socket is closed
 228      * <I>gracefully</I>.  Upon reaching the linger timeout, the socket is
 229      * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
 230      * timeout of zero does a forceful close immediately. If the specified
 231      * timeout value exceeds 65,535 it will be reduced to 65,535.
 232      * <P>
 233      * Valid only for TCP: SocketImpl
 234      *
 235      * @see Socket#setSoLinger
 236      * @see Socket#getSoLinger
 237      */
 238     public final static int SO_LINGER = 0x0080;
 239 
 240     /** Set a timeout on blocking Socket operations:
 241      * <PRE>
 242      * ServerSocket.accept();
 243      * SocketInputStream.read();
 244      * DatagramSocket.receive();
 245      * </PRE>
 246      *
 247      * <P> The option must be set prior to entering a blocking
 248      * operation to take effect.  If the timeout expires and the
 249      * operation would continue to block,
 250      * <B>java.io.InterruptedIOException</B> is raised.  The Socket is
 251      * not closed in this case.
 252      *
 253      * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
 254      *
 255      * @see Socket#setSoTimeout
 256      * @see ServerSocket#setSoTimeout
 257      * @see DatagramSocket#setSoTimeout
 258      */
 259     public final static int SO_TIMEOUT = 0x1006;
 260 
 261     /**
 262      * Set a hint the size of the underlying buffers used by the
 263      * platform for outgoing network I/O. When used in set, this is a
 264      * suggestion to the kernel from the application about the size of
 265      * buffers to use for the data to be sent over the socket. When
 266      * used in get, this must return the size of the buffer actually
 267      * used by the platform when sending out data on this socket.
 268      *
 269      * Valid for all sockets: SocketImpl, DatagramSocketImpl
 270      *
 271      * @see Socket#setSendBufferSize
 272      * @see Socket#getSendBufferSize
 273      * @see DatagramSocket#setSendBufferSize
 274      * @see DatagramSocket#getSendBufferSize
 275      */
 276     public final static int SO_SNDBUF = 0x1001;
 277 
 278     /**
 279      * Set a hint the size of the underlying buffers used by the
 280      * platform for incoming network I/O. When used in set, this is a
 281      * suggestion to the kernel from the application about the size of
 282      * buffers to use for the data to be received over the
 283      * socket. When used in get, this must return the size of the
 284      * buffer actually used by the platform when receiving in data on
 285      * this socket.
 286      *
 287      * Valid for all sockets: SocketImpl, DatagramSocketImpl
 288      *
 289      * @see Socket#setReceiveBufferSize
 290      * @see Socket#getReceiveBufferSize
 291      * @see DatagramSocket#setReceiveBufferSize
 292      * @see DatagramSocket#getReceiveBufferSize
 293      */
 294     public final static int SO_RCVBUF = 0x1002;
 295 
 296     /**
 297      * When the keepalive option is set for a TCP socket and no data
 298      * has been exchanged across the socket in either direction for
 299      * 2 hours (NOTE: the actual value is implementation dependent),
 300      * TCP automatically sends a keepalive probe to the peer. This probe is a
 301      * TCP segment to which the peer must respond.
 302      * One of three responses is expected:
 303      * 1. The peer responds with the expected ACK. The application is not
 304      *    notified (since everything is OK). TCP will send another probe
 305      *    following another 2 hours of inactivity.
 306      * 2. The peer responds with an RST, which tells the local TCP that
 307      *    the peer host has crashed and rebooted. The socket is closed.
 308      * 3. There is no response from the peer. The socket is closed.
 309      *
 310      * The purpose of this option is to detect if the peer host crashes.
 311      *
 312      * Valid only for TCP socket: SocketImpl
 313      *
 314      * @see Socket#setKeepAlive
 315      * @see Socket#getKeepAlive
 316      */
 317     public final static int SO_KEEPALIVE = 0x0008;
 318 
 319     /**
 320      * When the OOBINLINE option is set, any TCP urgent data received on
 321      * the socket will be received through the socket input stream.
 322      * When the option is disabled (which is the default) urgent data
 323      * is silently discarded.
 324      *
 325      * @see Socket#setOOBInline
 326      * @see Socket#getOOBInline
 327      */
 328     public final static int SO_OOBINLINE = 0x1003;
 329 }


   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.net;
  27 
  28 import java.lang.annotation.Native;
  29 
  30 /**
  31  * Interface of methods to get/set socket options.  This interface is
  32  * implemented by: <B>SocketImpl</B> and  <B>DatagramSocketImpl</B>.
  33  * Subclasses of these should override the methods
  34  * of this interface in order to support their own options.
  35  * <P>
  36  * The methods and constants which specify options in this interface are
  37  * for implementation only.  If you're not subclassing SocketImpl or
  38  * DatagramSocketImpl, <B>you won't use these directly.</B> There are
  39  * type-safe methods to get/set each of these options in Socket, ServerSocket,
  40  * DatagramSocket and MulticastSocket.
  41  * <P>
  42  * @author David Brown
  43  */
  44 
  45 
  46 public interface SocketOptions {
  47 
  48     /**
  49      * Enable/disable the option specified by <I>optID</I>.  If the option


 122      *         protocol stack (including the SocketImpl)
 123      * @see #setOption(int, java.lang.Object)
 124      */
 125     public Object getOption(int optID) throws SocketException;
 126 
 127     /**
 128      * The java-supported BSD-style options.
 129      */
 130 
 131     /**
 132      * Disable Nagle's algorithm for this connection.  Written data
 133      * to the network is not buffered pending acknowledgement of
 134      * previously written data.
 135      *<P>
 136      * Valid for TCP only: SocketImpl.
 137      * <P>
 138      * @see Socket#setTcpNoDelay
 139      * @see Socket#getTcpNoDelay
 140      */
 141 
 142     @Native public final static int TCP_NODELAY = 0x0001;
 143 
 144     /**
 145      * Fetch the local address binding of a socket (this option cannot
 146      * be "set" only "gotten", since sockets are bound at creation time,
 147      * and so the locally bound address cannot be changed).  The default local
 148      * address of a socket is INADDR_ANY, meaning any local address on a
 149      * multi-homed host.  A multi-homed host can use this option to accept
 150      * connections to only one of its addresses (in the case of a
 151      * ServerSocket or DatagramSocket), or to specify its return address
 152      * to the peer (for a Socket or DatagramSocket).  The parameter of
 153      * this option is an InetAddress.
 154      * <P>
 155      * This option <B>must</B> be specified in the constructor.
 156      * <P>
 157      * Valid for: SocketImpl, DatagramSocketImpl
 158      * <P>
 159      * @see Socket#getLocalAddress
 160      * @see DatagramSocket#getLocalAddress
 161      */
 162 
 163     @Native public final static int SO_BINDADDR = 0x000F;
 164 
 165     /** Sets SO_REUSEADDR for a socket.  This is used only for MulticastSockets
 166      * in java, and it is set by default for MulticastSockets.
 167      * <P>
 168      * Valid for: DatagramSocketImpl
 169      */
 170 
 171     @Native public final static int SO_REUSEADDR = 0x04;
 172 
 173     /**
 174      * Sets SO_BROADCAST for a socket. This option enables and disables
 175      * the ability of the process to send broadcast messages. It is supported
 176      * for only datagram sockets and only on networks that support
 177      * the concept of a broadcast message (e.g. Ethernet, token ring, etc.),
 178      * and it is set by default for DatagramSockets.
 179      * @since 1.4
 180      */
 181 
 182     @Native public final static int SO_BROADCAST = 0x0020;
 183 
 184     /** Set which outgoing interface on which to send multicast packets.
 185      * Useful on hosts with multiple network interfaces, where applications
 186      * want to use other than the system default.  Takes/returns an InetAddress.
 187      * <P>
 188      * Valid for Multicast: DatagramSocketImpl
 189      * <P>
 190      * @see MulticastSocket#setInterface(InetAddress)
 191      * @see MulticastSocket#getInterface()
 192      */
 193 
 194     @Native public final static int IP_MULTICAST_IF = 0x10;
 195 
 196     /** Same as above. This option is introduced so that the behaviour
 197      *  with IP_MULTICAST_IF will be kept the same as before, while
 198      *  this new option can support setting outgoing interfaces with either
 199      *  IPv4 and IPv6 addresses.
 200      *
 201      *  NOTE: make sure there is no conflict with this
 202      * @see MulticastSocket#setNetworkInterface(NetworkInterface)
 203      * @see MulticastSocket#getNetworkInterface()
 204      * @since 1.4
 205      */
 206     @Native public final static int IP_MULTICAST_IF2 = 0x1f;
 207 
 208     /**
 209      * This option enables or disables local loopback of multicast datagrams.
 210      * This option is enabled by default for Multicast Sockets.
 211      * @since 1.4
 212      */
 213 
 214     @Native public final static int IP_MULTICAST_LOOP = 0x12;
 215 
 216     /**
 217      * This option sets the type-of-service or traffic class field
 218      * in the IP header for a TCP or UDP socket.
 219      * @since 1.4
 220      */
 221 
 222     @Native public final static int IP_TOS = 0x3;
 223 
 224     /**
 225      * Specify a linger-on-close timeout.  This option disables/enables
 226      * immediate return from a <B>close()</B> of a TCP Socket.  Enabling
 227      * this option with a non-zero Integer <I>timeout</I> means that a
 228      * <B>close()</B> will block pending the transmission and acknowledgement
 229      * of all data written to the peer, at which point the socket is closed
 230      * <I>gracefully</I>.  Upon reaching the linger timeout, the socket is
 231      * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
 232      * timeout of zero does a forceful close immediately. If the specified
 233      * timeout value exceeds 65,535 it will be reduced to 65,535.
 234      * <P>
 235      * Valid only for TCP: SocketImpl
 236      *
 237      * @see Socket#setSoLinger
 238      * @see Socket#getSoLinger
 239      */
 240     @Native public final static int SO_LINGER = 0x0080;
 241 
 242     /** Set a timeout on blocking Socket operations:
 243      * <PRE>
 244      * ServerSocket.accept();
 245      * SocketInputStream.read();
 246      * DatagramSocket.receive();
 247      * </PRE>
 248      *
 249      * <P> The option must be set prior to entering a blocking
 250      * operation to take effect.  If the timeout expires and the
 251      * operation would continue to block,
 252      * <B>java.io.InterruptedIOException</B> is raised.  The Socket is
 253      * not closed in this case.
 254      *
 255      * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
 256      *
 257      * @see Socket#setSoTimeout
 258      * @see ServerSocket#setSoTimeout
 259      * @see DatagramSocket#setSoTimeout
 260      */
 261     @Native public final static int SO_TIMEOUT = 0x1006;
 262 
 263     /**
 264      * Set a hint the size of the underlying buffers used by the
 265      * platform for outgoing network I/O. When used in set, this is a
 266      * suggestion to the kernel from the application about the size of
 267      * buffers to use for the data to be sent over the socket. When
 268      * used in get, this must return the size of the buffer actually
 269      * used by the platform when sending out data on this socket.
 270      *
 271      * Valid for all sockets: SocketImpl, DatagramSocketImpl
 272      *
 273      * @see Socket#setSendBufferSize
 274      * @see Socket#getSendBufferSize
 275      * @see DatagramSocket#setSendBufferSize
 276      * @see DatagramSocket#getSendBufferSize
 277      */
 278     @Native public final static int SO_SNDBUF = 0x1001;
 279 
 280     /**
 281      * Set a hint the size of the underlying buffers used by the
 282      * platform for incoming network I/O. When used in set, this is a
 283      * suggestion to the kernel from the application about the size of
 284      * buffers to use for the data to be received over the
 285      * socket. When used in get, this must return the size of the
 286      * buffer actually used by the platform when receiving in data on
 287      * this socket.
 288      *
 289      * Valid for all sockets: SocketImpl, DatagramSocketImpl
 290      *
 291      * @see Socket#setReceiveBufferSize
 292      * @see Socket#getReceiveBufferSize
 293      * @see DatagramSocket#setReceiveBufferSize
 294      * @see DatagramSocket#getReceiveBufferSize
 295      */
 296     @Native public final static int SO_RCVBUF = 0x1002;
 297 
 298     /**
 299      * When the keepalive option is set for a TCP socket and no data
 300      * has been exchanged across the socket in either direction for
 301      * 2 hours (NOTE: the actual value is implementation dependent),
 302      * TCP automatically sends a keepalive probe to the peer. This probe is a
 303      * TCP segment to which the peer must respond.
 304      * One of three responses is expected:
 305      * 1. The peer responds with the expected ACK. The application is not
 306      *    notified (since everything is OK). TCP will send another probe
 307      *    following another 2 hours of inactivity.
 308      * 2. The peer responds with an RST, which tells the local TCP that
 309      *    the peer host has crashed and rebooted. The socket is closed.
 310      * 3. There is no response from the peer. The socket is closed.
 311      *
 312      * The purpose of this option is to detect if the peer host crashes.
 313      *
 314      * Valid only for TCP socket: SocketImpl
 315      *
 316      * @see Socket#setKeepAlive
 317      * @see Socket#getKeepAlive
 318      */
 319     @Native public final static int SO_KEEPALIVE = 0x0008;
 320 
 321     /**
 322      * When the OOBINLINE option is set, any TCP urgent data received on
 323      * the socket will be received through the socket input stream.
 324      * When the option is disabled (which is the default) urgent data
 325      * is silently discarded.
 326      *
 327      * @see Socket#setOOBInline
 328      * @see Socket#getOOBInline
 329      */
 330     @Native public final static int SO_OOBINLINE = 0x1003;
 331 }