View Javadoc
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   * <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
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 }