/*

 * 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.ByteBuffer;

import java.nio.channels.spi.AbstractSelectableChannel;

import java.nio.channels.spi.SelectorProvider;

import java.nio.channels.ClosedChannelException;

import java.nio.channels.SelectionKey;

/**

 * A selectable channel for message-oriented connected SCTP sockets.

 *

 * <P> An SCTP channel can only control one SCTP association.

 * An {@code SCTPChannel} is created by invoking one of the

 * {@link #open open} methods of this class. A newly-created channel is open but

 * not yet connected, that is, there is no association setup with a remote peer.

 * An attempt to invoke an I/O operation upon an unconnected

 * channel will cause a {@link java.nio.channels.NotYetConnectedException} to be

 * thrown. An association can be setup by connecting the channel using one of

 * its {@link #connect connect} methods. Once connected, the channel remains

 * connected until it is closed. Whether or not a channel is connected may be

 * determined by invoking {@link #getRemoteAddresses getRemoteAddresses}.

 *

 * <p> SCTP channels support <i>non-blocking connection:</i>&nbsp;A

 * channel may be created and the process of establishing the link to

 * the remote socket may be initiated via the {@link #connect connect} method

 * for later completion by the {@link #finishConnect finishConnect} method.

 * Whether or not a connection operation is in progress may be determined by

 * invoking the {@link #isConnectionPending isConnectionPending} method.

 *

 * <p> Socket options are configured using the

 * {@link #setOption(SctpSocketOption,Object) setOption} method. An SCTP

 * channel support the following options:

 * <blockquote>

 * <table border>

 *   <tr>

 *     <th>Option Name</th>

 *     <th>Description</th>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_DISABLE_FRAGMENTS

 *                                          SCTP_DISABLE_FRAGMENTS} </td>

 *     <td> Enables or disables message fragmentation </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_EXPLICIT_COMPLETE

 *                                          SCTP_EXPLICIT_COMPLETE} </td>

 *     <td> Enables or disables explicit message completion </td>

 *   </tr>

 *    <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_FRAGMENT_INTERLEAVE

 *                                          SCTP_FRAGMENT_INTERLEAVE} </td>

 *     <td> Controls how the presentation of messages occur for the message

 *          receiver </td>

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

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_NODELAY SCTP_NODELAY} </td>

 *     <td> Enables or disable a Nagle-like algorithm </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_PRIMARY_ADDR

 *                                          SCTP_PRIMARY_ADDR} </td>

 *     <td> Requests that the local SCTP stack use the given peer address as the

 *          association primary </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SCTP_SET_PEER_PRIMARY_ADDR

 *                                          SCTP_SET_PEER_PRIMARY_ADDR} </td>

 *     <td> Requests that the peer mark the enclosed address as the association

 *          primary </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SO_SNDBUF

 *                                          SO_SNDBUF} </td>

 *     <td> The size of the socket send buffer </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SO_RCVBUF

 *                                          SO_RCVBUF} </td>

 *     <td> The size of the socket receive buffer </td>

 *   </tr>

 *   <tr>

 *     <td> {@link SctpStandardSocketOption#SO_LINGER

 *                                          SO_LINGER} </td>

 *     <td> Linger on close if data is present (when configured in blocking mode

 *          only) </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 channels are safe for use by multiple concurrent threads.

 * They support concurrent reading and writing, though at most one thread may be

 * reading and at most one thread may be writing at any given time. The

 * {@link #connect connect} and {@link #finishConnect

 * finishConnect} methods are mutually synchronized against each other, and

 * an attempt to initiate a send or receive operation while an invocation of one

 * of these methods is in progress will block until that invocation is complete.

 *

 * @since 1.7

 */

public abstract class SctpChannel

    extends AbstractSelectableChannel

