SocketOptions


1   /*
2    * @(#)SocketOptions.java   1.32 04/01/28
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.net;
9   
10  /**
11   * Interface of methods to get/set socket options.  This interface is
12   * implemented by: <B>SocketImpl</B> and  <B>DatagramSocketImpl</B>.
13   * Subclasses of these should override the methods
14   * of this interface in order to support their own options.
15   * <P>
16   * The methods and constants which specify options in this interface are
17   * for implementation only.  If you're not subclassing SocketImpl or
18   * DatagramSocketImpl, <B>you won't use these directly.</B> There are
19   * type-safe methods to get/set each of these options in Socket, ServerSocket,
20   * DatagramSocket and MulticastSocket.
21   * <P>
22   * @version 1.32, 01/28/04
23   * @author David Brown
24   */
25  
26  
27  public interface SocketOptions {
28  
29      /**
30       * Enable/disable the option specified by <I>optID</I>.  If the option
31       * is to be enabled, and it takes an option-specific "value",  this is
32       * passed in <I>value</I>.  The actual type of value is option-specific,
33       * and it is an error to pass something that isn't of the expected type:
34       * <BR><PRE>
35       * SocketImpl s;
36       * ...
37       * s.setOption(SO_LINGER, new Integer(10));
38       *    // OK - set SO_LINGER w/ timeout of 10 sec.
39       * s.setOption(SO_LINGER, new Double(10));
40       *    // ERROR - expects java.lang.Integer
41       *</PRE>
42       * If the requested option is binary, it can be set using this method by
43       * a java.lang.Boolean:
44       * <BR><PRE>
45       * s.setOption(TCP_NODELAY, new Boolean(true));
46       *    // OK - enables TCP_NODELAY, a binary option
47       * </PRE>
48       * <BR>
49       * Any option can be disabled using this method with a Boolean(false):
50       * <BR><PRE>
51       * s.setOption(TCP_NODELAY, new Boolean(false));
52       *    // OK - disables TCP_NODELAY
53       * s.setOption(SO_LINGER, new Boolean(false));
54       *    // OK - disables SO_LINGER
55       * </PRE>
56       * <BR>
57       * For an option that has a notion of on and off, and requires 
58       * a non-boolean parameter, setting its value to anything other than
59       * <I>Boolean(false)</I> implicitly enables it.
60       * <BR>
61       * Throws SocketException if the option is unrecognized,
62       * the socket is closed, or some low-level error occurred
63       * <BR>
64       * @param optID identifies the option
65       * @param value the parameter of the socket option
66       * @throws SocketException if the option is unrecognized,
67       * the socket is closed, or some low-level error occurred
68       * @see #getOption(int)
69       */
70      public void
71      setOption(int optID, Object   value) throws SocketException  ;
72  
73      /**
74       * Fetch the value of an option.
75       * Binary options will return java.lang.Boolean(true)
76       * if enabled, java.lang.Boolean(false) if disabled, e.g.:
77       * <BR><PRE>
78       * SocketImpl s;
79       * ...
80       * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
81       * if (noDelay.booleanValue()) {
82       *     // true if TCP_NODELAY is enabled...
83       * ...
84       * }
85       * </PRE>
86       * <P>
87       * For options that take a particular type as a parameter,
88       * getOption(int) will return the paramter's value, else
89       * it will return java.lang.Boolean(false):
90       * <PRE>
91       * Object o = s.getOption(SO_LINGER);
92       * if (o instanceof Integer) {
93       *     System.out.print("Linger time is " + ((Integer)o).intValue());
94       * } else {
95       *   // the true type of o is java.lang.Boolean(false);
96       * }
97       * </PRE>
98       *
99       * @param optID an <code>int</code> identifying the option to fetch
100      * @return the value of the option
101      * @throws SocketException if the socket is closed
102      * @throws SocketException if <I>optID</I> is unknown along the
103      *         protocol stack (including the SocketImpl)
104      * @see #setOption(int, java.lang.Object)
105      */
106     public Object   getOption(int optID) throws SocketException  ;
107 
108     /**
109      * The java-supported BSD-style options.
110      */
111 
112     /**
113      * Disable Nagle's algorithm for this connection.  Written data
114      * to the network is not buffered pending acknowledgement of
115      * previously written data.
116      *<P>
117      * Valid for TCP only: SocketImpl.
118      * <P>
119      * @see Socket#setTcpNoDelay
120      * @see Socket#getTcpNoDelay
121      */
122 
123     public final static int TCP_NODELAY = 0x0001;
124 
125     /**
126      * Fetch the local address binding of a socket (this option cannot
127      * be "set" only "gotten", since sockets are bound at creation time,
128      * and so the locally bound address cannot be changed).  The default local
129      * address of a socket is INADDR_ANY, meaning any local address on a
130      * multi-homed host.  A multi-homed host can use this option to accept
131      * connections to only one of its addresses (in the case of a
132      * ServerSocket or DatagramSocket), or to specify its return address
133      * to the peer (for a Socket or DatagramSocket).  The parameter of
134      * this option is an InetAddress.
135      * <P>
136      * This option <B>must</B> be specified in the constructor.
137      * <P>
138      * Valid for: SocketImpl, DatagramSocketImpl
139      * <P>
140      * @see Socket#getLocalAddress
141      * @see DatagramSocket#getLocalAddress
142      */
143 
144     public final static int SO_BINDADDR = 0x000F;
145 
146     /** Sets SO_REUSEADDR for a socket.  This is used only for MulticastSockets
147      * in java, and it is set by default for MulticastSockets.
148      * <P>
149      * Valid for: DatagramSocketImpl
150      */
151 
152     public final static int SO_REUSEADDR = 0x04;
153 
154     /**
155      * Sets SO_BROADCAST for a socket. This option enables and disables 
156      * the ability of the process to send broadcast messages. It is supported
157      * for only datagram sockets and only on networks that support
158      * the concept of a broadcast message (e.g. Ethernet, token ring, etc.),
159      * and it is set by default for DatagramSockets.
160      * @since 1.4
161      */
162 
163     public final static int SO_BROADCAST = 0x0020;
164 
165     /** Set which outgoing interface on which to send multicast packets.
166      * Useful on hosts with multiple network interfaces, where applications
167      * want to use other than the system default.  Takes/returns an InetAddress.
168      * <P>
169      * Valid for Multicast: DatagramSocketImpl
170      * <P>
171      * @see MulticastSocket#setInterface(InetAddress)
172      * @see MulticastSocket#getInterface()
173      */
174 
175     public final static int IP_MULTICAST_IF = 0x10;
176 
177     /** Same as above. This option is introduced so that the behaviour 
178      *  with IP_MULTICAST_IF will be kept the same as before, while
179      *  this new option can support setting outgoing interfaces with either 
180      *  IPv4 and IPv6 addresses.
181      *
182      *  NOTE: make sure there is no conflict with this
183      * @see MulticastSocket#setNetworkInterface(NetworkInterface)
184      * @see MulticastSocket#getNetworkInterface()
185      * @since 1.4
186      */
187     public final static int IP_MULTICAST_IF2 = 0x1f;
188 
189     /** 
190      * This option enables or disables local loopback of multicast datagrams.
191      * This option is enabled by default for Multicast Sockets.
192      * @since 1.4
193      */
194 
195     public final static int IP_MULTICAST_LOOP = 0x12;
196 
197     /** 
198      * This option sets the type-of-service or traffic class field 
199      * in the IP header for a TCP or UDP socket.
200      * @since 1.4
201      */
202 
203     public final static int IP_TOS = 0x3;
204 
205     /**
206      * Specify a linger-on-close timeout.  This option disables/enables
207      * immediate return from a <B>close()</B> of a TCP Socket.  Enabling
208      * this option with a non-zero Integer <I>timeout</I> means that a
209      * <B>close()</B> will block pending the transmission and acknowledgement
210      * of all data written to the peer, at which point the socket is closed
211      * <I>gracefully</I>.  Upon reaching the linger timeout, the socket is
212      * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
213      * timeout of zero does a forceful close immediately. If the specified
214      * timeout value exceeds 65,535 it will be reduced to 65,535.
215      * <P>
216      * Valid only for TCP: SocketImpl
217      * 
218      * @see Socket#setSoLinger
219      * @see Socket#getSoLinger
220      */
221     public final static int SO_LINGER = 0x0080;
222 
223     /** Set a timeout on blocking Socket operations:
224      * <PRE>
225      * ServerSocket.accept();
226      * SocketInputStream.read();
227      * DatagramSocket.receive();
228      * </PRE>
229      *
230      * <P> The option must be set prior to entering a blocking
231      * operation to take effect.  If the timeout expires and the
232      * operation would continue to block,
233      * <B>java.io.InterruptedIOException</B> is raised.  The Socket is
234      * not closed in this case.
235      *
236      * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
237      *
238      * @see Socket#setSoTimeout
239      * @see ServerSocket#setSoTimeout
240      * @see DatagramSocket#setSoTimeout
241      */
242     public final static int SO_TIMEOUT = 0x1006;
243 
244     /**
245      * Set a hint the size of the underlying buffers used by the
246      * platform for outgoing network I/O. When used in set, this is a
247      * suggestion to the kernel from the application about the size of
248      * buffers to use for the data to be sent over the socket. When
249      * used in get, this must return the size of the buffer actually
250      * used by the platform when sending out data on this socket.
251      *
252      * Valid for all sockets: SocketImpl, DatagramSocketImpl
253      *
254      * @see Socket#setSendBufferSize
255      * @see Socket#getSendBufferSize
256      * @see DatagramSocket#setSendBufferSize
257      * @see DatagramSocket#getSendBufferSize
258      */
259     public final static int SO_SNDBUF = 0x1001;
260 
261     /**
262      * Set a hint the size of the underlying buffers used by the
263      * platform for incoming 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 received over the
266      * socket. When used in get, this must return the size of the
267      * buffer actually used by the platform when receiving in data on
268      * this socket.
269      *
270      * Valid for all sockets: SocketImpl, DatagramSocketImpl
271      *
272      * @see Socket#setReceiveBufferSize
273      * @see Socket#getReceiveBufferSize
274      * @see DatagramSocket#setReceiveBufferSize
275      * @see DatagramSocket#getReceiveBufferSize
276      */
277     public final static int SO_RCVBUF = 0x1002;
278 
279     /**
280      * When the keepalive option is set for a TCP socket and no data
281      * has been exchanged across the socket in either direction for 
282      * 2 hours (NOTE: the actual value is implementation dependent),
283      * TCP automatically sends a keepalive probe to the peer. This probe is a 
284      * TCP segment to which the peer must respond. 
285      * One of three responses is expected:
286      * 1. The peer responds with the expected ACK. The application is not 
287      *    notified (since everything is OK). TCP will send another probe 
288      *    following another 2 hours of inactivity.
289      * 2. The peer responds with an RST, which tells the local TCP that
290      *    the peer host has crashed and rebooted. The socket is closed.
291      * 3. There is no response from the peer. The socket is closed. 
292      *
293      * The purpose of this option is to detect if the peer host crashes. 
294      *
295      * Valid only for TCP socket: SocketImpl
296      *
297      * @see Socket#setKeepAlive
298      * @see Socket#getKeepAlive
299      */
300     public final static int SO_KEEPALIVE = 0x0008;
301 
302     /**
303      * When the OOBINLINE option is set, any TCP urgent data received on
304      * the socket will be received through the socket input stream.
305      * When the option is disabled (which is the default) urgent data
306      * is silently discarded.
307      *
308      * @see Socket#setOOBInline
309      * @see Socket#getOOBInline
310      */
311     public final static int SO_OOBINLINE = 0x1003;
312 }
313 
314 
315 
316 
317 
318 
319
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags