1 /*

     2  * Copyright 2009 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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 border>

    51  *   <tr>

    52  *     <th>Option Name</th>

    53  *     <th>Description</th>

    54  *   </tr>

    55  *   <tr>

    56  *     <td> {@link SctpStandardSocketOption#SCTP_INIT_MAXSTREAMS

    57  *                                          SCTP_INIT_MAXSTREAMS} </td>

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

    59  *          association initialization </td>

    60  *   </tr>

    61  * </table>

    62  * </blockquote>

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

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

    65  * supportedOptions} method.

    66  *

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

    68  *

    69  * @since 1.7

    70  */

    71 public abstract class SctpServerChannel

    72     extends AbstractSelectableChannel

    73 {

    74     /**

    75      * Initializes a new instance of this class.

    76      *

    77      * @param  provider

    78      *         The selector provider for this channel

    79      */

    80     protected SctpServerChannel(SelectorProvider provider) {

    81         super(provider);

    82     }

    83 

    84     /**

    85      * Opens an SCTP server channel.

    86      *

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

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

    89      * methods before associations can be accepted.

    90      *

    91      * @return  A new SCTP server channel

    92      *

    93      * @throws  UnsupportedOperationException

    94      *          If the SCTP protocol is not supported

    95      *

    96      * @throws  IOException

    97      *          If an I/O error occurs

    98      */

    99     public static SctpServerChannel open() throws

   100         IOException {

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

   102     }

   103 

   104     /**

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

   106      *

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

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

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

   110      * available or an I/O error occurs.

   111      *

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

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

   114      *

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

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

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

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

   119      *

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

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

   122      *          available to be accepted

   123      *

   124      * @throws  java.nio.channels.ClosedChannelException

   125      *          If this channel is closed

   126      *

   127      * @throws  java.nio.channels.AsynchronousCloseException

   128      *          If another thread closes this channel

   129      *          while the accept operation is in progress

   130      *

   131      * @throws  java.nio.channels.ClosedByInterruptException

   132      *          If another thread interrupts the current thread

   133      *          while the accept operation is in progress, thereby

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

   135      *          interrupt status

   136      *

   137      * @throws  java.nio.channels.NotYetBoundException

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

   139      *

   140      * @throws  SecurityException

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

   142      *          access to the remote peer of the new association

   143      *

   144      * @throws  IOException

   145      *          If some other I/O error occurs

   146      */

   147     public abstract SctpChannel accept() throws IOException;

   148 

   149     /**

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

   151      * to listen for associations.

   152      *

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

   154      * expression:

   155      * <blockquote><pre>

   156      * bind(local, 0);

   157      * </pre></blockquote>

   158      *

   159      * @param  local

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

   161      *         bind the socket to an automatically assigned socket address

   162      *

   163      * @return  This channel

   164      *

   165      * @throws  java.nio.channels.ClosedChannelException

   166      *          If this channel is closed

   167      *

   168      * @throws  java.nio.channels.AlreadyBoundException

   169      *          If this channel is already bound

   170      *

   171      * @throws  java.nio.channels.UnsupportedAddressTypeException

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

   173      *

   174      * @throws  SecurityException

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

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

   177      *          denies the operation

   178      *

   179      * @throws  IOException

   180      *          If some other I/O error occurs

   181      */

   182     public final SctpServerChannel bind(SocketAddress local)

   183         throws IOException {

   184         return bind(local, 0);

   185     }

   186 

   187     /**

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

   189      * to listen for associations.

   190      *

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

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

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

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

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

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

   197      * invocation of this method successfully completes.

   198      *

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

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

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

   202      * using {@link #unbindAddress unbindAddress}.

   203      *

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

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

   206      * implementation may impose an implementation specific maximum length or

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

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

   209      * default is used.

   210      *

   211      * @param  local

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

   213      *         bind the socket to an automatically assigned socket address

   214      *

   215      * @param  backlog

   216      *         The maximum number number of pending associations

   217      *

   218      * @return  This channel

   219      *

   220      * @throws  java.nio.channels.ClosedChannelException

   221      *          If this channel is closed

   222      *

   223      * @throws  java.nio.channels.AlreadyBoundException

   224      *          If this channel is already bound

   225      *

   226      * @throws  java.nio.channels.UnsupportedAddressTypeException

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

   228      *

   229      * @throws  SecurityException

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

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

   232      *          denies the operation

   233      *

   234      * @throws  IOException

   235      *          If some other I/O error occurs

   236      */

   237     public abstract SctpServerChannel bind(SocketAddress local,

   238                                            int backlog)

   239         throws IOException;

   240 

   241     /**

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

   243      * socket.

   244      *

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

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

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

   248      * invoking this method, otherwise {@link

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

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

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

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

   253      * the same for the lifetime of the channel.

   254      *

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

   256      * will be associated with the given address.

   257      *

   258      * @param  address

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

   260      *

   261      * @return  This channel

   262      *

   263      * @throws  java.nio.channels.ClosedChannelException

   264      *          If this channel is closed

   265      *

   266      * @throws  java.nio.channels.NotYetBoundException

   267      *          If this channel is not yet bound

   268      *

   269      * @throws  java.nio.channels.AlreadyBoundException

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

   271      *

   272      * @throws  IllegalArgumentException

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

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

   275      *

   276      * @throws  IOException

   277      *          If some other I/O error occurs

   278      */

   279     public abstract SctpServerChannel bindAddress(InetAddress address)

   280          throws IOException;

   281 

   282     /**

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

   284      * socket.

   285      *

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

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

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

   289      * invoking this method, otherwise

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

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

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

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

   294      * IllegalUnbindException}.

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

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

   297      * channel's socket.

   298      *

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

   300      * will not be associated with the given address.

   301      *

   302      * @param  address

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

   304      *

   305      * @return  This channel

   306      *

   307      * @throws  java.nio.channels.ClosedChannelException

   308      *          If this channel is closed

   309      *

   310      * @throws  java.nio.channels.NotYetBoundException

   311      *          If this channel is not yet bound

   312      *

   313      * @throws  IllegalArgumentException

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

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

   316      *

   317      * @throws  IllegalUnbindException

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

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

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

   321      *

   322      * @throws  IOException

   323      *          If some other I/O error occurs

   324      */

   325     public abstract SctpServerChannel unbindAddress(InetAddress address)

   326          throws IOException;

   327 

   328     /**

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

   330      * bound.

   331      *

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

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

   334      *          bound

   335      *

   336      * @throws  java.nio.channels.ClosedChannelException

   337      *          If the channel is closed

   338      *

   339      * @throws  IOException

   340      *          If an I/O error occurs

   341      */

   342     public abstract Set<SocketAddress> getAllLocalAddresses()

   343         throws IOException;

   344 

   345     /**

   346      * Returns the value of a socket option.

   347      *

   348      * @param   name

   349      *          The socket option

   350      *

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

   352      *          a valid value for some socket options.

   353      *

   354      * @throws  UnsupportedOperationException

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

   356      *

   357      * @throws  java.nio.channels.ClosedChannelException

   358      *          If this channel is closed

   359      *

   360      * @throws  IOException

   361      *          If an I/O error occurs

   362      *

   363      * @see SctpStandardSocketOption

   364      */

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

   366 

   367     /**

   368      * Sets the value of a socket option.

   369      *

   370      * @param   name

   371      *          The socket option

   372      *

   373      * @param   value

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

   375      *          a valid value for some socket options.

   376      *

   377      * @return  This channel

   378      *

   379      * @throws  UnsupportedOperationException

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

   381      *

   382      * @throws  IllegalArgumentException

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

   384      *

   385      * @throws  java.nio.channels.ClosedChannelException

   386      *          If this channel is closed

   387      *

   388      * @throws  IOException

   389      *          If an I/O error occurs

   390      *

   391      * @see SctpStandardSocketOption

   392      */

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

   394                                                     T value)

   395         throws IOException;

   396 

   397     /**

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

   399      *

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

   401      * channel has been closed.

   402      *

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

   404      */

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

   406 

   407     /**

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

   409      * operations.

   410      *

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

   412      * associations, so this method returns

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

   414      *

   415      * @return  The valid-operation set

   416      */

   417     @Override

   418     public final int validOps() {

   419         return SelectionKey.OP_ACCEPT;

   420     }

   421 }