{

    /**

     * Initializes a new instance of this class.

     *

     * @param  provider

     *         The selector provider for this channel

     */

    protected SctpChannel(SelectorProvider provider) {

        super(provider);

    }

    /**

     * Opens an SCTP channel.

     *

     * <P> The new channel is unbound and unconnected.

     *

     * @return  A new SCTP channel

     *

     * @throws  UnsupportedOperationException

     *          If the SCTP protocol is not supported

     *

     * @throws  IOException

     *          If an I/O error occurs

     */

    public static SctpChannel open() throws

        IOException {

        return new sun.nio.ch.SctpChannelImpl((SelectorProvider)null);

    }

    /**

     * Opens an SCTP channel and connects it to a remote address.

     *

     * <P> This is a convenience method and is equivalent to evaluating the

     * following expression:

     * <blockquote><pre>

     * open().connect(remote, maxOutStreams, maxInStreams);

     * </pre></blockquote>

     *

     * @param  remote

     *         The remote address to which the new channel is to be connected

     *

     * @param  maxOutStreams

     *         The number of streams that the application wishes to be able

     *         to send to. Must be non negative and no larger than {@code 65536}.

     *         {@code 0} to use the endpoints default value.

     *

     * @param  maxInStreams

     *         The maximum number of inbound streams the application is prepared

     *         to support. Must be non negative and no larger than {@code 65536}.

     *         {@code 0} to use the endpoints default value.

     *

     * @return  A new SCTP channel connected to the given address

     *

     * @throws  java.nio.channels.AsynchronousCloseException

     *          If another thread closes this channel

     *          while the connect operation is in progress

     *

     * @throws  java.nio.channels.ClosedByInterruptException

     *          If another thread interrupts the current thread

     *          while the connect operation is in progress, thereby

     *          closing the channel and setting the current thread's

     *          interrupt status

     *

     * @throws  java.nio.channels.UnresolvedAddressException

     *          If the given remote address is not fully resolved

     *

     * @throws  java.nio.channels.UnsupportedAddressTypeException

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

     *

     * @throws  SecurityException

     *          If a security manager has been installed

     *          and it does not permit access to the given remote peer

     *

     * @throws  UnsupportedOperationException

     *          If the SCTP protocol is not supported

     *

     * @throws  IOException

     *          If some other I/O error occurs

     */

    public static SctpChannel open(SocketAddress remote, int maxOutStreams,

                   int maxInStreams) throws IOException {

        SctpChannel ssc = SctpChannel.open();

        ssc.connect(remote, maxOutStreams, maxInStreams);

        return ssc;

    }

    /**

     * Returns the association on this channel's socket.

     *

     * @return  the association, or {@code null} if the channel's socket is not

     *          connected.

     *

     * @throws  ClosedChannelException

     *          If the channel is closed

     *

     * @throws  IOException

     *          If some other I/O error occurs

     */

    public abstract Association association() throws IOException;

    /**

     * Binds the channel's socket to a local address.

     *

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

     * and the local addresses. 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}.

     *

     * @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.AlreadyConnectedException

     *          If this channel is already connected

     *

     * @throws  java.nio.channels.ClosedChannelException

     *          If this channel is closed

     *

     * @throws  java.nio.channels.ConnectionPendingException

     *          If a non-blocking connection operation is already in progress on this channel

     *

     * @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  IOException

     *          If some other I/O error occurs

     */

    public abstract SctpChannel bind(SocketAddress local)

        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> Adding addresses to a connected association is optional functionality.

     * If the endpoint supports dynamic address reconfiguration then it may

     * send the appropriate message to the peer to change the peers address

     * lists.

     *

     * @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.ConnectionPendingException

     *          If a non-blocking connection operation is already in progress on

     *          this channel

     *

     * @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 SctpChannel 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> Removing addresses from a connected association is optional

     * functionality. If the endpoint supports dynamic address reconfiguration

     * then it may send the appropriate message to the peer to change the peers

     * address lists.

     *

     * @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.ConnectionPendingException

     *          If a non-blocking connection operation is already in progress on

     *          this channel

     *

     * @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 {@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 SctpChannel unbindAddress(InetAddress address)

         throws IOException;

    /**

     * Connects this channel's socket.

     *

     * <P> If this channel is in non-blocking mode then an invocation of this

     * method initiates a non-blocking connection operation.  If the connection

     * is established immediately, as can happen with a local connection, then

     * this method returns {@code true}.  Otherwise this method returns

     * {@code false} and the connection operation must later be completed by

     * invoking the {@link #finishConnect finishConnect} method.

     *

     * <P> If this channel is in blocking mode then an invocation of this

     * method will block until the connection is established or an I/O error

     * occurs.

     *

     * <P> If a security manager has been installed then this method verifies

     * that its {@link java.lang.SecurityManager#checkConnect checkConnect}

     * method permits connecting to the address and port number of the given

     * remote peer.

     *

     * <p> This method may be invoked at any time. If a {@link #send send} or

     * {@link #receive receive} operation upon this channel is invoked while an

     * invocation of this method is in progress then that operation will first

     * block until this invocation is complete.  If a connection attempt is

     * initiated but fails, that is, if an invocation of this method throws a

     * checked exception, then the channel will be closed.

     *

     * @param  remote

     *         The remote peer to which this channel is to be connected

     *

     * @return  {@code true} if a connection was established, {@code false} if

     *          this channel is in non-blocking mode and the connection

     *          operation is in progress

     *

     * @throws  java.nio.channels.AlreadyConnectedException

     *          If this channel is already connected

     *

     * @throws  java.nio.channels.ConnectionPendingException

     *          If a non-blocking connection operation is already in progress on

     *          this channel

     *

     * @throws  java.nio.channels.ClosedChannelException

     *          If this channel is closed

     *

     * @throws  java.nio.channels.AsynchronousCloseException

     *          If another thread closes this channel

     *          while the connect operation is in progress

     *

     * @throws  java.nio.channels.ClosedByInterruptException

     *          If another thread interrupts the current thread

     *          while the connect operation is in progress, thereby

     *          closing the channel and setting the current thread's

     *          interrupt status

     *

     * @throws  java.nio.channels.UnresolvedAddressException

     *          If the given remote address is not fully resolved

     *

     * @throws  java.nio.channels.UnsupportedAddressTypeException

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

     *

     * @throws  SecurityException

     *          If a security manager has been installed

     *          and it does not permit access to the given remote peer

     *

     * @throws  IOException

     *          If some other I/O error occurs

     */

    public abstract boolean connect(SocketAddress remote) throws IOException;

    /**

     * Connects this channel's socket.

     *

     * <P> This is a convience method and is equivalent to evaluating the

     * following expression:

     * <blockquote><pre>

     * setOption(SctpStandardSocketOption.SCTP_INIT_MAXSTREAMS, SctpStandardSocketOption.InitMaxStreams.create(maxInStreams, maxOutStreams))

     *  .connect(remote);

     * </pre></blockquote>

     *

     * <P> The {@code maxOutStreams} and {@code maxInStreams} parameters

     * represent the maximum number of streams that the application wishes to be

     * able to send to and receive from. They are negotiated with the remote

     * peer and may be limited by the operating system.

     *

     * @param  remote

     *         The remote peer to which this channel is to be connected

     *

     * @param  maxOutStreams

     *         Must be non negative and no larger than {@code 65536}.

     *         {@code 0} to use the endpoints default value.

     *

     * @param  maxInStreams

     *         Must be non negative and no larger than {@code 65536}.

     *         {@code 0} to use the endpoints default value.

     *

     * @return  {@code true} if a connection was established, {@code false} if

     *          this channel is in non-blocking mode and the connection operation

     *          is in progress

     *

     * @throws  java.nio.channels.AlreadyConnectedException

     *          If this channel is already connected

     *

     * @throws  java.nio.channels.ConnectionPendingException

     *          If a non-blocking connection operation is already in progress on

     *          this channel

     *

     * @throws  java.nio.channels.ClosedChannelException

     *          If this channel is closed

     *

     * @throws  java.nio.channels.AsynchronousCloseException

     *          If another thread closes this channel

     *          while the connect operation is in progress

     *

     * @throws  java.nio.channels.ClosedByInterruptException

     *          If another thread interrupts the current thread

     *          while the connect operation is in progress, thereby

     *          closing the channel and setting the current thread's

     *          interrupt status

     *

     * @throws  java.nio.channels.UnresolvedAddressException

     *          If the given remote address is not fully resolved

     *

     * @throws  java.nio.channels.UnsupportedAddressTypeException

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

     *

     * @throws  SecurityException

     *          If a security manager has been installed

     *          and it does not permit access to the given remote peer

     *

     * @throws  IOException

     *          If some other I/O error occurs

     */

    public abstract boolean connect(SocketAddress remote,

                                    int maxOutStreams,

                                    int maxInStreams)

        throws IOException;

    /**

     * Tells whether or not a connection operation is in progress on this channel.

     *

     * @return  {@code true} if, and only if, a connection operation has been initiated

     *          on this channel but not yet completed by invoking the

     *          {@link #finishConnect} method

     */

    public abstract boolean isConnectionPending();

    /**

     * Finishes the process of connecting an SCTP channel.

     *

     * <P> A non-blocking connection operation is initiated by placing a socket

     * channel in non-blocking mode and then invoking one of its {@link #connect

     * connect} methods.  Once the connection is established, or the attempt has

     * failed, the channel will become connectable and this method may