--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.sctp/share/classes/com/sun/nio/sctp/MessageInfo.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,303 @@
+/*
+ * 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);
+}