--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/com/sun/nio/sctp/SctpServerChannel.java Thu Apr 16 17:42:00 2009 +0100
@@ -0,0 +1,421 @@
+/*
+ * Copyright 2009 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+package com.sun.nio.sctp;
+
+import java.net.SocketAddress;
+import java.net.InetAddress;
+import java.io.IOException;
+import java.util.Set;
+import java.nio.channels.SelectionKey;
+import java.nio.channels.spi.SelectorProvider;
+import java.nio.channels.spi.AbstractSelectableChannel;
+
+/**
+ * A selectable channel for message-oriented listening SCTP sockets.
+ *
+ * <p> An {@code SCTPServerChannel} is created by invoking the
+ * {@link #open open} method of this class. A newly-created SCTP server
+ * channel is open but not yet bound. An attempt to invoke the
+ * {@link #accept accept} method of an unbound channel will cause the
+ * {@link java.nio.channels.NotYetBoundException} to be thrown. An SCTP server
+ * channel can be bound by invoking one of the
+ * {@link #bind(java.net.SocketAddress,int) bind} methods defined by this class.
+ *
+ * <p> Socket options are configured using the
+ * {@link #setOption(SctpSocketOption,Object) setOption} method. SCTP server socket
+ * channels support the following options:
+ * <blockquote>
+ * <table border>
+ * <tr>
+ * <th>Option Name</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td> {@link SctpStandardSocketOption#SCTP_INIT_MAXSTREAMS
+ * SCTP_INIT_MAXSTREAMS} </td>
+ * <td> The maximum number of streams requested by the local endpoint during
+ * association initialization </td>
+ * </tr>
+ * </table>
+ * </blockquote>
+ * Additional (implementation specific) options may also be supported. The list
+ * of options supported is obtained by invoking the {@link #supportedOptions()
+ * supportedOptions} method.
+ *
+ * <p>SCTP server channels are safe for use by multiple concurrent threads.
+ *
+ * @since 1.7
+ */
+public abstract class SctpServerChannel
+ extends AbstractSelectableChannel
+{
+ /**
+ * Initializes a new instance of this class.
+ *
+ * @param provider
+ * The selector provider for this channel
+ */
+ protected SctpServerChannel(SelectorProvider provider) {
+ super(provider);
+ }
+
+ /**
+ * Opens an SCTP server channel.
+ *
+ * <P> The new channel's socket is initially unbound; it must be bound
+ * to a specific address via one of its socket's {@link #bind bind}
+ * methods before associations can be accepted.
+ *
+ * @return A new SCTP server channel
+ *
+ * @throws UnsupportedOperationException
+ * If the SCTP protocol is not supported
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static SctpServerChannel open() throws
+ IOException {
+ return new sun.nio.ch.SctpServerChannelImpl((SelectorProvider)null);
+ }
+
+ /**
+ * Accepts an association on this channel's socket.
+ *
+ * <P> If this channel is in non-blocking mode then this method will
+ * immediately return {@code null} if there are no pending associations.
+ * Otherwise it will block indefinitely until a new association is
+ * available or an I/O error occurs.
+ *
+ * <P> The {@code SCTPChannel} returned by this method, if any, will be in
+ * blocking mode regardless of the blocking mode of this channel.
+ *
+ * <P> If a security manager has been installed then for each new
+ * association this method verifies that the address and port number of the
+ * assocaitions's remote peer are permitted by the security manager's {@link
+ * java.lang.SecurityManager#checkAccept(String,int) checkAccept} method.
+ *
+ * @return The SCTP channel for the new association, or {@code null}
+ * if this channel is in non-blocking mode and no association is
+ * available to be accepted
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws java.nio.channels.AsynchronousCloseException
+ * If another thread closes this channel
+ * while the accept operation is in progress
+ *
+ * @throws java.nio.channels.ClosedByInterruptException
+ * If another thread interrupts the current thread
+ * while the accept operation is in progress, thereby
+ * closing the channel and setting the current thread's
+ * interrupt status
+ *
+ * @throws java.nio.channels.NotYetBoundException
+ * If this channel's socket has not yet been bound
+ *
+ * @throws SecurityException
+ * If a security manager has been installed and it does not permit
+ * access to the remote peer of the new association
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract SctpChannel accept() throws IOException;
+
+ /**
+ * Binds the channel's socket to a local address and configures the socket
+ * to listen for associations.
+ *
+ * <P> This method works as if invoking it were equivalent to evaluating the
+ * expression:
+ * <blockquote><pre>
+ * bind(local, 0);
+ * </pre></blockquote>
+ *
+ * @param local
+ * The local address to bind the socket, or {@code null} to
+ * bind the socket to an automatically assigned socket address
+ *
+ * @return This channel
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws java.nio.channels.AlreadyBoundException
+ * If this channel is already bound
+ *
+ * @throws java.nio.channels.UnsupportedAddressTypeException
+ * If the type of the given address is not supported
+ *
+ * @throws SecurityException
+ * If a security manager has been installed and its {@link
+ * java.lang.SecurityManager#checkListen(int) checkListen} method
+ * denies the operation
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public final SctpServerChannel bind(SocketAddress local)
+ throws IOException {
+ return bind(local, 0);
+ }
+
+ /**
+ * Binds the channel's socket to a local address and configures the socket
+ * to listen for associations.
+ *
+ * <P> This method is used to establish a relationship between the socket
+ * and the local address. Once a relationship is established then
+ * the socket remains bound until the channel is closed. This relationship
+ * may not necesssarily be with the address {@code local} as it may be
+ * removed by {@link #unbindAddress unbindAddress}, but there will always be
+ * at least one local address bound to the channel's socket once an
+ * invocation of this method successfully completes.
+ *
+ * <P> Once the channel's socket has been successfully bound to a specific
+ * address, that is not automatically assigned, more addresses
+ * may be bound to it using {@link #bindAddress bindAddress}, or removed
+ * using {@link #unbindAddress unbindAddress}.
+ *
+ * <P> The backlog parameter is the maximum number of pending associations
+ * on the socket. Its exact semantics are implementation specific. An
+ * implementation may impose an implementation specific maximum length or
+ * may choose to ignore the parameter. If the backlog parameter has the
+ * value {@code 0}, or a negative value, then an implementation specific
+ * default is used.
+ *
+ * @param local
+ * The local address to bind the socket, or {@code null} to
+ * bind the socket to an automatically assigned socket address
+ *
+ * @param backlog
+ * The maximum number number of pending associations
+ *
+ * @return This channel
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws java.nio.channels.AlreadyBoundException
+ * If this channel is already bound
+ *
+ * @throws java.nio.channels.UnsupportedAddressTypeException
+ * If the type of the given address is not supported
+ *
+ * @throws SecurityException
+ * If a security manager has been installed and its {@link
+ * java.lang.SecurityManager#checkListen(int) checkListen} method
+ * denies the operation
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract SctpServerChannel bind(SocketAddress local,
+ int backlog)
+ throws IOException;
+
+ /**
+ * Adds the given address to the bound addresses for the channel's
+ * socket.
+ *
+ * <P> The given address must not be the {@link
+ * java.net.InetAddress#isAnyLocalAddress wildcard} address.
+ * The channel must be first bound using {@link #bind bind} before
+ * invoking this method, otherwise {@link
+ * java.nio.channels.NotYetBoundException} is thrown. The {@link #bind bind}
+ * method takes a {@code SocketAddress} as its argument which typically
+ * contains a port number as well as an address. Addresses subquently bound
+ * using this method are simply addresses as the SCTP port number remains
+ * the same for the lifetime of the channel.
+ *
+ * <P> New associations accepted after this method successfully completes
+ * will be associated with the given address.
+ *
+ * @param address
+ * The address to add to the bound addresses for the socket
+ *
+ * @return This channel
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws java.nio.channels.NotYetBoundException
+ * If this channel is not yet bound
+ *
+ * @throws java.nio.channels.AlreadyBoundException
+ * If this channel is already bound to the given address
+ *
+ * @throws IllegalArgumentException
+ * If address is {@code null} or the {@link
+ * java.net.InetAddress#isAnyLocalAddress wildcard} address
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract SctpServerChannel bindAddress(InetAddress address)
+ throws IOException;
+
+ /**
+ * Removes the given address from the bound addresses for the channel's
+ * socket.
+ *
+ * <P> The given address must not be the {@link
+ * java.net.InetAddress#isAnyLocalAddress wildcard} address.
+ * The channel must be first bound using {@link #bind bind} before
+ * invoking this method, otherwise
+ * {@link java.nio.channels.NotYetBoundException} is thrown.
+ * If this method is invoked on a channel that does not have
+ * {@code address} as one of its bound addresses, or that has only one
+ * local address bound to it, then this method throws {@link
+ * IllegalUnbindException}.
+ * The initial address that the channel's socket is bound to using
+ * {@link #bind bind} may be removed from the bound addresses for the
+ * channel's socket.
+ *
+ * <P> New associations accepted after this method successfully completes
+ * will not be associated with the given address.
+ *
+ * @param address
+ * The address to remove from the bound addresses for the socket
+ *
+ * @return This channel
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws java.nio.channels.NotYetBoundException
+ * If this channel is not yet bound
+ *
+ * @throws IllegalArgumentException
+ * If address is {@code null} or the {@link
+ * java.net.InetAddress#isAnyLocalAddress wildcard} address
+ *
+ * @throws IllegalUnbindException
+ * If the implementation does not support removing addresses from a
+ * listening socket, {@code address} is not bound to the channel's
+ * socket, or the channel has only one address bound to it
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract SctpServerChannel unbindAddress(InetAddress address)
+ throws IOException;
+
+ /**
+ * Returns all of the socket addresses to which this channel's socket is
+ * bound.
+ *
+ * @return All the socket addresses that this channel's socket is
+ * bound to, or an empty {@code Set} if the channel's socket is not
+ * bound
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If the channel is closed
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public abstract Set<SocketAddress> getAllLocalAddresses()
+ throws IOException;
+
+ /**
+ * Returns the value of a socket option.
+ *
+ * @param name
+ * The socket option
+ *
+ * @return The value of the socket option. A value of {@code null} may be
+ * a valid value for some socket options.
+ *
+ * @throws UnsupportedOperationException
+ * If the socket option is not supported by this channel
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ *
+ * @see SctpStandardSocketOption
+ */
+ public abstract <T> T getOption(SctpSocketOption<T> name) throws IOException;
+
+ /**
+ * Sets the value of a socket option.
+ *
+ * @param name
+ * The socket option
+ *
+ * @param value
+ * The value of the socket option. A value of {@code null} may be
+ * a valid value for some socket options.
+ *
+ * @return This channel
+ *
+ * @throws UnsupportedOperationException
+ * If the socket option is not supported by this channel
+ *
+ * @throws IllegalArgumentException
+ * If the value is not a valid value for this socket option
+ *
+ * @throws java.nio.channels.ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ *
+ * @see SctpStandardSocketOption
+ */
+ public abstract <T> SctpServerChannel setOption(SctpSocketOption<T> name,
+ T value)
+ throws IOException;
+
+ /**
+ * Returns a set of the socket options supported by this channel.
+ *
+ * <P> This method will continue to return the set of options even after the
+ * channel has been closed.
+ *
+ * @return A set of the socket options supported by this channel
+ */
+ public abstract Set<SctpSocketOption<?>> supportedOptions();
+
+ /**
+ * Returns an operation set identifying this channel's supported
+ * operations.
+ *
+ * <P> SCTP server channels only support the accepting of new
+ * associations, so this method returns
+ * {@link java.nio.channels.SelectionKey#OP_ACCEPT}.
+ *
+ * @return The valid-operation set
+ */
+ @Override
+ public final int validOps() {
+ return SelectionKey.OP_ACCEPT;
+ }
+}