1 /*

     2  * Copyright (c) 2000, 2017, 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 scope="col">Option Name</th>

    54  *     <th scope="col">Description</th>

    55  *   </tr>

    56  * </thead>

    57  * <tbody>

    58  *   <tr>

    59  *     <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>

    60  *     <td> The size of the socket receive buffer </td>

    61  *   </tr>

    62  *   <tr>

    63  *     <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>

    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 }