content: /*
   * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.nio.channels;
  
  import java.io.IOException;
  import java.net.ServerSocket;
  import java.net.SocketOption;
  import java.net.SocketAddress;
  import java.nio.channels.spi.AbstractSelectableChannel;
  import java.nio.channels.spi.SelectorProvider;
  
  /**
   * A selectable channel for stream-oriented listening sockets.
   *
   * <p> A server-socket channel is created by invoking the {@link #open() open}
   * method of this class.  It is not possible to create a channel for an arbitrary,
   * pre-existing {@link ServerSocket}. A newly-created server-socket channel is
   * open but not yet bound.  An attempt to invoke the {@link #accept() accept}
   * method of an unbound server-socket channel will cause a {@link NotYetBoundException}
   * to be thrown. A server-socket channel can be bound by invoking one of the
   * {@link #bind(SocketAddress,int) bind} methods defined by this class.
   *
   * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
   * setOption} method. Server-socket channels support the following options:
   * <blockquote>
   * <table border summary="Socket options">
   *   <tr>
   *     <th>Option Name</th>
   *     <th>Description</th>
   *   </tr>
   *   <tr>
   *     <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
   *     <td> The size of the socket receive buffer </td>
   *   </tr>
   *   <tr>
   *     <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
   *     <td> Re-use address </td>
   *   </tr>
   * </table>
   * </blockquote>
   * Additional (implementation specific) options may also be supported.
   *
   * <p> Server-socket channels are safe for use by multiple concurrent threads.
   * </p>
   *
   * @author Mark Reinhold
   * @author JSR-51 Expert Group
   * @since 1.4
   */
  
  public abstract class ServerSocketChannel
      extends AbstractSelectableChannel
      implements NetworkChannel
  {
  
      /**
       * Initializes a new instance of this class.
       *
       * @param  provider
       *         The provider that created this channel
       */
      protected ServerSocketChannel(SelectorProvider provider) {
          super(provider);
      }
  
      /**
       * Opens a server-socket channel.
       *
       * <p> The new channel is created by invoking the {@link
       * SelectorProvider#openServerSocketChannel
       * openServerSocketChannel} method of the system-wide default {@link
       * SelectorProvider} object.
       *
       * <p> The new channel's socket is initially unbound; it must be bound to a
       * specific address via one of its socket's {@link
       * ServerSocket#bind(SocketAddress) bind} methods before
       * connections can be accepted.  </p>
       *
       * @return  A new socket channel
       *
       * @throws  IOException
       *          If an I/O error occurs
       */
      public static ServerSocketChannel open() throws IOException {
          return SelectorProvider.provider().openServerSocketChannel();
      }
  
      /**
       * Returns an operation set identifying this channel's supported
       * operations.
       *
       * <p> Server-socket channels only support the accepting of new
       * connections, so this method returns {@link SelectionKey#OP_ACCEPT}.
       * </p>
       *
       * @return  The valid-operation set
       */
      public final int validOps() {
          return SelectionKey.OP_ACCEPT;
      }
  
  
      // -- ServerSocket-specific operations --
  
      /**
       * Binds the channel's socket to a local address and configures the socket
       * to listen for connections.
       *
       * <p> An invocation of this method is equivalent to the following:
       * <blockquote><pre>
       * bind(local, 0);
       * </pre></blockquote>
       *
       * @param   local
       *          The local address to bind the socket, or {@code null} to bind
       *          to an automatically assigned socket address
       *
       * @return  This channel
       *
       * @throws  AlreadyBoundException               {@inheritDoc}
       * @throws  UnsupportedAddressTypeException     {@inheritDoc}
       * @throws  ClosedChannelException              {@inheritDoc}
       * @throws  IOException                         {@inheritDoc}
       * @throws  SecurityException
       *          If a security manager has been installed and its {@link
       *          SecurityManager#checkListen checkListen} method denies the
       *          operation
       *
       * @since 1.7
       */
      public final ServerSocketChannel bind(SocketAddress local)
          throws IOException
      {
          return bind(local, 0);
      }
  
      /**
       * Binds the channel's socket to a local address and configures the socket to
       * listen for connections.
       *
       * <p> This method is used to establish an association between the socket and
       * a local address. Once an association is established then the socket remains
       * bound until the channel is closed.
       *
       * <p> The {@code backlog} parameter is the maximum number of pending
       * connections on the socket. Its exact semantics are implementation specific.
       * In particular, an implementation may impose a maximum length or may choose
       * to ignore the parameter altogther. If the {@code backlog} parameter has
       * the value {@code 0}, or a negative value, then an implementation specific
       * default is used.
       *
       * @param   local
       *          The address to bind the socket, or {@code null} to bind to an
       *          automatically assigned socket address
       * @param   backlog
       *          The maximum number of pending connections
       *
       * @return  This channel
       *
       * @throws  AlreadyBoundException
       *          If the socket is already bound
       * @throws  UnsupportedAddressTypeException
       *          If the type of the given address is not supported
       * @throws  ClosedChannelException
       *          If this channel is closed
       * @throws  IOException
       *          If some other I/O error occurs
       * @throws  SecurityException
       *          If a security manager has been installed and its {@link
       *          SecurityManager#checkListen checkListen} method denies the
       *          operation
       *
       * @since 1.7
       */
      public abstract ServerSocketChannel bind(SocketAddress local, int backlog)
          throws IOException;
  
      /**
       * @throws  UnsupportedOperationException           {@inheritDoc}
       * @throws  IllegalArgumentException                {@inheritDoc}
       * @throws  ClosedChannelException                  {@inheritDoc}
       * @throws  IOException                             {@inheritDoc}
       *
       * @since 1.7
       */
      public abstract <T> ServerSocketChannel setOption(SocketOption<T> name, T value)
          throws IOException;
  
      /**
       * Retrieves a server socket associated with this channel.
       *
       * <p> The returned object will not declare any public methods that are not
       * declared in the {@link ServerSocket} class.  </p>
       *
       * @return  A server socket associated with this channel
       */
      public abstract ServerSocket socket();
  
      /**
       * Accepts a connection made to this channel's socket.
       *
       * <p> If this channel is in non-blocking mode then this method will
       * immediately return <tt>null</tt> if there are no pending connections.
       * Otherwise it will block indefinitely until a new connection is available
       * or an I/O error occurs.
       *
       * <p> The socket channel returned by this method, if any, will be in
       * blocking mode regardless of the blocking mode of this channel.
       *
       * <p> This method performs exactly the same security checks as the {@link
       * ServerSocket#accept accept} method of the {@link
       * ServerSocket} class.  That is, if a security manager has been
       * installed then for each new connection this method verifies that the
       * address and port number of the connection's remote endpoint are
       * permitted by the security manager's {@link
       * SecurityManager#checkAccept checkAccept} method.  </p>
       *
       * @return  The socket channel for the new connection,
       *          or <tt>null</tt> if this channel is in non-blocking mode
       *          and no connection is available to be accepted
       *
       * @throws  ClosedChannelException
       *          If this channel is closed
       *
       * @throws  AsynchronousCloseException
       *          If another thread closes this channel
       *          while the accept operation is in progress
       *
       * @throws  ClosedByInterruptException
       *          If another thread interrupts the current thread
       *          while the accept operation is in progress, thereby
       *          closing the channel and setting the current thread's
       *          interrupt status
       *
       * @throws  NotYetBoundException
       *          If this channel's socket has not yet been bound
       *
       * @throws  SecurityException
       *          If a security manager has been installed
       *          and it does not permit access to the remote endpoint
       *          of the new connection
       *
       * @throws  IOException
       *          If some other I/O error occurs
       */
      public abstract SocketChannel accept() throws IOException;
  
      /**
       * {@inheritDoc}
       * <p>
       * If there is a security manager set, its {@code checkConnect} method is
       * called with the local address and {@code -1} as its arguments to see
       * if the operation is allowed. If the operation is not allowed,
       * a {@code SocketAddress} representing the
       * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
       * local port of the channel's socket is returned.
       *
       * @return  The {@code SocketAddress} that the socket is bound to, or the
       *          {@code SocketAddress} representing the loopback address if
       *          denied by the security manager, or {@code null} if the
       *          channel's socket is not bound
       *
       * @throws  ClosedChannelException     {@inheritDoc}
       * @throws  IOException                {@inheritDoc}
       */
      @Override
      public abstract SocketAddress getLocalAddress() throws IOException;
  
  }
  