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 */ 25package com.sun.nio.sctp; 26 27import java.net.SocketAddress; 28import sun.nio.ch.sctp.SctpStdSocketOption; 29 30/** 31 * SCTP channels supports the socket options defined by this class 32 * (as well as those listed in the particular channel class) and may support 33 * additional Implementation specific socket options. 34 * 35 * @since 1.7 36 */ 37public class SctpStandardSocketOptions { 38 private SctpStandardSocketOptions() {} 39 /** 40 * Enables or disables message fragmentation. 41 * 42 * <P> The value of this socket option is a {@code Boolean} that represents 43 * whether the option is enabled or disabled. If enabled no SCTP message 44 * fragmentation will be performed. Instead if a message being sent 45 * exceeds the current PMTU size, the message will NOT be sent and 46 * an error will be indicated to the user. 47 * 48 * <P> It is implementation specific whether or not this option is 49 * supported. 50 */ 51 public static final SctpSocketOption<Boolean> SCTP_DISABLE_FRAGMENTS = new 52 SctpStdSocketOption<Boolean>("SCTP_DISABLE_FRAGMENTS", Boolean.class, 53 sun.nio.ch.sctp.SctpStdSocketOption.SCTP_DISABLE_FRAGMENTS); 54 55 /** 56 * Enables or disables explicit message completion. 57 * 58 * <p> The value of this socket option is a {@code Boolean} that represents 59 * whether the option is enabled or disabled. When this option is enabled, 60 * the {@code send} method may be invoked multiple times to a send message. 61 * The {@code isComplete} parameter of the {@link MessageInfo} must only 62 * be set to {@code true} for the final send to indicate that the message is 63 * complete. If this option is disabled then each individual {@code send} 64 * invocation is considered complete. 65 * 66 * <P> The default value of the option is {@code false} indicating that the 67 * option is disabled. It is implementation specific whether or not this 68 * option is supported. 69 */ 70 public static final SctpSocketOption<Boolean> SCTP_EXPLICIT_COMPLETE = new 71 SctpStdSocketOption<Boolean>("SCTP_EXPLICIT_COMPLETE", Boolean.class, 72 sun.nio.ch.sctp.SctpStdSocketOption.SCTP_EXPLICIT_COMPLETE); 73 74 /** 75 * Fragmented interleave controls how the presentation of messages occur 76 * for the message receiver. There are three levels of fragment interleave 77 * defined. Two of the levels effect {@link SctpChannel}, while 78 * {@link SctpMultiChannel} is effected by all three levels. 79 * 80 * <P> This option takes an {@code Integer} value. It can be set to a value 81 * of {@code 0}, {@code 1} or {@code 2}. 82 * 83 * <P> Setting the three levels provides the following receiver 84 * interactions: 85 * 86 * <P> {@code level 0} - Prevents the interleaving of any messages. This 87 * means that when a partial delivery begins, no other messages will be 88 * received except the message being partially delivered. If another message 89 * arrives on a different stream (or association) that could be delivered, 90 * it will be blocked waiting for the user to read all of the partially 91 * delivered message. 92 * 93 * <P> {@code level 1} - Allows interleaving of messages that are from 94 * different associations. For {@code SctpChannel}, level 0 and 95 * level 1 have the same meaning since an {@code SctpChannel} always 96 * receives messages from the same association. Note that setting an {@code 97 * SctpMultiChannel} to this level may cause multiple partial 98 * delivers from different associations but for any given association, only 99 * one message will be delivered until all parts of a message have been 100 * delivered. This means that one large message, being read with an 101 * association identification of "X", will block other messages from 102 * association "X" from being delivered. 103 * 104 * <P> {@code level 2} - Allows complete interleaving of messages. This 105 * level requires that the sender carefully observe not only the peer 106 * {@code Association} but also must pay careful attention to the stream 107 * number. With this option enabled a partially delivered message may begin 108 * being delivered for association "X" stream "Y" and the next subsequent 109 * receive may return a message from association "X" stream "Z". Note that 110 * no other messages would be delivered for association "X" stream "Y" 111 * until all of stream "Y"'s partially delivered message was read. 112 * Note that this option effects both channel types. Also note that 113 * for an {@code SctpMultiChannel} not only may another streams 114 * message from the same association be delivered from the next receive, 115 * some other associations message may be delivered upon the next receive. 116 * 117 * <P> It is implementation specific whether or not this option is 118 * supported. 119 */ 120 public static final SctpSocketOption<Integer> SCTP_FRAGMENT_INTERLEAVE = 121 new SctpStdSocketOption<Integer>("SCTP_FRAGMENT_INTERLEAVE", 122 Integer.class, 123 sun.nio.ch.sctp.SctpStdSocketOption.SCTP_FRAGMENT_INTERLEAVE); 124 125 /** 126 * The maximum number of streams requested by the local endpoint during 127 * association initialization. 128 * 129 * <P> The value of this socket option is an {@link 130 * SctpStandardSocketOptions.InitMaxStreams InitMaxStreams}, that represents 131 * the maximum number of inbound and outbound streams that an association 132 * on the channel is prepared to support. 133 * 134 * <P> For an {@link SctpChannel} this option may only be used to 135 * change the number of inbound/outbound streams prior to connecting. 136 * 137 * <P> For an {@link SctpMultiChannel} this option determines 138 * the maximum number of inbound/outbound streams new associations setup 139 * on the channel will be prepared to support. 140 * 141 * <P> For an {@link SctpServerChannel} this option determines the 142 * maximum number of inbound/outbound streams accepted sockets will 143 * negotiate with their connecting peer. 144 * 145 * <P> In all cases the value set by this option is used in the negotiation 146 * of new associations setup on the channel's socket and the actual 147 * maximum number of inbound/outbound streams that have been negotiated 148 * with the peer can be retrieved from the appropriate {@link 149 * Association}. The {@code Association} can be retrieved from the 150 * {@link AssociationChangeNotification.AssocChangeEvent#COMM_UP COMM_UP} 151 * {@link AssociationChangeNotification} belonging to that association. 152 * 153 * <p> This value is bounded by the actual implementation. In other 154 * words the user may be able to support more streams than the Operating 155 * System. In such a case, the Operating System limit may override the 156 * value requested by the user. The default value of 0 indicates to use 157 * the endpoints default value. 158 */ 159 public static final SctpSocketOption 160 <SctpStandardSocketOptions.InitMaxStreams> SCTP_INIT_MAXSTREAMS = 161 new SctpStdSocketOption<SctpStandardSocketOptions.InitMaxStreams>( 162 "SCTP_INIT_MAXSTREAMS", SctpStandardSocketOptions.InitMaxStreams.class); 163 164 /** 165 * Enables or disables a Nagle-like algorithm. 166 * 167 * <P> The value of this socket option is a {@code Boolean} that represents 168 * whether the option is enabled or disabled. SCTP uses an algorithm like 169 * <em>The Nagle Algorithm</em> to coalesce short segments and 170 * improve network efficiency. 171 */ 172 public static final SctpSocketOption<Boolean> SCTP_NODELAY = 173 new SctpStdSocketOption<Boolean>("SCTP_NODELAY", Boolean.class, 174 sun.nio.ch.sctp.SctpStdSocketOption.SCTP_NODELAY); 175 176 /** 177 * Requests that the local SCTP stack use the given peer address as 178 * the association primary. 179 * 180 * <P> The value of this socket option is a {@code SocketAddress} 181 * that represents the peer address that the local SCTP stack should use as 182 * the association primary. The address must be one of the association 183 * peer's addresses. 184 * 185 * <P> An {@code SctpMultiChannel} can control more than one 186 * association, the association parameter must be given when setting or 187 * retrieving this option. 188 * 189 * <P> Since {@code SctpChannel} only controls one association, 190 * the association parameter is not required and this option can be 191 * set or queried directly. 192 */ 193 public static final SctpSocketOption<SocketAddress> SCTP_PRIMARY_ADDR = 194 new SctpStdSocketOption<SocketAddress> 195 ("SCTP_PRIMARY_ADDR", SocketAddress.class); 196 197 /** 198 * Requests that the peer mark the enclosed address as the association 199 * primary. 200 * 201 * <P> The value of this socket option is a {@code SocketAddress} 202 * that represents the local address that the peer should use as its 203 * primary address. The given address must be one of the association's 204 * locally bound addresses. 205 * 206 * <P> An {@code SctpMultiChannel} can control more than one 207 * association, the association parameter must be given when setting or 208 * retrieving this option. 209 * 210 * <P> Since {@code SctpChannel} only controls one association, 211 * the association parameter is not required and this option can be 212 * queried directly. 213 * 214 * <P> Note, this is a set only option and cannot be retrieved by {@code 215 * getOption}. It is implementation specific whether or not this 216 * option is supported. 217 */ 218 public static final SctpSocketOption<SocketAddress> SCTP_SET_PEER_PRIMARY_ADDR = 219 new SctpStdSocketOption<SocketAddress> 220 ("SCTP_SET_PEER_PRIMARY_ADDR", SocketAddress.class); 221 222 /** 223 * The size of the socket send buffer. 224 * 225 * <p> The value of this socket option is an {@code Integer} that is the 226 * size of the socket send buffer in bytes. The socket send buffer is an 227 * output buffer used by the networking implementation. It may need to be 228 * increased for high-volume connections. The value of the socket option is 229 * a <em>hint</em> to the implementation to size the buffer and the actual 230 * size may differ. The socket option can be queried to retrieve the actual 231 * size. 232 * 233 * <p> For {@code SctpChannel}, this controls the amount of data 234 * the SCTP stack may have waiting in internal buffers to be sent. This 235 * option therefore bounds the maximum size of data that can be sent in a 236 * single send call. 237 * 238 * <P> For {@code SctpMultiChannel}, the effect is the same as for {@code 239 * SctpChannel}, except that it applies to all associations. The option 240 * applies to each association's window size separately. 241 * 242 * <p> An implementation allows this socket option to be set before the 243 * socket is bound or connected. Whether an implementation allows the 244 * socket send buffer to be changed after the socket is bound is system 245 * dependent. 246 */ 247 public static final SctpSocketOption<Integer> SO_SNDBUF = 248 new SctpStdSocketOption<Integer>("SO_SNDBUF", Integer.class, 249 sun.nio.ch.sctp.SctpStdSocketOption.SO_SNDBUF); 250 251 /** 252 * The size of the socket receive buffer. 253 * 254 * <P> The value of this socket option is an {@code Integer} that is the 255 * size of the socket receive buffer in bytes. The socket receive buffer is 256 * an input buffer used by the networking implementation. It may need to be 257 * increased for high-volume connections or decreased to limit the possible 258 * backlog of incoming data. The value of the socket option is a 259 * <em>hint</em> to the implementation to size the buffer and the actual 260 * size may differ. 261 * 262 * <P> For {@code SctpChannel}, this controls the receiver window size. 263 * 264 * <P> For {@code SctpMultiChannel}, the meaning is implementation 265 * dependent. It might control the receive buffer for each association bound 266 * to the socket descriptor or it might control the receive buffer for the 267 * whole socket. 268 * 269 * <p> An implementation allows this socket option to be set before the 270 * socket is bound or connected. Whether an implementation allows the 271 * socket receive buffer to be changed after the socket is bound is system 272 * dependent. 273 */ 274 public static final SctpSocketOption<Integer> SO_RCVBUF = 275 new SctpStdSocketOption<Integer>("SO_RCVBUF", Integer.class, 276 sun.nio.ch.sctp.SctpStdSocketOption.SO_RCVBUF); 277 278 /** 279 * Linger on close if data is present. 280 * 281 * <p> The value of this socket option is an {@code Integer} that controls 282 * the action taken when unsent data is queued on the socket and a method 283 * to close the socket is invoked. If the value of the socket option is zero 284 * or greater, then it represents a timeout value, in seconds, known as the 285 * <em>linger interval</em>. The linger interval is the timeout for the 286 * {@code close} method to block while the operating system attempts to 287 * transmit the unsent data or it decides that it is unable to transmit the 288 * data. If the value of the socket option is less than zero then the option 289 * is disabled. In that case the {@code close} method does not wait until 290 * unsent data is transmitted; if possible the operating system will transmit 291 * any unsent data before the connection is closed. 292 * 293 * <p> This socket option is intended for use with sockets that are configured 294 * in {@link java.nio.channels.SelectableChannel#isBlocking() blocking} mode 295 * only. The behavior of the {@code close} method when this option is 296 * enabled on a non-blocking socket is not defined. 297 * 298 * <p> The initial value of this socket option is a negative value, meaning 299 * that the option is disabled. The option may be enabled, or the linger 300 * interval changed, at any time. The maximum value of the linger interval 301 * is system dependent. Setting the linger interval to a value that is 302 * greater than its maximum value causes the linger interval to be set to 303 * its maximum value. 304 */ 305 public static final SctpSocketOption<Integer> SO_LINGER = 306 new SctpStdSocketOption<Integer>("SO_LINGER", Integer.class, 307 sun.nio.ch.sctp.SctpStdSocketOption.SO_LINGER); 308 309 /** 310 * This class is used to set the maximum number of inbound/outbound streams 311 * used by the local endpoint during association initialization. An 312 * instance of this class is used to set the {@link 313 * SctpStandardSocketOptions#SCTP_INIT_MAXSTREAMS SCTP_INIT_MAXSTREAMS} 314 * socket option. 315 * 316 * @since 1.7 317 */ 318 public static class InitMaxStreams { 319 private int maxInStreams; 320 private int maxOutStreams; 321 322 private InitMaxStreams(int maxInStreams, int maxOutStreams) { 323 this.maxInStreams = maxInStreams; 324 this.maxOutStreams = maxOutStreams; 325 } 326 327 /** 328 * Creates an InitMaxStreams instance. 329 * 330 * @param maxInStreams 331 * The maximum number of inbound streams, where 332 * {@code 0 <= maxInStreams <= 65536} 333 * 334 * @param maxOutStreams 335 * The maximum number of outbound streams, where 336 * {@code 0 <= maxOutStreams <= 65536} 337 * 338 * @return An {@code InitMaxStreams} instance 339 * 340 * @throws IllegalArgumentException 341 * If an argument is outside of specified bounds 342 */ 343 public static InitMaxStreams create 344 (int maxInStreams, int maxOutStreams) { 345 if (maxOutStreams < 0 || maxOutStreams > 65535) 346 throw new IllegalArgumentException( 347 "Invalid maxOutStreams value"); 348 if (maxInStreams < 0 || maxInStreams > 65535) 349 throw new IllegalArgumentException( 350 "Invalid maxInStreams value"); 351 352 return new InitMaxStreams(maxInStreams, maxOutStreams); 353 } 354 355 /** 356 * Returns the maximum number of inbound streams. 357 * 358 * @return Maximum inbound streams 359 */ 360 public int maxInStreams() { 361 return maxInStreams; 362 } 363 364 /** 365 * Returns the maximum number of outbound streams. 366 * 367 * @return Maximum outbound streams 368 */ 369 public int maxOutStreams() { 370 return maxOutStreams; 371 } 372 373 /** 374 * Returns a string representation of this init max streams, including 375 * the maximum in and out bound streams. 376 * 377 * @return A string representation of this init max streams 378 */ 379 @Override 380 public String toString() { 381 StringBuilder sb = new StringBuilder(); 382 sb.append(super.toString()).append(" ["); 383 sb.append("maxInStreams:").append(maxInStreams); 384 sb.append("maxOutStreams:").append(maxOutStreams).append("]"); 385 return sb.toString(); 386 } 387 388 /** 389 * Returns true if the specified object is another {@code InitMaxStreams} 390 * instance with the same number of in and out bound streams. 391 * 392 * @param obj 393 * The object to be compared with this init max streams 394 * 395 * @return true if the specified object is another 396 * {@code InitMaxStreams} instance with the same number of in 397 * and out bound streams 398 */ 399 @Override 400 public boolean equals(Object obj) { 401 if (obj != null && obj instanceof InitMaxStreams) { 402 InitMaxStreams that = (InitMaxStreams) obj; 403 if (this.maxInStreams == that.maxInStreams && 404 this.maxOutStreams == that.maxOutStreams) 405 return true; 406 } 407 return false; 408 } 409 410 /** 411 * Returns a hash code value for this init max streams. 412 */ 413 @Override 414 public int hashCode() { 415 int hash = 7 ^ maxInStreams ^ maxOutStreams; 416 return hash; 417 } 418 } 419} 420