1 /*

     2  * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     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  *

    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

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

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

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

    53      * <BR><PRE>

    54      * SocketImpl s;

    55      * ...

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

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

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

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

    60      *</PRE>

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

    62      * a java.lang.Boolean:

    63      * <BR><PRE>

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

    65      *    // OK - enables TCP_NODELAY, a binary option

    66      * </PRE>

    67      * <BR>

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

    69      * <BR><PRE>

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

    71      *    // OK - disables TCP_NODELAY

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

    73      *    // OK - disables SO_LINGER

    74      * </PRE>

    75      * <BR>

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

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

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

    79      * <BR>

    80      * Throws SocketException if the option is unrecognized,

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

    82      * <BR>

    83      * @param optID identifies the option

    84      * @param value the parameter of the socket option

    85      * @throws SocketException if the option is unrecognized,

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

    87      * @see #getOption(int)

    88      */

    89     public void

    90         setOption(int optID, Object value) throws SocketException;

    91 

    92     /**

    93      * Fetch the value of an option.

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

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

    96      * <BR><PRE>

    97      * SocketImpl s;

    98      * ...

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

   100      * if (noDelay.booleanValue()) {

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

   102      * ...

   103      * }

   104      * </PRE>

   105      * <P>

   106      * For options that take a particular type as a parameter,

   107      * getOption(int) will return the parameter's value, else

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

   109      * <PRE>

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

   111      * if (o instanceof Integer) {

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

   113      * } else {

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

   115      * }

   116      * </PRE>

   117      *

   118      * @param optID an {@code int} identifying the option to fetch

   119      * @return the value of the option

   120      * @throws SocketException if the socket is closed

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

   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      *

   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      *

   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      *

   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 }