305 lines
12 KiB
Java
305 lines
12 KiB
Java
/*
|
|
* 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);
|
|
}
|