SocketOptions.java revision 12745:f068a4ffddd2 
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
26package java.net;
27
28import 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
46public 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final 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 static final int SO_OOBINLINE = 0x1003;
331}
332