Java example source code file (MessageInfo.java)

This example Java source code file (MessageInfo.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

association, illegalargumentexception, invalid, messageinfo, net, network, socketaddress

The MessageInfo.java Java example source code

/*
 * 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
 */
@jdk.Exported
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);
}