1 /*
   2  * Copyright (c) 2000, 2013, 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.nio.channels;
  27 
  28 import java.io.IOException;
  29 import java.net.ServerSocket;
  30 import java.net.SocketOption;
  31 import java.net.SocketAddress;
  32 import java.nio.channels.spi.AbstractSelectableChannel;
  33 import java.nio.channels.spi.SelectorProvider;
  34 
  35 /**
  36  * A selectable channel for stream-oriented listening sockets.
  37  *
  38  * <p> A server-socket channel is created by invoking the {@link #open() open}
  39  * method of this class.  It is not possible to create a channel for an arbitrary,
  40  * pre-existing {@link ServerSocket}. A newly-created server-socket channel is
  41  * open but not yet bound.  An attempt to invoke the {@link #accept() accept}
  42  * method of an unbound server-socket channel will cause a {@link NotYetBoundException}
  43  * to be thrown. A server-socket channel can be bound by invoking one of the
  44  * {@link #bind(java.net.SocketAddress,int) bind} methods defined by this class.
  45  *
  46  * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
  47  * setOption} method. Server-socket channels support the following options:
  48  * <blockquote>
  49  * <table class="striped">
  50  * <caption style="display:none">Socket options</caption>
  51  * <thead>
  52  *   <tr>
  53  *     <th>Option Name</th>
  54  *     <th>Description</th>
  55  *   </tr>
  56  * </thead>
  57  * <tbody>
  58  *   <tr>
  59  *     <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
  60  *     <td> The size of the socket receive buffer </td>
  61  *   </tr>
  62  *   <tr>
  63  *     <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
  64  *     <td> Re-use address </td>
  65  *   </tr>
  66  * </tbody>
  67  * </table>
  68  * </blockquote>
  69  * Additional (implementation specific) options may also be supported.
  70  *
  71  * <p> Server-socket channels are safe for use by multiple concurrent threads.
  72  * </p>
  73  *
  74  * @author Mark Reinhold
  75  * @author JSR-51 Expert Group
  76  * @since 1.4
  77  */
  78 
  79 public abstract class ServerSocketChannel
  80     extends AbstractSelectableChannel
  81     implements NetworkChannel
  82 {
  83 
  84     /**
  85      * Initializes a new instance of this class.
  86      *
  87      * @param  provider
  88      *         The provider that created this channel
  89      */
  90     protected ServerSocketChannel(SelectorProvider provider) {
  91         super(provider);
  92     }
  93 
  94     /**
  95      * Opens a server-socket channel.
  96      *
  97      * <p> The new channel is created by invoking the {@link
  98      * java.nio.channels.spi.SelectorProvider#openServerSocketChannel
  99      * openServerSocketChannel} method of the system-wide default {@link
 100      * java.nio.channels.spi.SelectorProvider} object.
 101      *
 102      * <p> The new channel's socket is initially unbound; it must be bound to a
 103      * specific address via one of its socket's {@link
 104      * java.net.ServerSocket#bind(SocketAddress) bind} methods before
 105      * connections can be accepted.  </p>
 106      *
 107      * @return  A new socket channel
 108      *
 109      * @throws  IOException
 110      *          If an I/O error occurs
 111      */
 112     public static ServerSocketChannel open() throws IOException {
 113         return SelectorProvider.provider().openServerSocketChannel();
 114     }
 115 
 116     /**
 117      * Returns an operation set identifying this channel's supported
 118      * operations.
 119      *
 120      * <p> Server-socket channels only support the accepting of new
 121      * connections, so this method returns {@link SelectionKey#OP_ACCEPT}.
 122      * </p>
 123      *
 124      * @return  The valid-operation set
 125      */
 126     public final int validOps() {
 127         return SelectionKey.OP_ACCEPT;
 128     }
 129 
 130 
 131     // -- ServerSocket-specific operations --
 132 
 133     /**
 134      * Binds the channel's socket to a local address and configures the socket
 135      * to listen for connections.
 136      *
 137      * <p> An invocation of this method is equivalent to the following:
 138      * <blockquote><pre>
 139      * bind(local, 0);
 140      * </pre></blockquote>
 141      *
 142      * @param   local
 143      *          The local address to bind the socket, or {@code null} to bind
 144      *          to an automatically assigned socket address
 145      *
 146      * @return  This channel
 147      *
 148      * @throws  AlreadyBoundException               {@inheritDoc}
 149      * @throws  UnsupportedAddressTypeException     {@inheritDoc}
 150      * @throws  ClosedChannelException              {@inheritDoc}
 151      * @throws  IOException                         {@inheritDoc}
 152      * @throws  SecurityException
 153      *          If a security manager has been installed and its {@link
 154      *          SecurityManager#checkListen checkListen} method denies the
 155      *          operation
 156      *
 157      * @since 1.7
 158      */
 159     public final ServerSocketChannel bind(SocketAddress local)
 160         throws IOException
 161     {
 162         return bind(local, 0);
 163     }
 164 
 165     /**
 166      * Binds the channel's socket to a local address and configures the socket to
 167      * listen for connections.
 168      *
 169      * <p> This method is used to establish an association between the socket and
 170      * a local address. Once an association is established then the socket remains
 171      * bound until the channel is closed.
 172      *
 173      * <p> The {@code backlog} parameter is the maximum number of pending
 174      * connections on the socket. Its exact semantics are implementation specific.
 175      * In particular, an implementation may impose a maximum length or may choose
 176      * to ignore the parameter altogther. If the {@code backlog} parameter has
 177      * the value {@code 0}, or a negative value, then an implementation specific
 178      * default is used.
 179      *
 180      * @param   local
 181      *          The address to bind the socket, or {@code null} to bind to an
 182      *          automatically assigned socket address
 183      * @param   backlog
 184      *          The maximum number of pending connections
 185      *
 186      * @return  This channel
 187      *
 188      * @throws  AlreadyBoundException
 189      *          If the socket is already bound
 190      * @throws  UnsupportedAddressTypeException
 191      *          If the type of the given address is not supported
 192      * @throws  ClosedChannelException
 193      *          If this channel is closed
 194      * @throws  IOException
 195      *          If some other I/O error occurs
 196      * @throws  SecurityException
 197      *          If a security manager has been installed and its {@link
 198      *          SecurityManager#checkListen checkListen} method denies the
 199      *          operation
 200      *
 201      * @since 1.7
 202      */
 203     public abstract ServerSocketChannel bind(SocketAddress local, int backlog)
 204         throws IOException;
 205 
 206     /**
 207      * @throws  UnsupportedOperationException           {@inheritDoc}
 208      * @throws  IllegalArgumentException                {@inheritDoc}
 209      * @throws  ClosedChannelException                  {@inheritDoc}
 210      * @throws  IOException                             {@inheritDoc}
 211      *
 212      * @since 1.7
 213      */
 214     public abstract <T> ServerSocketChannel setOption(SocketOption<T> name, T value)
 215         throws IOException;
 216 
 217     /**
 218      * Retrieves a server socket associated with this channel.
 219      *
 220      * <p> The returned object will not declare any public methods that are not
 221      * declared in the {@link java.net.ServerSocket} class.  </p>
 222      *
 223      * @return  A server socket associated with this channel
 224      */
 225     public abstract ServerSocket socket();
 226 
 227     /**
 228      * Accepts a connection made to this channel's socket.
 229      *
 230      * <p> If this channel is in non-blocking mode then this method will
 231      * immediately return {@code null} if there are no pending connections.
 232      * Otherwise it will block indefinitely until a new connection is available
 233      * or an I/O error occurs.
 234      *
 235      * <p> The socket channel returned by this method, if any, will be in
 236      * blocking mode regardless of the blocking mode of this channel.
 237      *
 238      * <p> This method performs exactly the same security checks as the {@link
 239      * java.net.ServerSocket#accept accept} method of the {@link
 240      * java.net.ServerSocket} class.  That is, if a security manager has been
 241      * installed then for each new connection this method verifies that the
 242      * address and port number of the connection's remote endpoint are
 243      * permitted by the security manager's {@link
 244      * java.lang.SecurityManager#checkAccept checkAccept} method.  </p>
 245      *
 246      * @return  The socket channel for the new connection,
 247      *          or {@code null} if this channel is in non-blocking mode
 248      *          and no connection is available to be accepted
 249      *
 250      * @throws  ClosedChannelException
 251      *          If this channel is closed
 252      *
 253      * @throws  AsynchronousCloseException
 254      *          If another thread closes this channel
 255      *          while the accept operation is in progress
 256      *
 257      * @throws  ClosedByInterruptException
 258      *          If another thread interrupts the current thread
 259      *          while the accept operation is in progress, thereby
 260      *          closing the channel and setting the current thread's
 261      *          interrupt status
 262      *
 263      * @throws  NotYetBoundException
 264      *          If this channel's socket has not yet been bound
 265      *
 266      * @throws  SecurityException
 267      *          If a security manager has been installed
 268      *          and it does not permit access to the remote endpoint
 269      *          of the new connection
 270      *
 271      * @throws  IOException
 272      *          If some other I/O error occurs
 273      */
 274     public abstract SocketChannel accept() throws IOException;
 275 
 276     /**
 277      * {@inheritDoc}
 278      * <p>
 279      * If there is a security manager set, its {@code checkConnect} method is
 280      * called with the local address and {@code -1} as its arguments to see
 281      * if the operation is allowed. If the operation is not allowed,
 282      * a {@code SocketAddress} representing the
 283      * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
 284      * local port of the channel's socket is returned.
 285      *
 286      * @return  The {@code SocketAddress} that the socket is bound to, or the
 287      *          {@code SocketAddress} representing the loopback address if
 288      *          denied by the security manager, or {@code null} if the
 289      *          channel's socket is not bound
 290      *
 291      * @throws  ClosedChannelException     {@inheritDoc}
 292      * @throws  IOException                {@inheritDoc}
 293      */
 294     @Override
 295     public abstract SocketAddress getLocalAddress() throws IOException;
 296 
 297 }