ServerSocket.java revision 0
0N/A * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * This class implements server sockets. A server socket waits for 0N/A * requests to come in over the network. It performs some operation 0N/A * based on that request, and then possibly returns a result to the requester. 0N/A * The actual work of the server socket is performed by an instance 0N/A * of the <code>SocketImpl</code> class. An application can 0N/A * change the socket factory that creates the socket 0N/A * implementation to configure itself to create sockets 0N/A * appropriate to the local firewall. 0N/A * @author unascribed 0N/A * @see java.net.SocketImpl 0N/A * @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) 0N/A * @see java.nio.channels.ServerSocketChannel 0N/A * Various states of this socket. 0N/A * The implementation of this Socket. 0N/A * Are we using an older SocketImpl? 0N/A * Creates an unbound server socket. 0N/A * @exception IOException IO error when opening the socket. 0N/A * Creates a server socket, bound to the specified port. A port number 0N/A * of <code>0</code> means that the port number is automatically 0N/A * allocated, typically from an ephemeral port range. This port 0N/A * number can then be retrieved by calling {@link #getLocalPort getLocalPort}. 0N/A * The maximum queue length for incoming connection indications (a 0N/A * request to connect) is set to <code>50</code>. If a connection 0N/A * indication arrives when the queue is full, the connection is refused. 0N/A * If the application has specified a server socket factory, that 0N/A * factory's <code>createSocketImpl</code> method is called to create 0N/A * the actual socket implementation. Otherwise a "plain" socket is created. 0N/A * If there is a security manager, 0N/A * its <code>checkListen</code> method is called 0N/A * with the <code>port</code> argument 0N/A * as its argument to ensure the operation is allowed. 0N/A * This could result in a SecurityException. 0N/A * @param port the port number, or <code>0</code> to use a port 0N/A * number that is automatically allocated. 0N/A * @exception IOException if an I/O error occurs when opening the socket. 0N/A * @exception SecurityException 0N/A * if a security manager exists and its <code>checkListen</code> 0N/A * method doesn't allow the operation. 0N/A * @exception IllegalArgumentException if the port parameter is outside 0N/A * the specified range of valid port values, which is between 0N/A * 0 and 65535, inclusive. 0N/A * @see java.net.SocketImpl 0N/A * @see java.net.SocketImplFactory#createSocketImpl() 0N/A * @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) 0N/A * @see SecurityManager#checkListen 0N/A * Creates a server socket and binds it to the specified local port 0N/A * number, with the specified backlog. 0N/A * A port number of <code>0</code> means that the port number is 0N/A * automatically allocated, typically from an ephemeral port range. 0N/A * This port number can then be retrieved by calling 0N/A * {@link #getLocalPort getLocalPort}. 0N/A * The maximum queue length for incoming connection indications (a 0N/A * request to connect) is set to the <code>backlog</code> parameter. If 0N/A * a connection indication arrives when the queue is full, the 0N/A * connection is refused. 0N/A * If the application has specified a server socket factory, that 0N/A * factory's <code>createSocketImpl</code> method is called to create 0N/A * the actual socket implementation. Otherwise a "plain" socket is created. 0N/A * If there is a security manager, 0N/A * its <code>checkListen</code> method is called 0N/A * with the <code>port</code> argument 0N/A * as its argument to ensure the operation is allowed. 0N/A * This could result in a SecurityException. 0N/A * <P>The <code>backlog</code> argument must be a positive 0N/A * value greater than 0. If the value passed is equal or less 0N/A * than 0, then the default value will be assumed. 0N/A * @param port the port number, or <code>0</code> to use a port 0N/A * number that is automatically allocated. 0N/A * @param backlog the maximum length of the queue. 0N/A * @exception IOException if an I/O error occurs when opening the socket. 0N/A * @exception SecurityException 0N/A * if a security manager exists and its <code>checkListen</code> 0N/A * method doesn't allow the operation. 0N/A * @exception IllegalArgumentException if the port parameter is outside 0N/A * the specified range of valid port values, which is between 0N/A * 0 and 65535, inclusive. 0N/A * @see java.net.SocketImpl 0N/A * @see java.net.SocketImplFactory#createSocketImpl() 0N/A * @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) 0N/A * @see SecurityManager#checkListen 0N/A * Create a server with the specified port, listen backlog, and 0N/A * local IP address to bind to. The <i>bindAddr</i> argument 0N/A * can be used on a multi-homed host for a ServerSocket that 0N/A * will only accept connect requests to one of its addresses. 0N/A * If <i>bindAddr</i> is null, it will default accepting 0N/A * The port must be between 0 and 65535, inclusive. 0N/A * A port number of <code>0</code> means that the port number is 0N/A * automatically allocated, typically from an ephemeral port range. 0N/A * This port number can then be retrieved by calling 0N/A * {@link #getLocalPort getLocalPort}. 0N/A * <P>If there is a security manager, this method 0N/A * calls its <code>checkListen</code> method 0N/A * with the <code>port</code> argument 0N/A * as its argument to ensure the operation is allowed. 0N/A * This could result in a SecurityException. 0N/A * <P>The <code>backlog</code> argument must be a positive 0N/A * value greater than 0. If the value passed is equal or less 0N/A * than 0, then the default value will be assumed. 0N/A * @param port the port number, or <code>0</code> to use a port 0N/A * number that is automatically allocated. 0N/A * @param backlog the listen backlog 0N/A * @param bindAddr the local InetAddress the server will bind to 0N/A * @throws SecurityException if a security manager exists and 0N/A * its <code>checkListen</code> method doesn't allow the operation. 0N/A * @throws IOException if an I/O error occurs when opening the socket. 0N/A * @exception IllegalArgumentException if the port parameter is outside 0N/A * the specified range of valid port values, which is between 0N/A * 0 and 65535, inclusive. 0N/A * @see SocketOptions 0N/A * @see SecurityManager#checkListen 0N/A "Port value out of range: " +
port);
0N/A * Get the <code>SocketImpl</code> attached to this socket, creating 0N/A * @return the <code>SocketImpl</code> attached to that ServerSocket. 0N/A * @throws SocketException if creation fails. 0N/A // SocketImpl.connect() is a protected method, therefore we need to use 0N/A // getDeclaredMethod, therefore we need permission to access the member 0N/A // No need to do a checkOldImpl() here, we know it's an up to date 0N/A * Creates the socket implementation. 0N/A * @throws IOException if creation fails 0N/A * Binds the <code>ServerSocket</code> to a specific address 0N/A * (IP address and port number). 0N/A * If the address is <code>null</code>, then the system will pick up 0N/A * an ephemeral port and a valid local address to bind the socket. 0N/A * @param endpoint The IP address & port number to bind to. 0N/A * @throws IOException if the bind operation fails, or if the socket 0N/A * @throws SecurityException if a <code>SecurityManager</code> is present and 0N/A * its <code>checkListen</code> method doesn't allow the operation. 0N/A * @throws IllegalArgumentException if endpoint is a 0N/A * SocketAddress subclass not supported by this socket 0N/A * Binds the <code>ServerSocket</code> to a specific address 0N/A * (IP address and port number). 0N/A * If the address is <code>null</code>, then the system will pick up 0N/A * an ephemeral port and a valid local address to bind the socket. 0N/A * The <code>backlog</code> argument must be a positive 0N/A * value greater than 0. If the value passed is equal or less 0N/A * than 0, then the default value will be assumed. 0N/A * @param endpoint The IP address & port number to bind to. 0N/A * @param backlog The listen backlog length. 0N/A * @throws IOException if the bind operation fails, or if the socket 0N/A * @throws SecurityException if a <code>SecurityManager</code> is present and 0N/A * its <code>checkListen</code> method doesn't allow the operation. 0N/A * @throws IllegalArgumentException if endpoint is a 0N/A * SocketAddress subclass not supported by this socket 0N/A * Returns the local address of this server socket. 0N/A * If the socket was bound prior to being {@link #close closed}, 0N/A * then this method will continue to return the local address 0N/A * after the socket is closed. 0N/A * @return the address to which this socket is bound, 0N/A * or <code>null</code> if the socket is unbound. 0N/A // If we're bound, the impl has been created 0N/A // so we shouldn't get here 0N/A * Returns the port number on which this socket is listening. 0N/A * If the socket was bound prior to being {@link #close closed}, 0N/A * then this method will continue to return the port number 0N/A * after the socket is closed. 0N/A * @return the port number to which this socket is listening or 0N/A * -1 if the socket is not bound yet. 0N/A // If we're bound, the impl has been created 0N/A // so we shouldn't get here 0N/A * Returns the address of the endpoint this socket is bound to, or 0N/A * <code>null</code> if it is not bound yet. 0N/A * If the socket was bound prior to being {@link #close closed}, 0N/A * then this method will continue to return the address of the endpoint 0N/A * after the socket is closed. 0N/A * @return a <code>SocketAddress</code> representing the local endpoint of this 0N/A * socket, or <code>null</code> if it is not bound yet. 0N/A * @see #getInetAddress() 0N/A * @see #getLocalPort() 0N/A * @see #bind(SocketAddress) 0N/A * Listens for a connection to be made to this socket and accepts 0N/A * it. The method blocks until a connection is made. 0N/A * <p>A new Socket <code>s</code> is created and, if there 0N/A * is a security manager, 0N/A * the security manager's <code>checkAccept</code> method is called 0N/A * with <code>s.getInetAddress().getHostAddress()</code> and 0N/A * <code>s.getPort()</code> 0N/A * as its arguments to ensure the operation is allowed. 0N/A * This could result in a SecurityException. 0N/A * @exception IOException if an I/O error occurs when waiting for a 0N/A * @exception SecurityException if a security manager exists and its 0N/A * <code>checkAccept</code> method doesn't allow the operation. 0N/A * @exception SocketTimeoutException if a timeout was previously set with setSoTimeout and 0N/A * the timeout has been reached. 0N/A * @exception java.nio.channels.IllegalBlockingModeException 0N/A * if this socket has an associated channel, the channel is in 0N/A * non-blocking mode, and there is no connection ready to be 0N/A * @return the new Socket 0N/A * @see SecurityManager#checkAccept 0N/A * Subclasses of ServerSocket use this method to override accept() 0N/A * to return their own subclass of socket. So a FooServerSocket 0N/A * will typically hand this method an <i>empty</i> FooSocket. On 0N/A * return from implAccept the FooSocket will be connected to a client. 0N/A * @param s the Socket 0N/A * @throws java.nio.channels.IllegalBlockingModeException 0N/A * if this socket has an associated channel, 0N/A * and the channel is in non-blocking mode 0N/A * @throws IOException if an I/O error occurs when waiting 0N/A * Closes this socket. 0N/A * Any thread currently blocked in {@link #accept()} will throw 0N/A * a {@link SocketException}. 0N/A * <p> If this socket has an associated channel then the channel is closed 0N/A * @exception IOException if an I/O error occurs when closing the socket. 0N/A * Returns the unique {@link java.nio.channels.ServerSocketChannel} object 0N/A * associated with this socket, if any. 0N/A * <p> A server socket will have a channel if, and only if, the channel 0N/A * itself was created via the {@link 0N/A * java.nio.channels.ServerSocketChannel#open ServerSocketChannel.open} 0N/A * @return the server-socket channel associated with this socket, 0N/A * or <tt>null</tt> if this socket was not created 0N/A * Returns the binding state of the ServerSocket. 0N/A * @return true if the ServerSocket succesfuly bound to an address 0N/A // Before 1.3 ServerSockets were always bound during creation 0N/A * Returns the closed state of the ServerSocket. 0N/A * @return true if the socket has been closed 0N/A * milliseconds. With this option set to a non-zero timeout, 0N/A * a call to accept() for this ServerSocket 0N/A * will block for only this amount of time. If the timeout expires, 0N/A * a <B>java.net.SocketTimeoutException</B> is raised, though the 0N/A * ServerSocket is still valid. The option <B>must</B> be enabled 0N/A * prior to entering the blocking operation to have effect. The 0N/A * timeout must be > 0. 0N/A * A timeout of zero is interpreted as an infinite timeout. 0N/A * @param timeout the specified timeout, in milliseconds 0N/A * @exception SocketException if there is an error in 0N/A * the underlying protocol, such as a TCP error. 0N/A * @see #getSoTimeout() 0N/A * Retrieve setting for SO_TIMEOUT. 0 returns implies that the 0N/A * option is disabled (i.e., timeout of infinity). 0N/A * @return the SO_TIMEOUT value 0N/A * @exception IOException if an I/O error occurs 0N/A * @see #setSoTimeout(int) 0N/A /* extra type safety */ 0N/A * When a TCP connection is closed the connection may remain 0N/A * in a timeout state for a period of time after the connection 0N/A * is closed (typically known as the <tt>TIME_WAIT</tt> state 0N/A * or <tt>2MSL</tt> wait state). 0N/A * For applications using a well known socket address or port 0N/A * it may not be possible to bind a socket to the required 0N/A * <tt>SocketAddress</tt> if there is a connection in the 0N/A * timeout state involving the socket address or port. 0N/A * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket 0N/A * using {@link #bind(SocketAddress)} allows the socket to be 0N/A * bound even though a previous connection is in a timeout 0N/A * When a <tt>ServerSocket</tt> is created the initial setting 0N/A * of <tt>SO_REUSEADDR</tt> is not defined. Applications can 0N/A * use {@link #getReuseAddress()} to determine the initial 0N/A * setting of <tt>SO_REUSEADDR</tt>. 0N/A * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or 0N/A * disabled after a socket is bound (See {@link #isBound()}) 0N/A * @param on whether to enable or disable the socket option 0N/A * @exception SocketException if an error occurs enabling or 0N/A * disabling the <tt>SO_RESUEADDR</tt> socket option, 0N/A * or the socket is closed. 0N/A * @see #getReuseAddress() 0N/A * @see #bind(SocketAddress) 0N/A * Tests if SO_REUSEADDR is enabled. 0N/A * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is enabled. 0N/A * @exception SocketException if there is an error 0N/A * in the underlying protocol, such as a TCP error. 0N/A * @see #setReuseAddress(boolean) 0N/A * Returns the implementation address and implementation port of 0N/A * this socket as a <code>String</code>. 0N/A * @return a string representation of this socket. 0N/A return "ServerSocket[unbound]";
0N/A * The factory for all server sockets. 0N/A * Sets the server socket implementation factory for the 0N/A * application. The factory can be specified only once. 0N/A * When an application creates a new server socket, the socket 0N/A * implementation factory's <code>createSocketImpl</code> method is 0N/A * called to create the actual socket implementation. 0N/A * Passing <code>null</code> to the method is a no-op unless the factory 0N/A * If there is a security manager, this method first calls 0N/A * the security manager's <code>checkSetFactory</code> method 0N/A * to ensure the operation is allowed. 0N/A * This could result in a SecurityException. 0N/A * @param fac the desired factory. 0N/A * @exception IOException if an I/O error occurs when setting the 0N/A * @exception SocketException if the factory has already been defined. 0N/A * @exception SecurityException if a security manager exists and its 0N/A * <code>checkSetFactory</code> method doesn't allow the operation. 0N/A * @see java.net.SocketImplFactory#createSocketImpl() 0N/A * @see SecurityManager#checkSetFactory 0N/A * Sets a default proposed value for the SO_RCVBUF option for sockets 0N/A * accepted from this <tt>ServerSocket</tt>. The value actually set 0N/A * in the accepted socket must be determined by calling 0N/A * {@link Socket#getReceiveBufferSize()} after the socket 0N/A * is returned by {@link #accept()}. 0N/A * The value of SO_RCVBUF is used both to set the size of the internal 0N/A * socket receive buffer, and to set the size of the TCP receive window 0N/A * that is advertized to the remote peer. 0N/A * It is possible to change the value subsequently, by calling 0N/A * {@link Socket#setReceiveBufferSize(int)}. However, if the application 0N/A * wishes to allow a receive window larger than 64K bytes, as defined by RFC1323 0N/A * then the proposed value must be set in the ServerSocket <B>before</B> 0N/A * it is bound to a local address. This implies, that the ServerSocket must be 0N/A * created with the no-argument constructor, then setReceiveBufferSize() must 0N/A * be called and lastly the ServerSocket is bound to an address by calling bind(). 0N/A * Failure to do this will not cause an error, and the buffer size may be set to the 0N/A * requested value but the TCP receive window in sockets accepted from 0N/A * this ServerSocket will be no larger than 64K bytes. 0N/A * @exception SocketException if there is an error 0N/A * in the underlying protocol, such as a TCP error. 0N/A * @param size the size to which to set the receive buffer 0N/A * size. This value must be greater than 0. 0N/A * @exception IllegalArgumentException if the 0N/A * value is 0 or is negative. 0N/A * @see #getReceiveBufferSize 0N/A * Gets the value of the SO_RCVBUF option for this <tt>ServerSocket</tt>, 0N/A * that is the proposed buffer size that will be used for Sockets accepted 0N/A * from this <tt>ServerSocket</tt>. 0N/A * <p>Note, the value actually set in the accepted socket is determined by 0N/A * calling {@link Socket#getReceiveBufferSize()}. 0N/A * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>. 0N/A * @exception SocketException if there is an error 0N/A * in the underlying protocol, such as a TCP error. 0N/A * @see #setReceiveBufferSize(int) 0N/A * Sets performance preferences for this ServerSocket. 0N/A * <p> Sockets use the TCP/IP protocol by default. Some implementations 0N/A * may offer alternative protocols which have different performance 0N/A * characteristics than TCP/IP. This method allows the application to 0N/A * express its own preferences as to how these tradeoffs should be made 0N/A * when the implementation chooses from the available protocols. 0N/A * <p> Performance preferences are described by three integers 0N/A * whose values indicate the relative importance of short connection time, 0N/A * low latency, and high bandwidth. The absolute values of the integers 0N/A * are irrelevant; in order to choose a protocol the values are simply 0N/A * compared, with larger values indicating stronger preferences. If the 0N/A * application prefers short connection time over both low latency and high 0N/A * bandwidth, for example, then it could invoke this method with the values 0N/A * <tt>(1, 0, 0)</tt>. If the application prefers high bandwidth above low 0N/A * latency, and low latency above short connection time, then it could 0N/A * invoke this method with the values <tt>(0, 1, 2)</tt>. 0N/A * <p> Invoking this method after this socket has been bound 0N/A * will have no effect. This implies that in order to use this capability 0N/A * requires the socket to be created with the no-argument constructor. 0N/A * @param connectionTime 0N/A * An <tt>int</tt> expressing the relative importance of a short 0N/A * An <tt>int</tt> expressing the relative importance of low 0N/A * An <tt>int</tt> expressing the relative importance of high 0N/A /* Not implemented yet */