/*

 * Copyright (c) 2009, 2013, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package com.sun.nio.sctp;

import java.net.SocketAddress;

/**

 * The {@code MessageInfo} class provides additional ancillary information about

 * messages.

 *

 * <P> Received SCTP messages, returned by

 * {@link SctpChannel#receive SctpChannel.receive} and {@link

 * SctpMultiChannel#receive SctpMultiChannel.receive},

 * return a {@code MessageInfo} instance that can be queried to determine

 * ancillary information about the received message. Messages being sent should

 * use one of the {@link #createOutgoing(java.net.SocketAddress,int)

 * createOutgoing} methods to provide ancillary data for the message being

 * sent, and may use the appropriate setter methods to override the default

 * values provided for {@link #isUnordered() unordered}, {@link #timeToLive()

 * timeToLive}, {@link #isComplete() complete} and {@link #payloadProtocolID()

 * payloadProtocolID}, before sending the message.

 *

 * <P> For out going messages the {@code timeToLive} parameter is a time period

 * that the sending side SCTP stack may expire the message if it has not been

 * sent. This time period is an indication to the stack that the message is no

 * longer required to be sent after the time period expires. It is not a hard

 * timeout and may be influenced by whether the association supports the partial

 * reliability extension, <a href=http://www.ietf.org/rfc/rfc3758.txt>RFC 3758

 * </a>.

 *

 * <P> {@code MessageInfo} instances are not safe for use by multiple concurrent

 * threads. If a MessageInfo is to be used by more than one thread then access

 * to the MessageInfo should be controlled by appropriate synchronization.

 *

 * @since 1.7

 */

public abstract class MessageInfo {

    /**

     * Initializes a new instance of this class.

     */

    protected MessageInfo() {}

    /**

     * Creates a {@code MessageInfo} instance suitable for use when

     * sending a message.

     *

     * <P> The returned instance will have its {@link #isUnordered() unordered}

     * value set to {@code false}, its {@link #timeToLive() timeToLive} value

     * set to {@code 0}, its {@link #isComplete() complete} value set

     * to {@code true}, and its {@link #payloadProtocolID() payloadProtocolID}

     * value set to {@code 0}. These values, if required, can be set through

     * the appropriate setter method before sending the message.

     *

     * @param  address

     *         For a connected {@code SctpChannel} the address is the

     *         preferred peer address of the association to send the message

     *         to, or {@code null} to use the peer primary address. For an

     *         {@code SctpMultiChannel} the address is used to determine

     *         the association, or if no association exists with a peer of that

     *         address then one is setup.

     *

     * @param  streamNumber

     *         The stream number that the message will be sent on

     *

     * @return  The outgoing message info

     *

     * @throws  IllegalArgumentException

     *          If the streamNumber is negative or greater than {@code 65536}

     */

    public static MessageInfo createOutgoing(SocketAddress address,

                                             int streamNumber) {

        if (streamNumber < 0 || streamNumber > 65536)

            throw new IllegalArgumentException("Invalid stream number");

        return new sun.nio.ch.sctp.MessageInfoImpl(null, address, streamNumber);

    }

    /**

     * Creates a {@code MessageInfo} instance suitable for use when

     * sending a message to a given association. Typically used for

     * {@code SctpMultiChannel} when an association has already been setup.

     *

     * <P> The returned instance will have its {@link #isUnordered() unordered}

     * value set to {@code false}, its {@link #timeToLive() timeToLive} value

     * set to {@code 0}, its {@link #isComplete() complete} value set

     * to {@code true}, and its {@link #payloadProtocolID() payloadProtocolID}

     * value set to {@code 0}. These values, if required, can be set through

     * the appropriate setter method before sending the message.

     *

     * @param  association

     *         The association to send the message on

     *

     * @param  address

     *         The preferred peer address of the association to send the message

     *         to, or {@code null} to use the peer primary address

     *

     * @param  streamNumber

     *         The stream number that the message will be sent on.

     *

     * @return  The outgoing message info

     *

     * @throws  IllegalArgumentException

     *          If {@code association} is {@code null}, or the streamNumber is

     *          negative or greater than {@code 65536}

     */

    public static MessageInfo createOutgoing(Association association,

                                             SocketAddress address,

                                             int streamNumber) {

        if (association == null)

            throw new IllegalArgumentException("association cannot be null");

        if (streamNumber < 0 || streamNumber > 65536)

            throw new IllegalArgumentException("Invalid stream number");

        return new sun.nio.ch.sctp.MessageInfoImpl(association,

                                                   address, streamNumber);

    }

    /**

     * Returns the source socket address if the message has been received,

     * otherwise the preferred destination of the message to be sent.

     *

     * @return  The socket address, or {@code null} if this instance is to be

     *          used for sending a message and has been construced without

     *          specifying a preferred destination address

     *

     */

