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 }