001: /*
002: * @(#)SocketOptions.java 1.32 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.net;
029:
030: /**
031: * Interface of methods to get/set socket options. This interface is
032: * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>.
033: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
034: * J2ME Foundation Profile.
035: * Subclasses of these should override the methods
036: * of this interface in order to support their own options.
037: * <P>
038: * The methods and constants which specify options in this interface are
039: * for implementation only. If you're not subclassing SocketImpl or
040: * DatagramSocketImpl, <B>you won't use these directly.</B> There are
041: * type-safe methods to get/set each of these options in Socket, ServerSocket,
042: * DatagramSocket and MulticastSocket.
043: * NOTE: <B>java.net.SocketImpl, java.net.Socket, java.net.ServerSocket,
044: * java.net.MulticastSocket</B> are found in J2ME CDC profiles such as
045: * J2ME Foundation Profile.
046: * <P>
047: * @version 1.32, 10/10/06
048: * @author David Brown
049: */
050:
051: public interface SocketOptions {
052:
053: /**
054: * Enable/disable the option specified by <I>optID</I>. If the option
055: * is to be enabled, and it takes an option-specific "value", this is
056: * passed in <I>value</I>. The actual type of value is option-specific,
057: * and it is an error to pass something that isn't of the expected type:
058: * <BR><PRE>
059: * SocketImpl s;
060: * ...
061: * s.setOption(SO_LINGER, new Integer(10));
062: * // OK - set SO_LINGER w/ timeout of 10 sec.
063: * s.setOption(SO_LINGER, new Double(10));
064: * // ERROR - expects java.lang.Integer
065: *</PRE>
066: * If the requested option is binary, it can be set using this method by
067: * a java.lang.Boolean:
068: * <BR><PRE>
069: * s.setOption(TCP_NODELAY, new Boolean(true));
070: * // OK - enables TCP_NODELAY, a binary option
071: * </PRE>
072: * <BR>
073: * Any option can be disabled using this method with a Boolean(false):
074: * <BR><PRE>
075: * s.setOption(TCP_NODELAY, new Boolean(false));
076: * // OK - disables TCP_NODELAY
077: * s.setOption(SO_LINGER, new Boolean(false));
078: * // OK - disables SO_LINGER
079: * </PRE>
080: * <BR>
081: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
082: * J2ME Foundation Profile.
083: *
084: * For an option that has a notion of on and off, and requires
085: * a non-boolean parameter, setting its value to anything other than
086: * <I>Boolean(false)</I> implicitly enables it.
087: * <BR>
088: * Throws SocketException if the option is unrecognized,
089: * the socket is closed, or some low-level error occurred
090: * <BR>
091: * @param optID identifies the option
092: * @param value the parameter of the socket option
093: * @throws SocketException if the option is unrecognized,
094: * the socket is closed, or some low-level error occurred
095: * @see #getOption(int)
096: */
097: public void setOption(int optID, Object value)
098: throws SocketException;
099:
100: /**
101: * Fetch the value of an option.
102: * Binary options will return java.lang.Boolean(true)
103: * if enabled, java.lang.Boolean(false) if disabled, e.g.:
104: * <BR><PRE>
105: * SocketImpl s;
106: * ...
107: * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
108: * if (noDelay.booleanValue()) {
109: * // true if TCP_NODELAY is enabled...
110: * ...
111: * }
112: * </PRE>
113: * <P>
114: * For options that take a particular type as a parameter,
115: * getOption(int) will return the paramter's value, else
116: * it will return java.lang.Boolean(false):
117: * <PRE>
118: * Object o = s.getOption(SO_LINGER);
119: * if (o instanceof Integer) {
120: * System.out.print("Linger time is " + ((Integer)o).intValue());
121: * } else {
122: * // the true type of o is java.lang.Boolean(false);
123: * }
124: * </PRE>
125: *
126: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
127: * J2ME Foundation Profile.
128: *
129: * @param optID an <code>int</code> identifying the option to fetch
130: * @return the value of the option
131: * @throws SocketException if the socket is closed
132: * @throws SocketException if <I>optID</I> is unknown along the
133: * protocol stack (including the SocketImpl)
134: * @see #setOption(int, java.lang.Object)
135: */
136: public Object getOption(int optID) throws SocketException;
137:
138: /**
139: * The java-supported BSD-style options.
140: */
141:
142: /**
143: * Disable Nagle's algorithm for this connection. Written data
144: * to the network is not buffered pending acknowledgement of
145: * previously written data.
146: *<P>
147: * Valid for TCP only: SocketImpl.
148: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
149: * J2ME Foundation Profile.
150: * <P>
151: * @see Socket#setTcpNoDelay
152: * @see Socket#getTcpNoDelay
153: */
154:
155: public final static int TCP_NODELAY = 0x0001;
156:
157: /**
158: * Fetch the local address binding of a socket (this option cannot
159: * be "set" only "gotten", since sockets are bound at creation time,
160: * and so the locally bound address cannot be changed). The default local
161: * address of a socket is INADDR_ANY, meaning any local address on a
162: * multi-homed host. A multi-homed host can use this option to accept
163: * connections to only one of its addresses (in the case of a
164: * ServerSocket or DatagramSocket), or to specify its return address
165: * to the peer (for a Socket or DatagramSocket). The parameter of
166: * this option is an InetAddress.
167: * <P>
168: * This option <B>must</B> be specified in the constructor.
169: * <P>
170: * Valid for: SocketImpl, DatagramSocketImpl
171: * <P>
172: * NOTE: <B>java.net.Socket, java.net.ServerSocket, java.net.SocketImpl</B>
173: * are found in J2ME CDC profiles such as J2ME Foundation Profile.
174: * <P>
175: * @see Socket#getLocalAddress
176: * @see DatagramSocket#getLocalAddress
177: */
178:
179: public final static int SO_BINDADDR = 0x000F;
180:
181: /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets
182: * in java, and it is set by default for MulticastSockets.
183: * <P>
184: * Valid for: DatagramSocketImpl
185: */
186:
187: public final static int SO_REUSEADDR = 0x04;
188:
189: /**
190: * Sets SO_BROADCAST for a socket. This option enables and disables
191: * the ability of the process to send broadcast messages. It is supported
192: * for only datagram sockets and only on networks that support
193: * the concept of a broadcast message (e.g. Ethernet, token ring, etc.),
194: * and it is set by default for DatagramSockets.
195: * @since 1.4
196: */
197:
198: public final static int SO_BROADCAST = 0x0020;
199:
200: /** Set which outgoing interface on which to send multicast packets.
201: * Useful on hosts with multiple network interfaces, where applications
202: * want to use other than the system default. Takes/returns an InetAddress.
203: * <P>
204: * Valid for Multicast: DatagramSocketImpl
205: * <P>
206: * @see MulticastSocket#setInterface(InetAddress)
207: * @see MulitcastSocket#getInterface()
208: */
209:
210: public final static int IP_MULTICAST_IF = 0x10;
211:
212: /** Same as above. This option is introduced so that the behaviour
213: * with IP_MULTICAST_IF will be kept the same as before, while
214: * this new option can support setting outgoing interfaces with either
215: * IPv4 and IPv6 addresses.
216: *
217: * NOTE: make sure there is no conflict with this
218: * @see MulticastSocket#setNetworkInterface(NetworkInterface)
219: * @see MulticastSocket#getNetworkInterface()
220: * @since 1.4
221: */
222: public final static int IP_MULTICAST_IF2 = 0x1f;
223:
224: /**
225: * This option enables or disables local loopback of multicast datagrams.
226: * This option is enabled by default for Multicast Sockets.
227: * @since 1.4
228: */
229:
230: public final static int IP_MULTICAST_LOOP = 0x12;
231:
232: /**
233: * This option sets the type-of-service or traffic class field
234: * in the IP header for a TCP or UDP socket.
235: * @since 1.4
236: */
237:
238: public final static int IP_TOS = 0x3;
239:
240: /**
241: * Specify a linger-on-close timeout. This option disables/enables
242: * immediate return from a <B>close()</B> of a TCP Socket. Enabling
243: * this option with a non-zero Integer <I>timeout</I> means that a
244: * <B>close()</B> will block pending the transmission and acknowledgement
245: * of all data written to the peer, at which point the socket is closed
246: * <I>gracefully</I>. Upon reaching the linger timeout, the socket is
247: * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
248: * timeout of zero does a forceful close immediately. If the specified
249: * timeout value exceeds 65,535 it will be reduced to 65,535.
250: * <P>
251: * Valid only for TCP: SocketImpl
252: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
253: * J2ME Foundation Profile.
254: *
255: * @see Socket#setSoLinger
256: * @see Socket#getSoLinger
257: */
258: public final static int SO_LINGER = 0x0080;
259:
260: /** Set a timeout on blocking Socket operations:
261: * <PRE>
262: * ServerSocket.accept();
263: * SocketInputStream.read();
264: * DatagramSocket.receive();
265: * </PRE>
266: * NOTE: <B>java.net.ServerSocket</B> is found in J2ME CDC profiles such as
267: * J2ME Foundation Profile.
268: *
269: * <P> The option must be set prior to entering a blocking
270: * operation to take effect. If the timeout expires and the
271: * operation would continue to block,
272: * <B>java.io.InterruptedIOException</B> is raised. The Socket is
273: * not closed in this case.
274: *
275: * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
276: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
277: * J2ME Foundation Profile.
278: *
279: * @see Socket#setSoTimeout
280: * @see ServerSocket#setSoTimeout
281: * @see DatagramSocket#setSoTimeout
282: */
283: public final static int SO_TIMEOUT = 0x1006;
284:
285: /**
286: * Set a hint the size of the underlying buffers used by the
287: * platform for outgoing network I/O. When used in set, this is a
288: * suggestion to the kernel from the application about the size of
289: * buffers to use for the data to be sent over the socket. When
290: * used in get, this must return the size of the buffer actually
291: * used by the platform when sending out data on this socket.
292: *
293: * Valid for all sockets: SocketImpl, DatagramSocketImpl
294: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
295: * J2ME Foundation Profile.
296: *
297: * @see Socket#setSendBufferSize
298: * @see Socket#getSendBufferSize
299: * @see DatagramSocket#setSendBufferSize
300: * @see DatagramSocket#getSendBufferSize
301: */
302: public final static int SO_SNDBUF = 0x1001;
303:
304: /**
305: * Set a hint the size of the underlying buffers used by the
306: * platform for incoming network I/O. When used in set, this is a
307: * suggestion to the kernel from the application about the size of
308: * buffers to use for the data to be received over the
309: * socket. When used in get, this must return the size of the
310: * buffer actually used by the platform when receiving in data on
311: * this socket.
312: *
313: * Valid for all sockets: SocketImpl, DatagramSocketImpl
314: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
315: * J2ME Foundation Profile.
316: *
317: * @see Socket#setReceiveBufferSize
318: * @see Socket#getReceiveBufferSize
319: * @see DatagramSocket#setReceiveBufferSize
320: * @see DatagramSocket#getReceiveBufferSize
321: */
322: public final static int SO_RCVBUF = 0x1002;
323:
324: /**
325: * When the keepalive option is set for a TCP socket and no data
326: * has been exchanged across the socket in either direction for
327: * 2 hours (NOTE: the actual value is implementation dependent),
328: * TCP automatically sends a keepalive probe to the peer. This probe is a
329: * TCP segment to which the peer must respond.
330: * One of three responses is expected:
331: * 1. The peer responds with the expected ACK. The application is not
332: * notified (since everything is OK). TCP will send another probe
333: * following another 2 hours of inactivity.
334: * 2. The peer responds with an RST, which tells the local TCP that
335: * the peer host has crashed and rebooted. The socket is closed.
336: * 3. There is no response from the peer. The socket is closed.
337: *
338: * The purpose of this option is to detect if the peer host crashes.
339: *
340: * Valid only for TCP socket: SocketImpl
341: * NOTE: <B>java.net.SocketImpl</B> is found in J2ME CDC profiles such as
342: * J2ME Foundation Profile.
343: *
344: * @see Socket#setKeepAlive
345: * @see Socket#getKeepAlive
346: */
347: public final static int SO_KEEPALIVE = 0x0008;
348:
349: /**
350: * When the OOBINLINE option is set, any TCP urgent data received on
351: * the socket will be received through the socket input stream.
352: * When the option is disabled (which is the default) urgent data
353: * is silently discarded.
354: *
355: * @see Socket#setOOBInline
356: * @see Socket#getOOBInline
357: */
358: public final static int SO_OOBINLINE = 0x1003;
359: }
|