    public abstract SocketAddress address();

    /**

     * Returns the association that the message was received on, if the message

     * has been received, otherwise the association that the message is to be

     * sent on.

     *

     * @return The association, or {@code null} if this instance is to be

     *         used for sending a message and has been construced using the

     *         the {@link #createOutgoing(SocketAddress,int)

     *         createOutgoing(SocketAddress,int)} static factory method

     */

    public abstract Association association();

    /**

     * Returns the number of bytes read for the received message.

     *

     * <P> This method is only appicable for received messages, it has no

     * meaning for messages being sent.

     *

     * @return  The number of bytes read, {@code -1} if the channel is an {@link

     *          SctpChannel} that has reached end-of-stream, otherwise

     *          {@code 0}

     */

    public abstract int bytes();

    /**

     * Tells whether or not the message is complete.

     *

     * <P> For received messages {@code true} indicates that the message was

     * completely received. For messages being sent {@code true} indicates that

     * the message is complete, {@code false} indicates that the message is not

     * complete. How the send channel interprets this value depends on the value

     * of its {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE

     * SCTP_EXPLICIT_COMPLETE} socket option.

     *

     * @return  {@code true} if, and only if, the message is complete

     */

    public abstract boolean isComplete();

    /**

     * Sets whether or not the message is complete.

     *

     * <P> For messages being sent {@code true} indicates that

     * the message is complete, {@code false} indicates that the message is not

     * complete. How the send channel interprets this value depends on the value

     * of its {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE

     * SCTP_EXPLICIT_COMPLETE} socket option.

     *

     * @param  complete

     *         {@code true} if, and only if, the message is complete

     *

     * @return  This MessageInfo

     *

     * @see  MessageInfo#isComplete()

     */

    public abstract MessageInfo complete(boolean complete);

    /**

     * Tells whether or not the message is unordered. For received messages

     * {@code true} indicates that the message was sent non-ordered. For

     * messages being sent {@code true} requests the un-ordered delivery of the

     * message, {@code false} indicates that the message is ordered.

     *

     * @return  {@code true} if the message is unordered, otherwise

     *          {@code false}

     */

    public abstract boolean isUnordered();

    /**

     * Sets whether or not the message is unordered.

     *

     * @param  unordered

     *         {@code true} requests the un-ordered delivery of the message,

     *         {@code false} indicates that the message is ordered.

     *

     * @return  This MessageInfo

     *

     * @see  MessageInfo#isUnordered()

     */

    public abstract MessageInfo unordered(boolean unordered);

    /**

     * Returns the payload protocol Identifier.

     *

     * <P> A value indicating the type of payload protocol data being

     * transmitted/received. This value is passed as opaque data by SCTP.

     * {@code 0} indicates an unspecified payload protocol identifier.

     *

     * @return  The Payload Protocol Identifier

     */

    public abstract int payloadProtocolID();

    /**

     * Sets the payload protocol Identifier.

     *

     * <P> A value indicating the type of payload protocol data being

     * transmitted. This value is passed as opaque data by SCTP.

     *

     * @param  ppid

     *         The Payload Protocol Identifier, or {@code 0} indicate an

     *         unspecified payload protocol identifier.

     *

     * @return  This MessageInfo

     *

     * @see  MessageInfo#payloadProtocolID()

     */

    public abstract MessageInfo payloadProtocolID(int ppid);

    /**

     * Returns the stream number that the message was received on, if the

     * message has been received, otherwise the stream number that the message

     * is to be sent on.

     *

     * @return  The stream number

     */

    public abstract int streamNumber();

    /**

     * Sets the stream number that the message is to be sent on.

     *

     * @param  streamNumber

     *         The stream number

     *

     * @throws  IllegalArgumentException

     *          If the streamNumber is negative or greater than {@code 65536}

     *

     * @return  This MessageInfo

     */

    public abstract MessageInfo streamNumber(int streamNumber);

    /**

     * The time period that the sending side may expire the message if it has

     * not been sent, or {@code 0} to indicate that no timeout should occur. This

     * value is only applicable for messages being sent, it has no meaning for

     * received messages.

     *

     * @return  The time period in milliseconds, or {@code 0}

     */

    public abstract long timeToLive();

    /**

     * Sets the time period that the sending side may expire the message if it

     * has not been sent.

     *

     * @param  millis

     *         The time period in milliseconds, or {@code 0} to indicate that no

     *         timeout should occur

     *

     * @return  This MessageInfo

     *

     * @see MessageInfo#timeToLive()

     */

    public abstract MessageInfo timeToLive(long millis);

}