Save This Page
Home » openjdk-7 » java » net » [javadoc | source]
    1   /*
    2    * Copyright (c) 1995, 2010, 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   
   26   package java.net;
   27   
   28   import java.io.FileDescriptor;
   29   import java.io.IOException;
   30   import java.nio.channels.ServerSocketChannel;
   31   import java.security.AccessController;
   32   import java.security.PrivilegedExceptionAction;
   33   
   34   /**
   35    * This class implements server sockets. A server socket waits for
   36    * requests to come in over the network. It performs some operation
   37    * based on that request, and then possibly returns a result to the requester.
   38    * <p>
   39    * The actual work of the server socket is performed by an instance
   40    * of the <code>SocketImpl</code> class. An application can
   41    * change the socket factory that creates the socket
   42    * implementation to configure itself to create sockets
   43    * appropriate to the local firewall.
   44    *
   45    * @author  unascribed
   46    * @see     java.net.SocketImpl
   47    * @see     java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory)
   48    * @see     java.nio.channels.ServerSocketChannel
   49    * @since   JDK1.0
   50    */
   51   public
   52   class ServerSocket implements java.io.Closeable {
   53       /**
   54        * Various states of this socket.
   55        */
   56       private boolean created = false;
   57       private boolean bound = false;
   58       private boolean closed = false;
   59       private Object closeLock = new Object();
   60   
   61       /**
   62        * The implementation of this Socket.
   63        */
   64       private SocketImpl impl;
   65   
   66       /**
   67        * Are we using an older SocketImpl?
   68        */
   69       private boolean oldImpl = false;
   70   
   71       /**
   72        * Package-private constructor to create a ServerSocket associated with
   73        * the given SocketImpl.
   74        */
   75       ServerSocket(SocketImpl impl) {
   76           this.impl = impl;
   77           impl.setServerSocket(this);
   78       }
   79   
   80       /**
   81        * Creates an unbound server socket.
   82        *
   83        * @exception IOException IO error when opening the socket.
   84        * @revised 1.4
   85        */
   86       public ServerSocket() throws IOException {
   87           setImpl();
   88       }
   89   
   90       /**
   91        * Creates a server socket, bound to the specified port. A port number
   92        * of <code>0</code> means that the port number is automatically
   93        * allocated, typically from an ephemeral port range. This port
   94        * number can then be retrieved by calling {@link #getLocalPort getLocalPort}.
   95        * <p>
   96        * The maximum queue length for incoming connection indications (a
   97        * request to connect) is set to <code>50</code>. If a connection
   98        * indication arrives when the queue is full, the connection is refused.
   99        * <p>
  100        * If the application has specified a server socket factory, that
  101        * factory's <code>createSocketImpl</code> method is called to create
  102        * the actual socket implementation. Otherwise a "plain" socket is created.
  103        * <p>
  104        * If there is a security manager,
  105        * its <code>checkListen</code> method is called
  106        * with the <code>port</code> argument
  107        * as its argument to ensure the operation is allowed.
  108        * This could result in a SecurityException.
  109        *
  110        *
  111        * @param      port  the port number, or <code>0</code> to use a port
  112        *                   number that is automatically allocated.
  113        *
  114        * @exception  IOException  if an I/O error occurs when opening the socket.
  115        * @exception  SecurityException
  116        * if a security manager exists and its <code>checkListen</code>
  117        * method doesn't allow the operation.
  118        * @exception  IllegalArgumentException if the port parameter is outside
  119        *             the specified range of valid port values, which is between
  120        *             0 and 65535, inclusive.
  121        *
  122        * @see        java.net.SocketImpl
  123        * @see        java.net.SocketImplFactory#createSocketImpl()
  124        * @see        java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory)
  125        * @see        SecurityManager#checkListen
  126        */
  127       public ServerSocket(int port) throws IOException {
  128           this(port, 50, null);
  129       }
  130   
  131       /**
  132        * Creates a server socket and binds it to the specified local port
  133        * number, with the specified backlog.
  134        * A port number of <code>0</code> means that the port number is
  135        * automatically allocated, typically from an ephemeral port range.
  136        * This port number can then be retrieved by calling
  137        * {@link #getLocalPort getLocalPort}.
  138        * <p>
  139        * The maximum queue length for incoming connection indications (a
  140        * request to connect) is set to the <code>backlog</code> parameter. If
  141        * a connection indication arrives when the queue is full, the
  142        * connection is refused.
  143        * <p>
  144        * If the application has specified a server socket factory, that
  145        * factory's <code>createSocketImpl</code> method is called to create
  146        * the actual socket implementation. Otherwise a "plain" socket is created.
  147        * <p>
  148        * If there is a security manager,
  149        * its <code>checkListen</code> method is called
  150        * with the <code>port</code> argument
  151        * as its argument to ensure the operation is allowed.
  152        * This could result in a SecurityException.
  153        *
  154        * The <code>backlog</code> argument is the requested maximum number of
  155        * pending connections on the socket. Its exact semantics are implementation
  156        * specific. In particular, an implementation may impose a maximum length
  157        * or may choose to ignore the parameter altogther. The value provided
  158        * should be greater than <code>0</code>. If it is less than or equal to
  159        * <code>0</code>, then an implementation specific default will be used.
  160        * <P>
  161        *
  162        * @param      port     the port number, or <code>0</code> to use a port
  163        *                      number that is automatically allocated.
  164        * @param      backlog  requested maximum length of the queue of incoming
  165        *                      connections.
  166        *
  167        * @exception  IOException  if an I/O error occurs when opening the socket.
  168        * @exception  SecurityException
  169        * if a security manager exists and its <code>checkListen</code>
  170        * method doesn't allow the operation.
  171        * @exception  IllegalArgumentException if the port parameter is outside
  172        *             the specified range of valid port values, which is between
  173        *             0 and 65535, inclusive.
  174        *
  175        * @see        java.net.SocketImpl
  176        * @see        java.net.SocketImplFactory#createSocketImpl()
  177        * @see        java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory)
  178        * @see        SecurityManager#checkListen
  179        */
  180       public ServerSocket(int port, int backlog) throws IOException {
  181           this(port, backlog, null);
  182       }
  183   
  184       /**
  185        * Create a server with the specified port, listen backlog, and
  186        * local IP address to bind to.  The <i>bindAddr</i> argument
  187        * can be used on a multi-homed host for a ServerSocket that
  188        * will only accept connect requests to one of its addresses.
  189        * If <i>bindAddr</i> is null, it will default accepting
  190        * connections on any/all local addresses.
  191        * The port must be between 0 and 65535, inclusive.
  192        * A port number of <code>0</code> means that the port number is
  193        * automatically allocated, typically from an ephemeral port range.
  194        * This port number can then be retrieved by calling
  195        * {@link #getLocalPort getLocalPort}.
  196        *
  197        * <P>If there is a security manager, this method
  198        * calls its <code>checkListen</code> method
  199        * with the <code>port</code> argument
  200        * as its argument to ensure the operation is allowed.
  201        * This could result in a SecurityException.
  202        *
  203        * The <code>backlog</code> argument is the requested maximum number of
  204        * pending connections on the socket. Its exact semantics are implementation
  205        * specific. In particular, an implementation may impose a maximum length
  206        * or may choose to ignore the parameter altogther. The value provided
  207        * should be greater than <code>0</code>. If it is less than or equal to
  208        * <code>0</code>, then an implementation specific default will be used.
  209        * <P>
  210        * @param port  the port number, or <code>0</code> to use a port
  211        *              number that is automatically allocated.
  212        * @param backlog requested maximum length of the queue of incoming
  213        *                connections.
  214        * @param bindAddr the local InetAddress the server will bind to
  215        *
  216        * @throws  SecurityException if a security manager exists and
  217        * its <code>checkListen</code> method doesn't allow the operation.
  218        *
  219        * @throws  IOException if an I/O error occurs when opening the socket.
  220        * @exception  IllegalArgumentException if the port parameter is outside
  221        *             the specified range of valid port values, which is between
  222        *             0 and 65535, inclusive.
  223        *
  224        * @see SocketOptions
  225        * @see SocketImpl
  226        * @see SecurityManager#checkListen
  227        * @since   JDK1.1
  228        */
  229       public ServerSocket(int port, int backlog, InetAddress bindAddr) throws IOException {
  230           setImpl();
  231           if (port < 0 || port > 0xFFFF)
  232               throw new IllegalArgumentException(
  233                          "Port value out of range: " + port);
  234           if (backlog < 1)
  235             backlog = 50;
  236           try {
  237               bind(new InetSocketAddress(bindAddr, port), backlog);
  238           } catch(SecurityException e) {
  239               close();
  240               throw e;
  241           } catch(IOException e) {
  242               close();
  243               throw e;
  244           }
  245       }
  246   
  247       /**
  248        * Get the <code>SocketImpl</code> attached to this socket, creating
  249        * it if necessary.
  250        *
  251        * @return  the <code>SocketImpl</code> attached to that ServerSocket.
  252        * @throws SocketException if creation fails.
  253        * @since 1.4
  254        */
  255       SocketImpl getImpl() throws SocketException {
  256           if (!created)
  257               createImpl();
  258           return impl;
  259       }
  260   
  261       private void checkOldImpl() {
  262           if (impl == null)
  263               return;
  264           // SocketImpl.connect() is a protected method, therefore we need to use
  265           // getDeclaredMethod, therefore we need permission to access the member
  266           try {
  267               AccessController.doPrivileged(
  268                   new PrivilegedExceptionAction<Void>() {
  269                       public Void run() throws NoSuchMethodException {
  270                           Class[] cl = new Class[2];
  271                           cl[0] = SocketAddress.class;
  272                           cl[1] = Integer.TYPE;
  273                           impl.getClass().getDeclaredMethod("connect", cl);
  274                           return null;
  275                       }
  276                   });
  277           } catch (java.security.PrivilegedActionException e) {
  278               oldImpl = true;
  279           }
  280       }
  281   
  282       private void setImpl() {
  283           if (factory != null) {
  284               impl = factory.createSocketImpl();
  285               checkOldImpl();
  286           } else {
  287               // No need to do a checkOldImpl() here, we know it's an up to date
  288               // SocketImpl!
  289               impl = new SocksSocketImpl();
  290           }
  291           if (impl != null)
  292               impl.setServerSocket(this);
  293       }
  294   
  295       /**
  296        * Creates the socket implementation.
  297        *
  298        * @throws IOException if creation fails
  299        * @since 1.4
  300        */
  301       void createImpl() throws SocketException {
  302           if (impl == null)
  303               setImpl();
  304           try {
  305               impl.create(true);
  306               created = true;
  307           } catch (IOException e) {
  308               throw new SocketException(e.getMessage());
  309           }
  310       }
  311   
  312       /**
  313        *
  314        * Binds the <code>ServerSocket</code> to a specific address
  315        * (IP address and port number).
  316        * <p>
  317        * If the address is <code>null</code>, then the system will pick up
  318        * an ephemeral port and a valid local address to bind the socket.
  319        * <p>
  320        * @param   endpoint        The IP address & port number to bind to.
  321        * @throws  IOException if the bind operation fails, or if the socket
  322        *                     is already bound.
  323        * @throws  SecurityException       if a <code>SecurityManager</code> is present and
  324        * its <code>checkListen</code> method doesn't allow the operation.
  325        * @throws  IllegalArgumentException if endpoint is a
  326        *          SocketAddress subclass not supported by this socket
  327        * @since 1.4
  328        */
  329       public void bind(SocketAddress endpoint) throws IOException {
  330           bind(endpoint, 50);
  331       }
  332   
  333       /**
  334        *
  335        * Binds the <code>ServerSocket</code> to a specific address
  336        * (IP address and port number).
  337        * <p>
  338        * If the address is <code>null</code>, then the system will pick up
  339        * an ephemeral port and a valid local address to bind the socket.
  340        * <P>
  341        * The <code>backlog</code> argument is the requested maximum number of
  342        * pending connections on the socket. Its exact semantics are implementation
  343        * specific. In particular, an implementation may impose a maximum length
  344        * or may choose to ignore the parameter altogther. The value provided
  345        * should be greater than <code>0</code>. If it is less than or equal to
  346        * <code>0</code>, then an implementation specific default will be used.
  347        * @param   endpoint        The IP address & port number to bind to.
  348        * @param   backlog         requested maximum length of the queue of
  349        *                          incoming connections.
  350        * @throws  IOException if the bind operation fails, or if the socket
  351        *                     is already bound.
  352        * @throws  SecurityException       if a <code>SecurityManager</code> is present and
  353        * its <code>checkListen</code> method doesn't allow the operation.
  354        * @throws  IllegalArgumentException if endpoint is a
  355        *          SocketAddress subclass not supported by this socket
  356        * @since 1.4
  357        */
  358       public void bind(SocketAddress endpoint, int backlog) throws IOException {
  359           if (isClosed())
  360               throw new SocketException("Socket is closed");
  361           if (!oldImpl && isBound())
  362               throw new SocketException("Already bound");
  363           if (endpoint == null)
  364               endpoint = new InetSocketAddress(0);
  365           if (!(endpoint instanceof InetSocketAddress))
  366               throw new IllegalArgumentException("Unsupported address type");
  367           InetSocketAddress epoint = (InetSocketAddress) endpoint;
  368           if (epoint.isUnresolved())
  369               throw new SocketException("Unresolved address");
  370           if (backlog < 1)
  371             backlog = 50;
  372           try {
  373               SecurityManager security = System.getSecurityManager();
  374               if (security != null)
  375                   security.checkListen(epoint.getPort());
  376               getImpl().bind(epoint.getAddress(), epoint.getPort());
  377               getImpl().listen(backlog);
  378               bound = true;
  379           } catch(SecurityException e) {
  380               bound = false;
  381               throw e;
  382           } catch(IOException e) {
  383               bound = false;
  384               throw e;
  385           }
  386       }
  387   
  388       /**
  389        * Returns the local address of this server socket.
  390        * <p>
  391        * If the socket was bound prior to being {@link #close closed},
  392        * then this method will continue to return the local address
  393        * after the socket is closed.
  394        *
  395        * @return  the address to which this socket is bound,
  396        *          or <code>null</code> if the socket is unbound.
  397        */
  398       public InetAddress getInetAddress() {
  399           if (!isBound())
  400               return null;
  401           try {
  402               return getImpl().getInetAddress();
  403           } catch (SocketException e) {
  404               // nothing
  405               // If we're bound, the impl has been created
  406               // so we shouldn't get here
  407           }
  408           return null;
  409       }
  410   
  411       /**
  412        * Returns the port number on which this socket is listening.
  413        * <p>
  414        * If the socket was bound prior to being {@link #close closed},
  415        * then this method will continue to return the port number
  416        * after the socket is closed.
  417        *
  418        * @return  the port number to which this socket is listening or
  419        *          -1 if the socket is not bound yet.
  420        */
  421       public int getLocalPort() {
  422           if (!isBound())
  423               return -1;
  424           try {
  425               return getImpl().getLocalPort();
  426           } catch (SocketException e) {
  427               // nothing
  428               // If we're bound, the impl has been created
  429               // so we shouldn't get here
  430           }
  431           return -1;
  432       }
  433   
  434       /**
  435        * Returns the address of the endpoint this socket is bound to, or
  436        * <code>null</code> if it is not bound yet.
  437        * <p>
  438        * If the socket was bound prior to being {@link #close closed},
  439        * then this method will continue to return the address of the endpoint
  440        * after the socket is closed.
  441        *
  442        * @return a <code>SocketAddress</code> representing the local endpoint of this
  443        *         socket, or <code>null</code> if it is not bound yet.
  444        * @see #getInetAddress()
  445        * @see #getLocalPort()
  446        * @see #bind(SocketAddress)
  447        * @since 1.4
  448        */
  449   
  450       public SocketAddress getLocalSocketAddress() {
  451           if (!isBound())
  452               return null;
  453           return new InetSocketAddress(getInetAddress(), getLocalPort());
  454       }
  455   
  456       /**
  457        * Listens for a connection to be made to this socket and accepts
  458        * it. The method blocks until a connection is made.
  459        *
  460        * <p>A new Socket <code>s</code> is created and, if there
  461        * is a security manager,
  462        * the security manager's <code>checkAccept</code> method is called
  463        * with <code>s.getInetAddress().getHostAddress()</code> and
  464        * <code>s.getPort()</code>
  465        * as its arguments to ensure the operation is allowed.
  466        * This could result in a SecurityException.
  467        *
  468        * @exception  IOException  if an I/O error occurs when waiting for a
  469        *               connection.
  470        * @exception  SecurityException  if a security manager exists and its
  471        *             <code>checkAccept</code> method doesn't allow the operation.
  472        * @exception  SocketTimeoutException if a timeout was previously set with setSoTimeout and
  473        *             the timeout has been reached.
  474        * @exception  java.nio.channels.IllegalBlockingModeException
  475        *             if this socket has an associated channel, the channel is in
  476        *             non-blocking mode, and there is no connection ready to be
  477        *             accepted
  478        *
  479        * @return the new Socket
  480        * @see SecurityManager#checkAccept
  481        * @revised 1.4
  482        * @spec JSR-51
  483        */
  484       public Socket accept() throws IOException {
  485           if (isClosed())
  486               throw new SocketException("Socket is closed");
  487           if (!isBound())
  488               throw new SocketException("Socket is not bound yet");
  489           Socket s = new Socket((SocketImpl) null);
  490           implAccept(s);
  491           return s;
  492       }
  493   
  494       /**
  495        * Subclasses of ServerSocket use this method to override accept()
  496        * to return their own subclass of socket.  So a FooServerSocket
  497        * will typically hand this method an <i>empty</i> FooSocket.  On
  498        * return from implAccept the FooSocket will be connected to a client.
  499        *
  500        * @param s the Socket
  501        * @throws java.nio.channels.IllegalBlockingModeException
  502        *         if this socket has an associated channel,
  503        *         and the channel is in non-blocking mode
  504        * @throws IOException if an I/O error occurs when waiting
  505        * for a connection.
  506        * @since   JDK1.1
  507        * @revised 1.4
  508        * @spec JSR-51
  509        */
  510       protected final void implAccept(Socket s) throws IOException {
  511           SocketImpl si = null;
  512           try {
  513               if (s.impl == null)
  514                 s.setImpl();
  515               else {
  516                   s.impl.reset();
  517               }
  518               si = s.impl;
  519               s.impl = null;
  520               si.address = new InetAddress();
  521               si.fd = new FileDescriptor();
  522               getImpl().accept(si);
  523   
  524               SecurityManager security = System.getSecurityManager();
  525               if (security != null) {
  526                   security.checkAccept(si.getInetAddress().getHostAddress(),
  527                                        si.getPort());
  528               }
  529           } catch (IOException e) {
  530               if (si != null)
  531                   si.reset();
  532               s.impl = si;
  533               throw e;
  534           } catch (SecurityException e) {
  535               if (si != null)
  536                   si.reset();
  537               s.impl = si;
  538               throw e;
  539           }
  540           s.impl = si;
  541           s.postAccept();
  542       }
  543   
  544       /**
  545        * Closes this socket.
  546        *
  547        * Any thread currently blocked in {@link #accept()} will throw
  548        * a {@link SocketException}.
  549        *
  550        * <p> If this socket has an associated channel then the channel is closed
  551        * as well.
  552        *
  553        * @exception  IOException  if an I/O error occurs when closing the socket.
  554        * @revised 1.4
  555        * @spec JSR-51
  556        */
  557       public void close() throws IOException {
  558           synchronized(closeLock) {
  559               if (isClosed())
  560                   return;
  561               if (created)
  562                   impl.close();
  563               closed = true;
  564           }
  565       }
  566   
  567       /**
  568        * Returns the unique {@link java.nio.channels.ServerSocketChannel} object
  569        * associated with this socket, if any.
  570        *
  571        * <p> A server socket will have a channel if, and only if, the channel
  572        * itself was created via the {@link
  573        * java.nio.channels.ServerSocketChannel#open ServerSocketChannel.open}
  574        * method.
  575        *
  576        * @return  the server-socket channel associated with this socket,
  577        *          or <tt>null</tt> if this socket was not created
  578        *          for a channel
  579        *
  580        * @since 1.4
  581        * @spec JSR-51
  582        */
  583       public ServerSocketChannel getChannel() {
  584           return null;
  585       }
  586   
  587       /**
  588        * Returns the binding state of the ServerSocket.
  589        *
  590        * @return true if the ServerSocket succesfuly bound to an address
  591        * @since 1.4
  592        */
  593       public boolean isBound() {
  594           // Before 1.3 ServerSockets were always bound during creation
  595           return bound || oldImpl;
  596       }
  597   
  598       /**
  599        * Returns the closed state of the ServerSocket.
  600        *
  601        * @return true if the socket has been closed
  602        * @since 1.4
  603        */
  604       public boolean isClosed() {
  605           synchronized(closeLock) {
  606               return closed;
  607           }
  608       }
  609   
  610       /**
  611        * Enable/disable SO_TIMEOUT with the specified timeout, in
  612        * milliseconds.  With this option set to a non-zero timeout,
  613        * a call to accept() for this ServerSocket
  614        * will block for only this amount of time.  If the timeout expires,
  615        * a <B>java.net.SocketTimeoutException</B> is raised, though the
  616        * ServerSocket is still valid.  The option <B>must</B> be enabled
  617        * prior to entering the blocking operation to have effect.  The
  618        * timeout must be > 0.
  619        * A timeout of zero is interpreted as an infinite timeout.
  620        * @param timeout the specified timeout, in milliseconds
  621        * @exception SocketException if there is an error in
  622        * the underlying protocol, such as a TCP error.
  623        * @since   JDK1.1
  624        * @see #getSoTimeout()
  625        */
  626       public synchronized void setSoTimeout(int timeout) throws SocketException {
  627           if (isClosed())
  628               throw new SocketException("Socket is closed");
  629           getImpl().setOption(SocketOptions.SO_TIMEOUT, new Integer(timeout));
  630       }
  631   
  632       /**
  633        * Retrieve setting for SO_TIMEOUT.  0 returns implies that the
  634        * option is disabled (i.e., timeout of infinity).
  635        * @return the SO_TIMEOUT value
  636        * @exception IOException if an I/O error occurs
  637        * @since   JDK1.1
  638        * @see #setSoTimeout(int)
  639        */
  640       public synchronized int getSoTimeout() throws IOException {
  641           if (isClosed())
  642               throw new SocketException("Socket is closed");
  643           Object o = getImpl().getOption(SocketOptions.SO_TIMEOUT);
  644           /* extra type safety */
  645           if (o instanceof Integer) {
  646               return ((Integer) o).intValue();
  647           } else {
  648               return 0;
  649           }
  650       }
  651   
  652       /**
  653        * Enable/disable the SO_REUSEADDR socket option.
  654        * <p>
  655        * When a TCP connection is closed the connection may remain
  656        * in a timeout state for a period of time after the connection
  657        * is closed (typically known as the <tt>TIME_WAIT</tt> state
  658        * or <tt>2MSL</tt> wait state).
  659        * For applications using a well known socket address or port
  660        * it may not be possible to bind a socket to the required
  661        * <tt>SocketAddress</tt> if there is a connection in the
  662        * timeout state involving the socket address or port.
  663        * <p>
  664        * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket
  665        * using {@link #bind(SocketAddress)} allows the socket to be
  666        * bound even though a previous connection is in a timeout
  667        * state.
  668        * <p>
  669        * When a <tt>ServerSocket</tt> is created the initial setting
  670        * of <tt>SO_REUSEADDR</tt> is not defined. Applications can
  671        * use {@link #getReuseAddress()} to determine the initial
  672        * setting of <tt>SO_REUSEADDR</tt>.
  673        * <p>
  674        * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or
  675        * disabled after a socket is bound (See {@link #isBound()})
  676        * is not defined.
  677        *
  678        * @param on  whether to enable or disable the socket option
  679        * @exception SocketException if an error occurs enabling or
  680        *            disabling the <tt>SO_RESUEADDR</tt> socket option,
  681        *            or the socket is closed.
  682        * @since 1.4
  683        * @see #getReuseAddress()
  684        * @see #bind(SocketAddress)
  685        * @see #isBound()
  686        * @see #isClosed()
  687        */
  688       public void setReuseAddress(boolean on) throws SocketException {
  689           if (isClosed())
  690               throw new SocketException("Socket is closed");
  691           getImpl().setOption(SocketOptions.SO_REUSEADDR, Boolean.valueOf(on));
  692       }
  693   
  694       /**
  695        * Tests if SO_REUSEADDR is enabled.
  696        *
  697        * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is enabled.
  698        * @exception SocketException if there is an error
  699        * in the underlying protocol, such as a TCP error.
  700        * @since   1.4
  701        * @see #setReuseAddress(boolean)
  702        */
  703       public boolean getReuseAddress() throws SocketException {
  704           if (isClosed())
  705               throw new SocketException("Socket is closed");
  706           return ((Boolean) (getImpl().getOption(SocketOptions.SO_REUSEADDR))).booleanValue();
  707       }
  708   
  709       /**
  710        * Returns the implementation address and implementation port of
  711        * this socket as a <code>String</code>.
  712        *
  713        * @return  a string representation of this socket.
  714        */
  715       public String toString() {
  716           if (!isBound())
  717               return "ServerSocket[unbound]";
  718           return "ServerSocket[addr=" + impl.getInetAddress() +
  719                   ",port=" + impl.getPort() +
  720                   ",localport=" + impl.getLocalPort()  + "]";
  721       }
  722   
  723       void setBound() {
  724           bound = true;
  725       }
  726   
  727       void setCreated() {
  728           created = true;
  729       }
  730   
  731       /**
  732        * The factory for all server sockets.
  733        */
  734       private static SocketImplFactory factory = null;
  735   
  736       /**
  737        * Sets the server socket implementation factory for the
  738        * application. The factory can be specified only once.
  739        * <p>
  740        * When an application creates a new server socket, the socket
  741        * implementation factory's <code>createSocketImpl</code> method is
  742        * called to create the actual socket implementation.
  743        * <p>
  744        * Passing <code>null</code> to the method is a no-op unless the factory
  745        * was already set.
  746        * <p>
  747        * If there is a security manager, this method first calls
  748        * the security manager's <code>checkSetFactory</code> method
  749        * to ensure the operation is allowed.
  750        * This could result in a SecurityException.
  751        *
  752        * @param      fac   the desired factory.
  753        * @exception  IOException  if an I/O error occurs when setting the
  754        *               socket factory.
  755        * @exception  SocketException  if the factory has already been defined.
  756        * @exception  SecurityException  if a security manager exists and its
  757        *             <code>checkSetFactory</code> method doesn't allow the operation.
  758        * @see        java.net.SocketImplFactory#createSocketImpl()
  759        * @see        SecurityManager#checkSetFactory
  760        */
  761       public static synchronized void setSocketFactory(SocketImplFactory fac) throws IOException {
  762           if (factory != null) {
  763               throw new SocketException("factory already defined");
  764           }
  765           SecurityManager security = System.getSecurityManager();
  766           if (security != null) {
  767               security.checkSetFactory();
  768           }
  769           factory = fac;
  770       }
  771   
  772       /**
  773        * Sets a default proposed value for the SO_RCVBUF option for sockets
  774        * accepted from this <tt>ServerSocket</tt>. The value actually set
  775        * in the accepted socket must be determined by calling
  776        * {@link Socket#getReceiveBufferSize()} after the socket
  777        * is returned by {@link #accept()}.
  778        * <p>
  779        * The value of SO_RCVBUF is used both to set the size of the internal
  780        * socket receive buffer, and to set the size of the TCP receive window
  781        * that is advertized to the remote peer.
  782        * <p>
  783        * It is possible to change the value subsequently, by calling
  784        * {@link Socket#setReceiveBufferSize(int)}. However, if the application
  785        * wishes to allow a receive window larger than 64K bytes, as defined by RFC1323
  786        * then the proposed value must be set in the ServerSocket <B>before</B>
  787        * it is bound to a local address. This implies, that the ServerSocket must be
  788        * created with the no-argument constructor, then setReceiveBufferSize() must
  789        * be called and lastly the ServerSocket is bound to an address by calling bind().
  790        * <p>
  791        * Failure to do this will not cause an error, and the buffer size may be set to the
  792        * requested value but the TCP receive window in sockets accepted from
  793        * this ServerSocket will be no larger than 64K bytes.
  794        *
  795        * @exception SocketException if there is an error
  796        * in the underlying protocol, such as a TCP error.
  797        *
  798        * @param size the size to which to set the receive buffer
  799        * size. This value must be greater than 0.
  800        *
  801        * @exception IllegalArgumentException if the
  802        * value is 0 or is negative.
  803        *
  804        * @since 1.4
  805        * @see #getReceiveBufferSize
  806        */
  807        public synchronized void setReceiveBufferSize (int size) throws SocketException {
  808           if (!(size > 0)) {
  809               throw new IllegalArgumentException("negative receive size");
  810           }
  811           if (isClosed())
  812               throw new SocketException("Socket is closed");
  813           getImpl().setOption(SocketOptions.SO_RCVBUF, new Integer(size));
  814       }
  815   
  816       /**
  817        * Gets the value of the SO_RCVBUF option for this <tt>ServerSocket</tt>,
  818        * that is the proposed buffer size that will be used for Sockets accepted
  819        * from this <tt>ServerSocket</tt>.
  820        *
  821        * <p>Note, the value actually set in the accepted socket is determined by
  822        * calling {@link Socket#getReceiveBufferSize()}.
  823        * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
  824        * @exception SocketException if there is an error
  825        * in the underlying protocol, such as a TCP error.
  826        * @see #setReceiveBufferSize(int)
  827        * @since 1.4
  828        */
  829       public synchronized int getReceiveBufferSize()
  830       throws SocketException{
  831           if (isClosed())
  832               throw new SocketException("Socket is closed");
  833           int result = 0;
  834           Object o = getImpl().getOption(SocketOptions.SO_RCVBUF);
  835           if (o instanceof Integer) {
  836               result = ((Integer)o).intValue();
  837           }
  838           return result;
  839       }
  840   
  841       /**
  842        * Sets performance preferences for this ServerSocket.
  843        *
  844        * <p> Sockets use the TCP/IP protocol by default.  Some implementations
  845        * may offer alternative protocols which have different performance
  846        * characteristics than TCP/IP.  This method allows the application to
  847        * express its own preferences as to how these tradeoffs should be made
  848        * when the implementation chooses from the available protocols.
  849        *
  850        * <p> Performance preferences are described by three integers
  851        * whose values indicate the relative importance of short connection time,
  852        * low latency, and high bandwidth.  The absolute values of the integers
  853        * are irrelevant; in order to choose a protocol the values are simply
  854        * compared, with larger values indicating stronger preferences.  If the
  855        * application prefers short connection time over both low latency and high
  856        * bandwidth, for example, then it could invoke this method with the values
  857        * <tt>(1, 0, 0)</tt>.  If the application prefers high bandwidth above low
  858        * latency, and low latency above short connection time, then it could
  859        * invoke this method with the values <tt>(0, 1, 2)</tt>.
  860        *
  861        * <p> Invoking this method after this socket has been bound
  862        * will have no effect. This implies that in order to use this capability
  863        * requires the socket to be created with the no-argument constructor.
  864        *
  865        * @param  connectionTime
  866        *         An <tt>int</tt> expressing the relative importance of a short
  867        *         connection time
  868        *
  869        * @param  latency
  870        *         An <tt>int</tt> expressing the relative importance of low
  871        *         latency
  872        *
  873        * @param  bandwidth
  874        *         An <tt>int</tt> expressing the relative importance of high
  875        *         bandwidth
  876        *
  877        * @since 1.5
  878        */
  879       public void setPerformancePreferences(int connectionTime,
  880                                             int latency,
  881                                             int bandwidth)
  882       {
  883           /* Not implemented yet */
  884       }
  885   
  886   }

Save This Page
Home » openjdk-7 » java » net » [javadoc | source]