View Javadoc
1   /*
2    * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package com.sun.nio.sctp;
26  
27  import java.net.SocketAddress;
28  
29  /**
30   * The {@code MessageInfo} class provides additional ancillary information about
31   * messages.
32   *
33   * <P> Received SCTP messages, returned by
34   * {@link SctpChannel#receive SctpChannel.receive} and {@link
35   * SctpMultiChannel#receive SctpMultiChannel.receive},
36   * return a {@code MessageInfo} instance that can be queried to determine
37   * ancillary information about the received message. Messages being sent should
38   * use one of the {@link #createOutgoing(java.net.SocketAddress,int)
39   * createOutgoing} methods to provide ancillary data for the message being
40   * sent, and may use the appropriate setter methods to override the default
41   * values provided for {@link #isUnordered() unordered}, {@link #timeToLive()
42   * timeToLive}, {@link #isComplete() complete} and {@link #payloadProtocolID()
43   * payloadProtocolID}, before sending the message.
44   *
45   * <P> For out going messages the {@code timeToLive} parameter is a time period
46   * that the sending side SCTP stack may expire the message if it has not been
47   * sent. This time period is an indication to the stack that the message is no
48   * longer required to be sent after the time period expires. It is not a hard
49   * timeout and may be influenced by whether the association supports the partial
50   * reliability extension, <a href=http://www.ietf.org/rfc/rfc3758.txt>RFC 3758
51   * </a>.
52   *
53   * <P> {@code MessageInfo} instances are not safe for use by multiple concurrent
54   * threads. If a MessageInfo is to be used by more than one thread then access
55   * to the MessageInfo should be controlled by appropriate synchronization.
56   *
57   * @since 1.7
58   */
59  @jdk.Exported
60  public abstract class MessageInfo {
61      /**
62       * Initializes a new instance of this class.
63       */
64      protected MessageInfo() {}
65  
66      /**
67       * Creates a {@code MessageInfo} instance suitable for use when
68       * sending a message.
69       *
70       * <P> The returned instance will have its {@link #isUnordered() unordered}
71       * value set to {@code false}, its {@link #timeToLive() timeToLive} value
72       * set to {@code 0}, its {@link #isComplete() complete} value set
73       * to {@code true}, and its {@link #payloadProtocolID() payloadProtocolID}
74       * value set to {@code 0}. These values, if required, can be set through
75       * the appropriate setter method before sending the message.
76       *
77       * @param  address
78       *         For a connected {@code SctpChannel} the address is the
79       *         preferred peer address of the association to send the message
80       *         to, or {@code null} to use the peer primary address. For an
81       *         {@code SctpMultiChannel} the address is used to determine
82       *         the association, or if no association exists with a peer of that
83       *         address then one is setup.
84       *
85       * @param  streamNumber
86       *         The stream number that the message will be sent on
87       *
88       * @return  The outgoing message info
89       *
90       * @throws  IllegalArgumentException
91       *          If the streamNumber is negative or greater than {@code 65536}
92       */
93      public static MessageInfo createOutgoing(SocketAddress address,
94                                               int streamNumber) {
95          if (streamNumber < 0 || streamNumber > 65536)
96              throw new IllegalArgumentException("Invalid stream number");
97  
98          return new sun.nio.ch.sctp.MessageInfoImpl(null, address, streamNumber);
99      }
100     /**
101      * Creates a {@code MessageInfo} instance suitable for use when
102      * sending a message to a given association. Typically used for
103      * {@code SctpMultiChannel} when an association has already been setup.
104      *
105      * <P> The returned instance will have its {@link #isUnordered() unordered}
106      * value set to {@code false}, its {@link #timeToLive() timeToLive} value
107      * set to {@code 0}, its {@link #isComplete() complete} value set
108      * to {@code true}, and its {@link #payloadProtocolID() payloadProtocolID}
109      * value set to {@code 0}. These values, if required, can be set through
110      * the appropriate setter method before sending the message.
111      *
112      * @param  association
113      *         The association to send the message on
114      *
115      * @param  address
116      *         The preferred peer address of the association to send the message
117      *         to, or {@code null} to use the peer primary address
118      *
119      * @param  streamNumber
120      *         The stream number that the message will be sent on.
121      *
122      * @return  The outgoing message info
123      *
124      * @throws  IllegalArgumentException
125      *          If {@code association} is {@code null}, or the streamNumber is
126      *          negative or greater than {@code 65536}
127      */
128     public static MessageInfo createOutgoing(Association association,
129                                              SocketAddress address,
130                                              int streamNumber) {
131         if (association == null)
132             throw new IllegalArgumentException("association cannot be null");
133 
134         if (streamNumber < 0 || streamNumber > 65536)
135             throw new IllegalArgumentException("Invalid stream number");
136 
137         return new sun.nio.ch.sctp.MessageInfoImpl(association,
138                                                    address, streamNumber);
139     }
140 
141     /**
142      * Returns the source socket address if the message has been received,
143      * otherwise the preferred destination of the message to be sent.
144      *
145      * @return  The socket address, or {@code null} if this instance is to be
146      *          used for sending a message and has been construced without
147      *          specifying a preferred destination address
148      *
149      */
150     public abstract SocketAddress address();
151 
152     /**
153      * Returns the association that the message was received on, if the message
154      * has been received, otherwise the association that the message is to be
155      * sent on.
156      *
157      * @return The association, or {@code null} if this instance is to be
158      *         used for sending a message and has been construced using the
159      *         the {@link #createOutgoing(SocketAddress,int)
160      *         createOutgoing(SocketAddress,int)} static factory method
161      */
162     public abstract Association association();
163 
164     /**
165      * Returns the number of bytes read for the received message.
166      *
167      * <P> This method is only appicable for received messages, it has no
168      * meaning for messages being sent.
169      *
170      * @return  The number of bytes read, {@code -1} if the channel is an {@link
171      *          SctpChannel} that has reached end-of-stream, otherwise
172      *          {@code 0}
173      */
174     public abstract int bytes();
175 
176     /**
177      * Tells whether or not the message is complete.
178      *
179      * <P> For received messages {@code true} indicates that the message was
180      * completely received. For messages being sent {@code true} indicates that
181      * the message is complete, {@code false} indicates that the message is not
182      * complete. How the send channel interprets this value depends on the value
183      * of its {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE
184      * SCTP_EXPLICIT_COMPLETE} socket option.
185      *
186      * @return  {@code true} if, and only if, the message is complete
187      */
188     public abstract boolean isComplete();
189 
190     /**
191      * Sets whether or not the message is complete.
192      *
193      * <P> For messages being sent {@code true} indicates that
194      * the message is complete, {@code false} indicates that the message is not
195      * complete. How the send channel interprets this value depends on the value
196      * of its {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE
197      * SCTP_EXPLICIT_COMPLETE} socket option.
198      *
199      * @param  complete
200      *         {@code true} if, and only if, the message is complete
201      *
202      * @return  This MessageInfo
203      *
204      * @see  MessageInfo#isComplete()
205      */
206     public abstract MessageInfo complete(boolean complete);
207 
208     /**
209      * Tells whether or not the message is unordered. For received messages
210      * {@code true} indicates that the message was sent non-ordered. For
211      * messages being sent {@code true} requests the un-ordered delivery of the
212      * message, {@code false} indicates that the message is ordered.
213      *
214      * @return  {@code true} if the message is unordered, otherwise
215      *          {@code false}
216      */
217     public abstract boolean isUnordered();
218 
219     /**
220      * Sets whether or not the message is unordered.
221      *
222      * @param  unordered
223      *         {@code true} requests the un-ordered delivery of the message,
224      *         {@code false} indicates that the message is ordered.
225      *
226      * @return  This MessageInfo
227      *
228      * @see  MessageInfo#isUnordered()
229      */
230     public abstract MessageInfo unordered(boolean unordered);
231 
232     /**
233      * Returns the payload protocol Identifier.
234      *
235      * <P> A value indicating the type of payload protocol data being
236      * transmitted/received. This value is passed as opaque data by SCTP.
237      * {@code 0} indicates an unspecified payload protocol identifier.
238      *
239      * @return  The Payload Protocol Identifier
240      */
241     public abstract int payloadProtocolID();
242 
243     /**
244      * Sets the payload protocol Identifier.
245      *
246      * <P> A value indicating the type of payload protocol data being
247      * transmitted. This value is passed as opaque data by SCTP.
248      *
249      * @param  ppid
250      *         The Payload Protocol Identifier, or {@code 0} indicate an
251      *         unspecified payload protocol identifier.
252      *
253      * @return  This MessageInfo
254      *
255      * @see  MessageInfo#payloadProtocolID()
256      */
257     public abstract MessageInfo payloadProtocolID(int ppid);
258 
259     /**
260      * Returns the stream number that the message was received on, if the
261      * message has been received, otherwise the stream number that the message
262      * is to be sent on.
263      *
264      * @return  The stream number
265      */
266     public abstract int streamNumber();
267 
268     /**
269      * Sets the stream number that the message is to be sent on.
270      *
271      * @param  streamNumber
272      *         The stream number
273      *
274      * @throws  IllegalArgumentException
275      *          If the streamNumber is negative or greater than {@code 65536}
276      *
277      * @return  This MessageInfo
278      */
279     public abstract MessageInfo streamNumber(int streamNumber);
280 
281     /**
282      * The time period that the sending side may expire the message if it has
283      * not been sent, or {@code 0} to indicate that no timeout should occur. This
284      * value is only applicable for messages being sent, it has no meaning for
285      * received messages.
286      *
287      * @return  The time period in milliseconds, or {@code 0}
288      */
289     public abstract long timeToLive();
290 
291     /**
292      * Sets the time period that the sending side may expire the message if it
293      * has not been sent.
294      *
295      * @param  millis
296      *         The time period in milliseconds, or {@code 0} to indicate that no
297      *         timeout should occur
298      *
299      * @return  This MessageInfo
300      *
301      * @see MessageInfo#timeToLive()
302      */
303     public abstract MessageInfo timeToLive(long millis);
304 }