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><caption style="display:none">Socket options</caption>
  51  *   <tr>
  52  *     <th>Option Name</th>
  53  *     <th>Description</th>
  54  *   </tr>
  55  *   <tr>
  56  *     <td> {@link SctpStandardSocketOptions#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.sctp.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 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   <T>
 349      *          The type of the socket option value
 350      *
 351      * @param   name
 352      *          The socket option
 353      *
 354      * @return  The value of the socket option. A value of {@code null} may be
 355      *          a valid value for some socket options.
 356      *
 357      * @throws  UnsupportedOperationException
 358      *          If the socket option is not supported by this channel
 359      *
 360      * @throws  java.nio.channels.ClosedChannelException
 361      *          If this channel is closed
 362      *
 363      * @throws  IOException
 364      *          If an I/O error occurs
 365      *
 366      * @see SctpStandardSocketOptions
 367      */
 368     public abstract <T> T getOption(SctpSocketOption<T> name) throws IOException;
 369 
 370     /**
 371      * Sets the value of a socket option.
 372      *
 373      * @param   <T>
 374      *          The type of the socket option value
 375      *
 376      * @param   name
 377      *          The socket option
 378      *
 379      * @param   value
 380      *          The value of the socket option. A value of {@code null} may be
 381      *          a valid value for some socket options.
 382      *
 383      * @return  This channel
 384      *
 385      * @throws  UnsupportedOperationException
 386      *          If the socket option is not supported by this channel
 387      *
 388      * @throws  IllegalArgumentException
 389      *          If the value is not a valid value for this socket option
 390      *
 391      * @throws  java.nio.channels.ClosedChannelException
 392      *          If this channel is closed
 393      *
 394      * @throws  IOException
 395      *          If an I/O error occurs
 396      *
 397      * @see SctpStandardSocketOptions
 398      */
 399     public abstract <T> SctpServerChannel setOption(SctpSocketOption<T> name,
 400                                                     T value)
 401         throws IOException;
 402 
 403     /**
 404      * Returns a set of the socket options supported by this channel.
 405      *
 406      * <P> This method will continue to return the set of options even after the
 407      * channel has been closed.
 408      *
 409      * @return  A set of the socket options supported by this channel
 410      */
 411     public abstract Set<SctpSocketOption<?>> supportedOptions();
 412 
 413     /**
 414      * Returns an operation set identifying this channel's supported
 415      * operations.
 416      *
 417      * <P> SCTP server channels only support the accepting of new
 418      * associations, so this method returns
 419      * {@link java.nio.channels.SelectionKey#OP_ACCEPT}.
 420      *
 421      * @return  The valid-operation set
 422      */
 423     @Override
 424     public final int validOps() {
 425         return SelectionKey.OP_ACCEPT;
 426     }
 427 }