1 /*

     2  * Copyright (c) 2009, 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 package com.sun.nio.sctp;

    26 

    27 import java.net.SocketAddress;

    28 import java.net.InetAddress;

    29 import java.io.IOException;

    30 import java.util.Set;

    31 import java.nio.channels.SelectionKey;

    32 import java.nio.channels.spi.SelectorProvider;

    33 import java.nio.channels.spi.AbstractSelectableChannel;

    34 

    35 /**

    36  * A selectable channel for message-oriented listening SCTP sockets.

    37  *

    38  * <p> An {@code SCTPServerChannel} is created by invoking the

    39  * {@link #open open} method of this class. A newly-created SCTP server

    40  * channel is open but not yet bound. An attempt to invoke the

    41  * {@link #accept accept} method of an unbound channel will cause the

    42  * {@link java.nio.channels.NotYetBoundException} to be thrown. An SCTP server

    43  * 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

    47  * {@link #setOption(SctpSocketOption,Object) setOption} method. SCTP server socket

    48  * channels support the following options:

    49  * <blockquote>

    50  * <table class="striped">

    51  *   <caption style="display:none">Socket options</caption>

    52  *   <thead>

    53  *   <tr>

    54  *     <th scope="col">Option Name</th>

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

    56  *   </tr>

    57  *   </thead>

    58  *   <tbody>

    59  *   <tr>

    60  *     <th scope="row"> {@link SctpStandardSocketOptions#SCTP_INIT_MAXSTREAMS

    61  *                                          SCTP_INIT_MAXSTREAMS} </th>

    62  *     <td> The maximum number of streams requested by the local endpoint during

    63  *          association initialization </td>

    64  *   </tr>

    65  *   </tbody>

    66  * </table>

    67  * </blockquote>

    68  * Additional (implementation specific) options may also be supported. The list

    69  * of options supported is obtained by invoking the {@link #supportedOptions()

    70  * supportedOptions} method.

    71  *

    72  * <p>SCTP server channels are safe for use by multiple concurrent threads.

    73  *

    74  * @since 1.7

    75  */

    76 public abstract class SctpServerChannel

    77     extends AbstractSelectableChannel

    78 {

    79     /**

    80      * Initializes a new instance of this class.

    81      *

    82      * @param  provider

    83      *         The selector provider for this channel

    84      */

    85     protected SctpServerChannel(SelectorProvider provider) {

    86         super(provider);

    87     }

    88 

    89     /**

    90      * Opens an SCTP server channel.

    91      *

    92      * <P> The new channel's socket is initially unbound; it must be bound

    93      * to a specific address via one of its socket's {@link #bind bind}

    94      * methods before associations can be accepted.

    95      *

    96      * @return  A new SCTP server channel

    97      *

    98      * @throws  UnsupportedOperationException

    99      *          If the SCTP protocol is not supported

   100      *

   101      * @throws  IOException

   102      *          If an I/O error occurs

   103      */

   104     public static SctpServerChannel open() throws

   105         IOException {

   106         return new sun.nio.ch.sctp.SctpServerChannelImpl((SelectorProvider)null);

   107     }

   108 

   109     /**

   110      * Accepts an association on this channel's socket.

   111      *

   112      * <P> If this channel is in non-blocking mode then this method will

   113      * immediately return {@code null} if there are no pending associations.

   114      * Otherwise it will block indefinitely until a new association is

   115      * available or an I/O error occurs.

   116      *

   117      * <P> The {@code SCTPChannel} returned by this method, if any, will be in

   118      *  blocking mode regardless of the blocking mode of this channel.

   119      *

   120      * <P> If a security manager has been installed then for each new

   121      * association this method verifies that the address and port number of the

   122      * assocaitions's remote peer are permitted by the security manager's {@link

   123      * java.lang.SecurityManager#checkAccept(String,int) checkAccept} method.

   124      *

   125      * @return  The SCTP channel for the new association, or {@code null}

   126      *          if this channel is in non-blocking mode and no association is

   127      *          available to be accepted

   128      *

   129      * @throws  java.nio.channels.ClosedChannelException

   130      *          If this channel is closed

   131      *

   132      * @throws  java.nio.channels.AsynchronousCloseException

   133      *          If another thread closes this channel

   134      *          while the accept operation is in progress

   135      *

   136      * @throws  java.nio.channels.ClosedByInterruptException

   137      *          If another thread interrupts the current thread

   138      *          while the accept operation is in progress, thereby

   139      *          closing the channel and setting the current thread's

   140      *          interrupt status

   141      *

   142      * @throws  java.nio.channels.NotYetBoundException

   143      *          If this channel's socket has not yet been bound

   144      *

   145      * @throws  SecurityException

   146      *          If a security manager has been installed and it does not permit

   147      *          access to the remote peer of the new association

   148      *

   149      * @throws  IOException

   150      *          If some other I/O error occurs

   151      */

   152     public abstract SctpChannel accept() throws IOException;

   153 

   154     /**

   155      * Binds the channel's socket to a local address and configures the socket

   156      * to listen for associations.

   157      *

   158      * <P> This method works as if invoking it were equivalent to evaluating the

   159      * expression:

   160      * <blockquote><pre>

   161      * bind(local, 0);

   162      * </pre></blockquote>

   163      *

   164      * @param  local

   165      *         The local address to bind the socket, or {@code null} to

   166      *         bind the socket to an automatically assigned socket address

   167      *

   168      * @return  This channel

   169      *

   170      * @throws  java.nio.channels.ClosedChannelException

   171      *          If this channel is closed

   172      *

   173      * @throws  java.nio.channels.AlreadyBoundException

   174      *          If this channel is already bound

   175      *

   176      * @throws  java.nio.channels.UnsupportedAddressTypeException

   177      *          If the type of the given address is not supported

   178      *

   179      * @throws  SecurityException

   180      *          If a security manager has been installed and its {@link

   181      *          java.lang.SecurityManager#checkListen(int) checkListen} method

   182      *          denies the operation

   183      *

   184      * @throws  IOException

   185      *          If some other I/O error occurs

   186      */

   187     public final SctpServerChannel bind(SocketAddress local)

   188         throws IOException {

   189         return bind(local, 0);

   190     }

   191 

   192     /**

   193      * Binds the channel's socket to a local address and configures the socket

   194      * to listen for associations.

   195      *

   196      * <P> This method is used to establish a relationship between the socket

   197      * and the local address. Once a relationship is established then

   198      * the socket remains bound until the channel is closed. This relationship

   199      * may not necesssarily be with the address {@code local} as it may be

   200      * removed by {@link #unbindAddress unbindAddress}, but there will always be

   201      * at least one local address bound to the channel's socket once an

   202      * invocation of this method successfully completes.

   203      *

   204      * <P> Once the channel's socket has been successfully bound to a specific

   205      * address, that is not automatically assigned, more addresses

   206      * may be bound to it using {@link #bindAddress bindAddress}, or removed

   207      * using {@link #unbindAddress unbindAddress}.

   208      *

   209      * <P> The backlog parameter is the maximum number of pending associations

   210      * on the socket. Its exact semantics are implementation specific. An

   211      * implementation may impose an implementation specific maximum length or

   212      * may choose to ignore the parameter. If the backlog parameter has the

   213      * value {@code 0}, or a negative value, then an implementation specific

   214      * default is used.

   215      *

   216      * @param  local

   217      *         The local address to bind the socket, or {@code null} to

   218      *         bind the socket to an automatically assigned socket address

   219      *

   220      * @param  backlog

   221      *         The maximum number of pending associations

   222      *

   223      * @return  This channel

   224      *

   225      * @throws  java.nio.channels.ClosedChannelException

   226      *          If this channel is closed

   227      *

   228      * @throws  java.nio.channels.AlreadyBoundException

   229      *          If this channel is already bound

   230      *

   231      * @throws  java.nio.channels.UnsupportedAddressTypeException

   232      *          If the type of the given address is not supported

   233      *

   234      * @throws  SecurityException

   235      *          If a security manager has been installed and its {@link

   236      *          java.lang.SecurityManager#checkListen(int) checkListen} method

   237      *          denies the operation

   238      *

   239      * @throws  IOException

   240      *          If some other I/O error occurs

   241      */

   242     public abstract SctpServerChannel bind(SocketAddress local,

   243                                            int backlog)

   244         throws IOException;

   245 

   246     /**

   247      * Adds the given address to the bound addresses for the channel's

   248      * socket.

   249      *

   250      * <P> The given address must not be the {@link

   251      * java.net.InetAddress#isAnyLocalAddress wildcard} address.

   252      * The channel must be first bound using {@link #bind bind} before

   253      * invoking this method, otherwise {@link

   254      * java.nio.channels.NotYetBoundException} is thrown. The {@link #bind bind}

   255      * method takes a {@code SocketAddress} as its argument which typically

   256      * contains a port number as well as an address. Addresses subquently bound

   257      * using this method are simply addresses as the SCTP port number remains

   258      * the same for the lifetime of the channel.

   259      *

   260      * <P> New associations accepted after this method successfully completes

   261      * will be associated with the given address.

   262      *

   263      * @param  address

   264      *         The address to add to the bound addresses for the socket

   265      *

   266      * @return  This channel

   267      *

   268      * @throws  java.nio.channels.ClosedChannelException

   269      *          If this channel is closed

   270      *

   271      * @throws  java.nio.channels.NotYetBoundException

   272      *          If this channel is not yet bound

   273      *

   274      * @throws  java.nio.channels.AlreadyBoundException

   275      *          If this channel is already bound to the given address

   276      *

   277      * @throws  IllegalArgumentException

   278      *          If address is {@code null} or the {@link

   279      *          java.net.InetAddress#isAnyLocalAddress wildcard} address

   280      *

   281      * @throws  IOException

   282      *          If some other I/O error occurs

   283      */

   284     public abstract SctpServerChannel bindAddress(InetAddress address)

   285          throws IOException;

   286 

   287     /**

   288      * Removes the given address from the bound addresses for the channel's

   289      * socket.

   290      *

   291      * <P> The given address must not be the {@link

   292      * java.net.InetAddress#isAnyLocalAddress wildcard} address.

   293      * The channel must be first bound using {@link #bind bind} before

   294      * invoking this method, otherwise

   295      * {@link java.nio.channels.NotYetBoundException} is thrown.

   296      * If this method is invoked on a channel that does not have

   297      * {@code address} as one of its bound addresses, or that has only one

   298      * local address bound to it, then this method throws {@link

   299      * IllegalUnbindException}.

   300      * The initial address that the channel's socket is bound to using

   301      * {@link #bind bind} may be removed from the bound addresses for the

   302      * channel's socket.

   303      *

   304      * <P> New associations accepted after this method successfully completes

   305      * will not be associated with the given address.

   306      *

   307      * @param  address

   308      *         The address to remove from the bound addresses for the socket

   309      *

   310      * @return  This channel

   311      *

   312      * @throws  java.nio.channels.ClosedChannelException

   313      *          If this channel is closed

   314      *

   315      * @throws  java.nio.channels.NotYetBoundException

   316      *          If this channel is not yet bound

   317      *

   318      * @throws  IllegalArgumentException

   319      *          If address is {@code null} or the {@link

   320      *          java.net.InetAddress#isAnyLocalAddress wildcard} address

   321      *

   322      * @throws  IllegalUnbindException

   323      *          If the implementation does not support removing addresses from a

   324      *          listening socket, {@code address} is not bound to the channel's

   325      *          socket, or the channel has only one address bound to it

   326      *

   327      * @throws  IOException

   328      *          If some other I/O error occurs

   329      */

   330     public abstract SctpServerChannel unbindAddress(InetAddress address)

   331          throws IOException;

   332 

   333     /**

   334      * Returns all of the socket addresses to which this channel's socket is

   335      * bound.

   336      *

   337      * @return  All the socket addresses that this channel's socket is

   338      *          bound to, or an empty {@code Set} if the channel's socket is not

   339      *          bound

   340      *

   341      * @throws  java.nio.channels.ClosedChannelException

   342      *          If the channel is closed

   343      *

   344      * @throws  IOException

   345      *          If an I/O error occurs

   346      */

   347     public abstract Set<SocketAddress> getAllLocalAddresses()

   348         throws IOException;

   349 

   350     /**

   351      * Returns the value of a socket option.

   352      *

   353      * @param   <T>

   354      *          The type of the socket option value

   355      *

   356      * @param   name

   357      *          The socket option

   358      *

   359      * @return  The value of the socket option. A value of {@code null} may be

   360      *          a valid value for some socket options.

   361      *

   362      * @throws  UnsupportedOperationException

   363      *          If the socket option is not supported by this channel

   364      *

   365      * @throws  java.nio.channels.ClosedChannelException

   366      *          If this channel is closed

   367      *

   368      * @throws  IOException

   369      *          If an I/O error occurs

   370      *

   371      * @see SctpStandardSocketOptions

   372      */

   373     public abstract <T> T getOption(SctpSocketOption<T> name) throws IOException;

   374 

   375     /**

   376      * Sets the value of a socket option.

   377      *

   378      * @param   <T>

   379      *          The type of the socket option value

   380      *

   381      * @param   name

   382      *          The socket option

   383      *

   384      * @param   value

   385      *          The value of the socket option. A value of {@code null} may be

   386      *          a valid value for some socket options.

   387      *

   388      * @return  This channel

   389      *

   390      * @throws  UnsupportedOperationException

   391      *          If the socket option is not supported by this channel

   392      *

   393      * @throws  IllegalArgumentException

   394      *          If the value is not a valid value for this socket option

   395      *

   396      * @throws  java.nio.channels.ClosedChannelException

   397      *          If this channel is closed

   398      *

   399      * @throws  IOException

   400      *          If an I/O error occurs

   401      *

   402      * @see SctpStandardSocketOptions

   403      */

   404     public abstract <T> SctpServerChannel setOption(SctpSocketOption<T> name,

   405                                                     T value)

   406         throws IOException;

   407 

   408     /**

   409      * Returns a set of the socket options supported by this channel.

   410      *

   411      * <P> This method will continue to return the set of options even after the

   412      * channel has been closed.

   413      *

   414      * @return  A set of the socket options supported by this channel

   415      */

   416     public abstract Set<SctpSocketOption<?>> supportedOptions();

   417 

   418     /**

   419      * Returns an operation set identifying this channel's supported

   420      * operations.

   421      *

   422      * <P> SCTP server channels only support the accepting of new

   423      * associations, so this method returns

   424      * {@link java.nio.channels.SelectionKey#OP_ACCEPT}.

   425      *

   426      * @return  The valid-operation set

   427      */

   428     @Override

   429     public final int validOps() {

   430         return SelectionKey.OP_ACCEPT;

   431     }

   432 }