PageRenderTime 24ms CodeModel.GetById 2ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/overlays/nio2/openjdk/jdk/src/share/classes/org/classpath/icedtea/java/net/StandardSocketOption.java

https://bitbucket.org/xiaoqiangnk/icedtea6
Java | 370 lines | 38 code | 23 blank | 309 comment | 0 complexity | a8d485768042856596a00ec7799d7184 MD5 | raw file
  1/*
  2 * Copyright 2007-2008 Sun Microsystems, Inc.  All Rights Reserved.
  3 * Copyright 2009 Red Hat, Inc.
  4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  5 *
  6 * This code is free software; you can redistribute it and/or modify it
  7 * under the terms of the GNU General Public License version 2 only, as
  8 * published by the Free Software Foundation.  Sun designates this
  9 * particular file as subject to the "Classpath" exception as provided
 10 * by Sun in the LICENSE file that accompanied this code.
 11 *
 12 * This code is distributed in the hope that it will be useful, but WITHOUT
 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 14 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 15 * version 2 for more details (a copy is included in the LICENSE file that
 16 * accompanied this code).
 17 *
 18 * You should have received a copy of the GNU General Public License version
 19 * 2 along with this work; if not, write to the Free Software Foundation,
 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 21 *
 22 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 23 * CA 95054 USA or visit www.sun.com if you need additional information or
 24 * have any questions.
 25 */
 26
 27package org.classpath.icedtea.java.net;
 28
 29import java.net.NetworkInterface;
 30
 31/**
 32 * Defines the <em>standard</em> socket options.
 33 *
 34 * <p> The {@link SocketOption#name name} of each socket option defined by this
 35 * class is its field name.
 36 *
 37 * <p> In this release, the socket options defined here are used by {@link
 38 * java.nio.channels.NetworkChannel network} channels in the {@link
 39 * java.nio.channels channels} package.
 40 *
 41 * @since 1.7
 42 */
 43
 44public final class StandardSocketOption {
 45    private StandardSocketOption() { }
 46
 47    // -- SOL_SOCKET --
 48
 49    /**
 50     * Allow transmission of broadcast datagrams.
 51     *
 52     * <p> The value of this socket option is a {@code Boolean} that represents
 53     * whether the option is enabled or disabled. The option is specific to
 54     * datagram-oriented sockets sending to {@link java.net.Inet4Address IPv4}
 55     * broadcast addresses. When the socket option is enabled then the socket
 56     * can be used to send <em>broadcast datagrams</em>.
 57     *
 58     * <p> The initial value of this socket option is {@code FALSE}. The socket
 59     * option may be enabled or disabled at any time. Some operating systems may
 60     * require that the Java virtual machine be started with implementation
 61     * specific privileges to enable this option or send broadcast datagrams.
 62     *
 63     * @see <a href="http://www.ietf.org/rfc/rfc919.txt">RFC&nbsp;929:
 64     * Broadcasting Internet Datagrams</a>
 65     * @see DatagramSocket#setBroadcast
 66     */
 67    public static final SocketOption<Boolean> SO_BROADCAST =
 68        new StdSocketOption<Boolean>("SO_BROADCAST", Boolean.class);
 69
 70    /**
 71     * Keep connection alive.
 72     *
 73     * <p> The value of this socket option is a {@code Boolean} that represents
 74     * whether the option is enabled or disabled. When the {@code SO_KEEPALIVE}
 75     * option is enabled the operating system may use a <em>keep-alive</em>
 76     * mechanism to periodically probe the other end of a connection when the
 77     * connection is otherwise idle. The exact semantics of the keep alive
 78     * mechanism is system dependent and therefore unspecified.
 79     *
 80     * <p> The initial value of this socket option is {@code FALSE}. The socket
 81     * option may be enabled or disabled at any time.
 82     *
 83     * @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122
 84     * Requirements for Internet Hosts -- Communication Layers</a>
 85     * @see Socket#setKeepAlive
 86     */
 87    public static final SocketOption<Boolean> SO_KEEPALIVE =
 88        new StdSocketOption<Boolean>("SO_KEEPALIVE", Boolean.class);
 89
 90    /**
 91     * The size of the socket send buffer.
 92     *
 93     * <p> The value of this socket option is an {@code Integer} that is the
 94     * size of the socket send buffer in bytes. The socket send buffer is an
 95     * output buffer used by the networking implementation. It may need to be
 96     * increased for high-volume connections. The value of the socket option is
 97     * a <em>hint</em> to the implementation to size the buffer and the actual
 98     * size may differ. The socket option can be queried to retrieve the actual
 99     * size.
100     *
101     * <p> For datagram-oriented sockets, the size of the send buffer may limit
102     * the size of the datagrams that may be sent by the socket. Whether
103     * datagrams larger than the buffer size are sent or discarded is system
104     * dependent.
105     *
106     * <p> The initial/default size of the socket send buffer and the range of
107     * allowable values is system dependent although a negative size is not
108     * allowed. An attempt to set the socket send buffer to larger than its
109     * maximum size causes it to be set to its maximum size.
110     *
111     * <p> An implementation allows this socket option to be set before the
112     * socket is bound or connected. Whether an implementation allows the
113     * socket send buffer to be changed after the socket is bound is system
114     * dependent.
115     *
116     * @see Socket#setSendBufferSize
117     */
118    public static final SocketOption<Integer> SO_SNDBUF =
119        new StdSocketOption<Integer>("SO_SNDBUF", Integer.class);
120
121
122    /**
123     * The size of the socket receive buffer.
124     *
125     * <p> The value of this socket option is an {@code Integer} that is the
126     * size of the socket receive buffer in bytes. The socket receive buffer is
127     * an input buffer used by the networking implementation. It may need to be
128     * increased for high-volume connections or decreased to limit the possible
129     * backlog of incoming data. The value of the socket option is a
130     * <em>hint</em> to the implementation to size the buffer and the actual
131     * size may differ.
132     *
133     * <p> For datagram-oriented sockets, the size of the receive buffer may
134     * limit the size of the datagrams that can be received. Whether datagrams
135     * larger than the buffer size can be received is system dependent.
136     * Increasing the socket receive buffer may be important for cases where
137     * datagrams arrive in bursts faster than they can be processed.
138     *
139     * <p> In the case of stream-oriented sockets and the TCP/IP protocol, the
140     * size of the socket receive buffer may be used when advertising the size
141     * of the TCP receive window to the remote peer.
142     *
143     * <p> The initial/default size of the socket receive buffer and the range
144     * of allowable values is system dependent although a negative size is not
145     * allowed. An attempt to set the socket receive buffer to larger than its
146     * maximum size causes it to be set to its maximum size.
147     *
148     * <p> An implementation allows this socket option to be set before the
149     * socket is bound or connected. Whether an implementation allows the
150     * socket receive buffer to be changed after the socket is bound is system
151     * dependent.
152     *
153     * @see <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC&nbsp;1323: TCP
154     * Extensions for High Performance</a>
155     * @see Socket#setReceiveBufferSize
156     * @see ServerSocket#setReceiveBufferSize
157     */
158    public static final SocketOption<Integer> SO_RCVBUF =
159        new StdSocketOption<Integer>("SO_RCVBUF", Integer.class);
160
161    /**
162     * Re-use address.
163     *
164     * <p> The value of this socket option is a {@code Boolean} that represents
165     * whether the option is enabled or disabled. The exact semantics of this
166     * socket option are socket type and system dependent.
167     *
168     * <p> In the case of stream-oriented sockets, this socket option will
169     * usually determine whether the socket can be bound to a socket address
170     * when a previous connection involving that socket address is in the
171     * <em>TIME_WAIT</em> state. On implementations where the semantics differ,
172     * and the socket option is not required to be enabled in order to bind the
173     * socket when a previous connection is in this state, then the
174     * implementation may choose to ignore this option.
175     *
176     * <p> For datagram-oriented sockets the socket option is used to allow
177     * multiple programs bind to the same address. This option should be enabled
178     * when the socket is to be used for Internet Protocol (IP) multicasting.
179     *
180     * <p> An implementation allows this socket option to be set before the
181     * socket is bound or connected. Changing the value of this socket option
182     * after the socket is bound has no effect. The default value of this
183     * socket option is system dependent.
184     *
185     * @see <a href="http://www.ietf.org/rfc/rfc793.txt">RFC&nbsp;793: Transmission
186     * Control Protocol</a>
187     * @see ServerSocket#setReuseAddress
188     */
189    public static final SocketOption<Boolean> SO_REUSEADDR =
190        new StdSocketOption<Boolean>("SO_REUSEADDR", Boolean.class);
191
192    /**
193     * Linger on close if data is present.
194     *
195     * <p> The value of this socket option is an {@code Integer} that controls
196     * the action taken when unsent data is queued on the socket and a method
197     * to close the socket is invoked. If the value of the socket option is zero
198     * or greater, then it represents a timeout value, in seconds, known as the
199     * <em>linger interval</em>. The linger interval is the timeout for the
200     * {@code close} method to block while the operating system attempts to
201     * transmit the unsent data or it decides that it is unable to transmit the
202     * data. If the value of the socket option is less than zero then the option
203     * is disabled. In that case the {@code close} method does not wait until
204     * unsent data is transmitted; if possible the operating system will transmit
205     * any unsent data before the connection is closed.
206     *
207     * <p> This socket option is intended for use with sockets that are configured
208     * in {@link java.nio.channels.SelectableChannel#isBlocking() blocking} mode
209     * only. The behavior of the {@code close} method when this option is
210     * enabled on a non-blocking socket is not defined.
211     *
212     * <p> The initial value of this socket option is a negative value, meaning
213     * that the option is disabled. The option may be enabled, or the linger
214     * interval changed, at any time. The maximum value of the linger interval
215     * is system dependent. Setting the linger interval to a value that is
216     * greater than its maximum value causes the linger interval to be set to
217     * its maximum value.
218     *
219     * @see Socket#setSoLinger
220     */
221    public static final SocketOption<Integer> SO_LINGER =
222        new StdSocketOption<Integer>("SO_LINGER", Integer.class);
223
224
225    // -- IPPROTO_IP --
226
227    /**
228     * The Type of Service (ToS) octet in the Internet Protocol (IP) header.
229     *
230     * <p> The value of this socket option is an {@code Integer} representing
231     * the value of the ToS octet in IP packets sent by sockets to an {@link
232     * StandardProtocolFamily#INET IPv4} socket. The interpretation of the ToS
233     * octet is network specific and is not defined by this class. Further
234     * information on the ToS octet can be found in <a
235     * href="http://www.ietf.org/rfc/rfc1349.txt">RFC&nbsp;1349</a> and <a
236     * href="http://www.ietf.org/rfc/rfc2474.txt">RFC&nbsp;2474</a>. The value
237     * of the socket option is a <em>hint</em>. An implementation may ignore the
238     * value, or ignore specific values.
239     *
240     * <p> The initial/default value of the TOS field in the ToS octet is
241     * implementation specific but will typically be {@code 0}. For
242     * datagram-oriented sockets the option may be configured at any time after
243     * the socket has been bound. The new value of the octet is used when sending
244     * subsequent datagrams. It is system dependent whether this option can be
245     * queried or changed prior to binding the socket.
246     *
247     * <p> The behavior of this socket option on a stream-oriented socket, or an
248     * {@link StandardProtocolFamily#INET6 IPv6} socket, is not defined in this
249     * release.
250     *
251     * @see DatagramSocket#setTrafficClass
252     */
253    public static final SocketOption<Integer> IP_TOS =
254        new StdSocketOption<Integer>("IP_TOS", Integer.class);
255
256    /**
257     * The network interface for Internet Protocol (IP) multicast datagrams.
258     *
259     * <p> The value of this socket option is a {@link NetworkInterface} that
260     * represents the outgoing interface for multicast datagrams sent by the
261     * datagram-oriented socket. For {@link StandardProtocolFamily#INET6 IPv6}
262     * sockets then it is system dependent whether setting this option also
263     * sets the outgoing interface for multlicast datagrams sent to IPv4
264     * addresses.
265     *
266     * <p> The initial/default value of this socket option may be {@code null}
267     * to indicate that outgoing interface will be selected by the operating
268     * system, typically based on the network routing tables. An implementation
269     * allows this socket option to be set after the socket is bound. Whether
270     * the socket option can be queried or changed prior to binding the socket
271     * is system dependent.
272     *
273     * @see java.nio.channels.MulticastChannel
274     * @see MulticastSocket#setInterface
275     */
276    public static final SocketOption<NetworkInterface> IP_MULTICAST_IF =
277        new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class);
278
279    /**
280     * The <em>time-to-live</em> for Internet Protocol (IP) multicast datagrams.
281     *
282     * <p> The value of this socket option is an {@code Integer} in the range
283     * <tt>0&nbsp;<=&nbsp;value&nbsp;<=&nbsp;255</tt>. It is used to control
284     * the scope of multicast datagrams sent by the datagram-oriented socket.
285     * In the case of an {@link StandardProtocolFamily#INET IPv4} socket
286     * the option is the time-to-live (TTL) on multicast datagrams sent by the
287     * socket. Datagrams with a TTL of zero are not transmitted on the network
288     * but may be delivered locally. In the case of an {@link
289     * StandardProtocolFamily#INET6 IPv6} socket the option is the
290     * <em>hop limit</em> which is number of <em>hops</em> that the datagram can
291     * pass through before expiring on the network. For IPv6 sockets it is
292     * system dependent whether the option also sets the <em>time-to-live</em>
293     * on multicast datagrams sent to IPv4 addresses.
294     *
295     * <p> The initial/default value of the time-to-live setting is typically
296     * {@code 1}. An implementation allows this socket option to be set after
297     * the socket is bound. Whether the socket option can be queried or changed
298     * prior to binding the socket is system dependent.
299     *
300     * @see java.nio.channels.MulticastChannel
301     * @see MulticastSocket#setTimeToLive
302     */
303    public static final SocketOption<Integer> IP_MULTICAST_TTL =
304        new StdSocketOption<Integer>("IP_MULTICAST_TTL", Integer.class);
305
306    /**
307     * Loopback for Internet Protocol (IP) multicast datagrams.
308     *
309     * <p> The value of this socket option is a {@code Boolean} that controls
310     * the <em>loopback</em> of multicast datagrams. The value of the socket
311     * option represents if the option is enabled or disabled.
312     *
313     * <p> The exact semantics of this socket options are system dependent.
314     * In particular, it is system dependent whether the loopback applies to
315     * multicast datagrams sent from the socket or received by the socket.
316     * For {@link StandardProtocolFamily#INET6 IPv6} sockets then it is
317     * system dependent whether the option also applies to multicast datagrams
318     * sent to IPv4 addresses.
319     *
320     * <p> The initial/default value of this socket option is {@code TRUE}. An
321     * implementation allows this socket option to be set after the socket is
322     * bound. Whether the socket option can be queried or changed prior to
323     * binding the socket is system dependent.
324     *
325     * @see java.nio.channels.MulticastChannel
326     *  @see MulticastSocket#setLoopbackMode
327     */
328    public static final SocketOption<Boolean> IP_MULTICAST_LOOP =
329        new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class);
330
331
332    // -- IPPROTO_TCP --
333
334    /**
335     * Disable the Nagle algorithm.
336     *
337     * <p> The value of this socket option is a {@code Boolean} that represents
338     * whether the option is enabled or disabled. The socket option is specific to
339     * stream-oriented sockets using the TCP/IP protocol. TCP/IP uses an algorithm
340     * known as <em>The Nagle Algorithm</em> to coalesce short segments and
341     * improve network efficiency.
342     *
343     * <p> The default value of this socket option is {@code FALSE}. The
344     * socket option should only be enabled in cases where it is known that the
345     * coalescing impacts performance. The socket option may be enabled at any
346     * time. In other words, the Nagle Algorithm can be disabled. Once the option
347     * is enabled, it is system dependent whether it can be subsequently
348     * disabled. If it cannot, then invoking the {@code setOption} method to
349     * disable the option has no effect.
350     *
351     * @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122:
352     * Requirements for Internet Hosts -- Communication Layers</a>
353     * @see Socket#setTcpNoDelay
354     */
355    public static final SocketOption<Boolean> TCP_NODELAY =
356        new StdSocketOption<Boolean>("TCP_NODELAY", Boolean.class);
357
358
359    private static class StdSocketOption<T> implements SocketOption<T> {
360        private final String name;
361        private final Class<T> type;
362        StdSocketOption(String name, Class<T> type) {
363            this.name = name;
364            this.type = type;
365        }
366 public String name() { return name; }
367 public Class<T> type() { return type; }
368 public String toString() { return name; }
369    }
370}