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 import java.net.InetAddress; 29 import java.io.IOException; 30 import java.util.Set; 31 import java.nio.ByteBuffer; 32 import java.nio.channels.spi.AbstractSelectableChannel; 33 import java.nio.channels.spi.SelectorProvider; 34 import java.nio.channels.ClosedChannelException; 35 import java.nio.channels.NotYetBoundException; 36 import java.nio.channels.SelectionKey; 37 38 /** 39 * A selectable channel for message-oriented SCTP sockets. 40 * 41 * <P> An SCTP multi channel supports many associations on a single socket. 42 * An {@code SctpMultiChannel} is created by invoking the 43 * {@link #open open} method of this class. A newly-created channel is open but 44 * not yet bound. An attempt to invoke the {@link #receive receive} method of an 45 * unbound channel will cause the {@link NotYetBoundException} 46 * to be thrown. An attempt to invoke the {@link #send send} method of an 47 * unbound channel will cause it to first invoke the {@link #bind bind} method. 48 * The address(es) that the channel's socket is bound to can be retrieved by 49 * calling {@link #getAllLocalAddresses getAllLocalAddresses}. 50 * 51 * <P> Messages may be sent and received without explicitly setting up an 52 * association with the remote peer. The channel will implicitly setup 53 * a new association whenever it sends or receives a message from a remote 54 * peer if there is not already an association with that peer. Upon successful 55 * association setup, an {@link AssociationChangeNotification 56 * association changed} notification will be put to the SCTP stack with its 57 * {@code event} parameter set to {@link 58 * AssociationChangeNotification.AssocChangeEvent#COMM_UP 59 * COMM_UP}. This notification can be received by invoking {@link #receive 60 * receive}. 61 * 62 * <P> Socket options are configured using the 63 * {@link #setOption(SctpSocketOption,Object,Association) setOption} method. An 64 * {@code SctpMultiChannel} supports the following options: 65 * <blockquote> 66 * <table border summary="Socket options"> 67 * <tr> 68 * <th>Option Name</th> 69 * <th>Description</th> 70 * </tr> 71 * <tr> 72 * <td> {@link SctpStandardSocketOptions#SCTP_DISABLE_FRAGMENTS 73 * SCTP_DISABLE_FRAGMENTS} </td> 74 * <td> Enables or disables message fragmentation </td> 75 * </tr> 76 * <tr> 77 * <td> {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE 78 * SCTP_EXPLICIT_COMPLETE} </td> 79 * <td> Enables or disables explicit message completion </td> 80 * </tr> 81 * <tr> 82 * <td> {@link SctpStandardSocketOptions#SCTP_FRAGMENT_INTERLEAVE 83 * SCTP_FRAGMENT_INTERLEAVE} </td> 84 * <td> Controls how the presentation of messages occur for the message 85 * receiver </td> 86 * </tr> 87 * <tr> 88 * <td> {@link SctpStandardSocketOptions#SCTP_INIT_MAXSTREAMS 89 * SCTP_INIT_MAXSTREAMS} </td> 90 * <td> The maximum number of streams requested by the local endpoint during 91 * association initialization </td> 92 * </tr> 93 * <tr> 94 * <td> {@link SctpStandardSocketOptions#SCTP_NODELAY SCTP_NODELAY} </td> 95 * <td> Enables or disable a Nagle-like algorithm </td> 96 * </tr> 97 * <tr> 98 * <td> {@link SctpStandardSocketOptions#SCTP_PRIMARY_ADDR 99 * SCTP_PRIMARY_ADDR} </td> 100 * <td> Requests that the local SCTP stack use the given peer address as the 101 * association primary </td> 102 * </tr> 103 * <tr> 104 * <td> {@link SctpStandardSocketOptions#SCTP_SET_PEER_PRIMARY_ADDR 105 * SCTP_SET_PEER_PRIMARY_ADDR} </td> 106 * <td> Requests that the peer mark the enclosed address as the association 107 * primary </td> 108 * </tr> 109 * <tr> 110 * <td> {@link SctpStandardSocketOptions#SO_SNDBUF 111 * SO_SNDBUF} </td> 112 * <td> The size of the socket send buffer </td> 113 * </tr> 114 * <tr> 115 * <td> {@link SctpStandardSocketOptions#SO_RCVBUF 116 * SO_RCVBUF} </td> 117 * <td> The size of the socket receive buffer </td> 118 * </tr> 119 * <tr> 120 * <td> {@link SctpStandardSocketOptions#SO_LINGER 121 * SO_LINGER} </td> 122 * <td> Linger on close if data is present (when configured in blocking mode 123 * only) </td> 124 * </tr> 125 * </table> 126 * </blockquote> 127 * Additional (implementation specific) options may also be supported. The list 128 * of options supported is obtained by invoking the {@link #supportedOptions() 129 * supportedOptions} method. 130 * 131 * <p> SCTP multi channels are safe for use by multiple concurrent threads. 132 * They support concurrent sending and receiving, though at most one thread may be 133 * sending and at most one thread may be receiving at any given time. 134 * 135 * @since 1.7 136 */ 137 @jdk.Exported 138 public abstract class SctpMultiChannel 139 extends AbstractSelectableChannel 140 { 141 /** 142 * Initializes a new instance of this class. 143 * 144 * @param provider 145 * The selector provider for this channel 146 */ SctpMultiChannel(SelectorProvider provider)147 protected SctpMultiChannel(SelectorProvider provider) { 148 super(provider); 149 } 150 151 /** 152 * Opens an SCTP multi channel. 153 * 154 * <P> The new channel is unbound. 155 * 156 * @return A new SCTP multi channel 157 * 158 * @throws UnsupportedOperationException 159 * If the SCTP protocol is not supported 160 * 161 * @throws IOException 162 * If an I/O error occurs 163 */ open()164 public static SctpMultiChannel open() throws 165 IOException { 166 return new sun.nio.ch.sctp.SctpMultiChannelImpl((SelectorProvider)null); 167 } 168 169 /** 170 * Returns the open associations on this channel's socket. 171 * 172 * <P> Only associations whose {@link AssociationChangeNotification.AssocChangeEvent#COMM_UP 173 * COMM_UP} association change event has been received are included 174 * in the returned set of associations. Associations for which a 175 * {@link AssociationChangeNotification.AssocChangeEvent#COMM_LOST COMM_LOST} or {@link 176 * AssociationChangeNotification.AssocChangeEvent#SHUTDOWN SHUTDOWN} association change 177 * event have been receive are removed from the set of associations. 178 * 179 * <P> The returned set of associations is a snapshot of the open 180 * associations at the time that this method is invoked. 181 * 182 * @return A {@code Set} containing the open associations, or an empty 183 * {@code Set} if there are none. 184 * 185 * @throws ClosedChannelException 186 * If this channel is closed 187 * 188 * @throws IOException 189 * If some other I/O error occurs 190 */ associations()191 public abstract Set<Association> associations() 192 throws IOException; 193 194 /** 195 * Binds the channel's socket to a local address and configures the socket 196 * to listen for connections. 197 * 198 * <P> This method is used to establish a relationship between the socket 199 * and the local address. Once a relationship is established then 200 * the socket remains bound until the channel is closed. This relationship 201 * may not necesssarily be with the address {@code local} as it may be removed 202 * by {@link #unbindAddress unbindAddress}, but there will always be at least one local 203 * address bound to the channel's socket once an invocation of this method 204 * successfully completes. 205 * 206 * <P> Once the channel's socket has been successfully bound to a specific 207 * address, that is not automatically assigned, more addresses 208 * may be bound to it using {@link #bindAddress bindAddress}, or removed 209 * using {@link #unbindAddress unbindAddress}. 210 * 211 * <P> The backlog parameter is the maximum number of pending connections on 212 * the socket. Its exact semantics are implementation specific. An implementation 213 * may impose an implementation specific maximum length or may choose to ignore 214 * the parameter. If the backlog parameter has the value {@code 0}, or a negative 215 * value, then an implementation specific default is used. 216 * 217 * @param local 218 * The local address to bind the socket, or {@code null} to 219 * bind the socket to an automatically assigned socket address 220 * 221 * @param backlog 222 * The maximum number number of pending connections 223 * 224 * @return This channel 225 * 226 * @throws ClosedChannelException 227 * If this channel is closed 228 * 229 * @throws java.nio.channels.AlreadyBoundException 230 * If this channel is already bound 231 * 232 * @throws java.nio.channels.UnsupportedAddressTypeException 233 * If the type of the given address is not supported 234 * 235 * @throws SecurityException 236 * If a security manager has been installed and its {@link 237 * java.lang.SecurityManager#checkListen(int) checkListen} method 238 * denies the operation 239 * 240 * @throws IOException 241 * If some other I/O error occurs 242 */ bind(SocketAddress local, int backlog)243 public abstract SctpMultiChannel bind(SocketAddress local, 244 int backlog) 245 throws IOException; 246 247 /** 248 * Binds the channel's socket to a local address and configures the socket 249 * to listen for connections. 250 * 251 * <P> This method works as if invoking it were equivalent to evaluating the 252 * expression: 253 * <blockquote><pre> 254 * bind(local, 0); 255 * </pre></blockquote> 256 * 257 * @param local 258 * The local address to bind the socket, or {@code null} to 259 * bind the socket to an automatically assigned socket address 260 * 261 * @return This channel 262 * 263 * @throws ClosedChannelException 264 * If this channel is closed 265 * 266 * @throws java.nio.channels.AlreadyBoundException 267 * If this channel is already bound 268 * 269 * @throws java.nio.channels.UnsupportedAddressTypeException 270 * If the type of the given address is not supported 271 * 272 * @throws SecurityException 273 * If a security manager has been installed and its {@link 274 * java.lang.SecurityManager#checkListen(int) checkListen} method 275 * denies the operation 276 * 277 * @throws IOException 278 * If some other I/O error occurs 279 */ bind(SocketAddress local)280 public final SctpMultiChannel bind(SocketAddress local) 281 throws IOException { 282 return bind(local, 0); 283 } 284 285 /** 286 * Adds the given address to the bound addresses for the channel's 287 * socket. 288 * 289 * <P> The given address must not be the {@link 290 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 291 * The channel must be first bound using {@link #bind bind} before 292 * invoking this method, otherwise {@link NotYetBoundException} is thrown. 293 * The {@link #bind bind} method takes a {@code SocketAddress} as its 294 * argument which typically contains a port number as well as an address. 295 * Addresses subquently bound using this method are simply addresses as the 296 * SCTP port number remains the same for the lifetime of the channel. 297 * 298 * <P> New associations setup after this method successfully completes 299 * will be associated with the given address. Adding addresses to existing 300 * associations is optional functionality. If the endpoint supports 301 * dynamic address reconfiguration then it may send the appropriate message 302 * to the peer to change the peers address lists. 303 * 304 * @param address 305 * The address to add to the bound addresses for the socket 306 * 307 * @return This channel 308 * 309 * @throws ClosedChannelException 310 * If this channel is closed 311 * 312 * @throws NotYetBoundException 313 * If this channel is not yet bound 314 * 315 * @throws java.nio.channels.AlreadyBoundException 316 * If this channel is already bound to the given address 317 * 318 * @throws IllegalArgumentException 319 * If address is {@code null} or the {@link 320 * java.net.InetAddress#isAnyLocalAddress wildcard} address 321 * 322 * @throws IOException 323 * If some other I/O error occurs 324 */ bindAddress(InetAddress address)325 public abstract SctpMultiChannel bindAddress(InetAddress address) 326 throws IOException; 327 328 /** 329 * Removes the given address from the bound addresses for the channel's 330 * socket. 331 * 332 * <P> The given address must not be the {@link 333 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 334 * The channel must be first bound using {@link #bind bind} before 335 * invoking this method, otherwise {@link NotYetBoundException} is thrown. 336 * 337 * <P> If this method is invoked on a channel that does 338 * not have {@code address} as one of its bound addresses, or that has only 339 * one local address bound to it, then this method throws 340 * {@link IllegalUnbindException}. 341 * 342 * <P> The initial address that the channel's socket is bound to using 343 * {@link #bind bind} may be removed from the bound addresses for the 344 * channel's socket. 345 * 346 * <P> New associations setup after this method successfully completes 347 * will not be associated with the given address. Removing addresses from 348 * existing associations is optional functionality. If the endpoint supports 349 * dynamic address reconfiguration then it may send the appropriate message 350 * to the peer to change the peers address lists. 351 * 352 * @param address 353 * The address to remove from the bound addresses for the socket 354 * 355 * @return This channel 356 * 357 * @throws ClosedChannelException 358 * If this channel is closed 359 * 360 * @throws NotYetBoundException 361 * If this channel is not yet bound 362 * 363 * @throws IllegalUnbindException 364 * {@code address} is not bound to the channel's socket, or the 365 * channel has only one address bound to it 366 * 367 * @throws IllegalArgumentException 368 * If address is {@code null} or the {@link 369 * java.net.InetAddress#isAnyLocalAddress wildcard} address 370 * 371 * @throws IOException 372 * If some other I/O error occurs 373 */ unbindAddress(InetAddress address)374 public abstract SctpMultiChannel unbindAddress(InetAddress address) 375 throws IOException; 376 377 /** 378 * Returns all of the socket addresses to which this channel's socket is 379 * bound. 380 * 381 * @return All the socket addresses that this channel's socket is 382 * bound to, or an empty {@code Set} if the channel's socket is not 383 * bound 384 * 385 * @throws ClosedChannelException 386 * If the channel is closed 387 * 388 * @throws IOException 389 * If an I/O error occurs 390 */ getAllLocalAddresses()391 public abstract Set<SocketAddress> getAllLocalAddresses() 392 throws IOException; 393 394 /** 395 * Returns all of the remote addresses to which the given association on 396 * this channel's socket is connected. 397 * 398 * @param association 399 * The association 400 * 401 * @return All of the remote addresses for the given association, or 402 * an empty {@code Set} if the association has been shutdown 403 * 404 * @throws ClosedChannelException 405 * If the channel is closed 406 * 407 * @throws IOException 408 * If an I/O error occurs 409 */ getRemoteAddresses(Association association)410 public abstract Set<SocketAddress> getRemoteAddresses(Association association) 411 throws IOException; 412 413 /** 414 * Shutdown an association without closing the channel. 415 * 416 * @param association 417 * The association to shutdown 418 * 419 * @return This channel 420 * 421 * @throws ClosedChannelException 422 * If this channel is closed 423 * 424 * @throws IOException 425 * If some other I/O error occurs 426 */ shutdown(Association association)427 public abstract SctpMultiChannel shutdown(Association association) 428 throws IOException; 429 430 /** 431 * Returns the value of a socket option. 432 * 433 * <P> Note that some options are retrieved on the channel's socket, 434 * therefore the {@code association} parameter is not applicable and will be 435 * ignored if given. However, if the option is association specific then the 436 * association must be given. 437 * 438 * @param <T> 439 * The type of the socket option value 440 * 441 * @param name 442 * The socket option 443 * 444 * @param association 445 * The association whose option should be retrieved, or {@code null} 446 * if this option should be retrieved at the channel's socket level. 447 * 448 * @return The value of the socket option. A value of {@code null} may be 449 * a valid value for some socket options. 450 * 451 * @throws UnsupportedOperationException 452 * If the socket option is not supported by this channel 453 * 454 * @throws ClosedChannelException 455 * If this channel is closed 456 * 457 * @throws IOException 458 * If an I/O error occurs 459 * 460 * @see SctpStandardSocketOptions 461 */ getOption(SctpSocketOption<T> name, Association association)462 public abstract <T> T getOption(SctpSocketOption<T> name, 463 Association association) 464 throws IOException; 465 466 /** 467 * Sets the value of a socket option. 468 * 469 * <P> Note that some options are retrieved on the channel's socket, 470 * therefore the {@code association} parameter is not applicable and will be 471 * ignored if given. However, if the option is association specific then the 472 * association must be given. 473 * 474 * @param <T> 475 * The type of the socket option value 476 * 477 * @param name 478 * The socket option 479 * 480 * @param association 481 * The association whose option should be set, or {@code null} 482 * if this option should be set at the channel's socket level. 483 * 484 * @param value 485 * The value of the socket option. A value of {@code null} may be 486 * a valid value for some socket options. 487 * 488 * @return This channel 489 * 490 * @throws UnsupportedOperationException 491 * If the socket option is not supported by this channel 492 * 493 * @throws IllegalArgumentException 494 * If the value is not a valid value for this socket option 495 * 496 * @throws ClosedChannelException 497 * If this channel is closed 498 * 499 * @throws IOException 500 * If an I/O error occurs 501 * 502 * @see SctpStandardSocketOptions 503 */ setOption(SctpSocketOption<T> name, T value, Association association)504 public abstract <T> SctpMultiChannel setOption(SctpSocketOption<T> name, 505 T value, 506 Association association) 507 throws IOException; 508 509 /** 510 * Returns a set of the socket options supported by this channel. 511 * 512 * <P> This method will continue to return the set of options even after the 513 * channel has been closed. 514 * 515 * @return A set of the socket options supported by this channel 516 */ supportedOptions()517 public abstract Set<SctpSocketOption<?>> supportedOptions(); 518 519 /** 520 * Returns an operation set identifying this channel's supported operations. 521 * 522 * <P> SCTP multi channels support reading, and writing, so this 523 * method returns 524 * {@code (}{@link SelectionKey#OP_READ} {@code |} {@link 525 * SelectionKey#OP_WRITE}{@code )}. </p> 526 * 527 * @return The valid-operation set 528 */ 529 @Override validOps()530 public final int validOps() { 531 return (SelectionKey.OP_READ | 532 SelectionKey.OP_WRITE ); 533 } 534 535 /** 536 * Receives a message and/or handles a notification via this channel. 537 * 538 * <P> If a message or notification is immediately available, or if this 539 * channel is in blocking mode and one eventually becomes available, then 540 * the message or notification is returned or handled, respectively. If this 541 * channel is in non-blocking mode and a message or notification is not 542 * immediately available then this method immediately returns {@code null}. 543 * 544 * <P> If this method receives a message it is copied into the given byte 545 * buffer and an {@link MessageInfo} is returned. 546 * The message is transferred into the given byte buffer starting at its 547 * current position and the buffers position is incremented by the number of 548 * bytes read. If there are fewer bytes remaining in the buffer than are 549 * required to hold the message, or the underlying input buffer does not 550 * contain the complete message, then an invocation of {@link 551 * MessageInfo#isComplete isComplete} on the returned {@code 552 * MessageInfo} will return {@code false}, and more invocations of this 553 * method will be necessary to completely consume the messgae. Only 554 * one message at a time will be partially delivered in any stream. The 555 * socket option {@link SctpStandardSocketOptions#SCTP_FRAGMENT_INTERLEAVE 556 * SCTP_FRAGMENT_INTERLEAVE} controls various aspects of what interlacing of 557 * messages occurs. 558 * 559 * <P> If this method receives a notification then the appropriate method of 560 * the given handler, if there is one, is invoked. If the handler returns {@link 561 * HandlerResult#CONTINUE CONTINUE} then this method will try to receive another 562 * message/notification, otherwise, if {@link HandlerResult#RETURN RETURN} is returned 563 * this method will return {@code null}. If an uncaught exception is thrown by the 564 * handler it will be propagated up the stack through this method. 565 * 566 * <P> If a security manager has been installed then for each new association 567 * setup this method verifies that the associations source address and port 568 * number are permitted by the security manager's {@link 569 * java.lang.SecurityManager#checkAccept(String,int) checkAccept} method. 570 * 571 * <P> This method may be invoked at any time. If another thread has 572 * already initiated a receive operation upon this channel, then an 573 * invocation of this method will block until the first operation is 574 * complete. The given handler is invoked without holding any locks used 575 * to enforce the above synchronization policy, that way handlers 576 * will not stall other threads from receiving. A handler should not invoke 577 * the {@code receive} method of this channel, if it does an 578 * {@link IllegalReceiveException} will be thrown. 579 * 580 * @param <T> 581 * The type of the attachment 582 * 583 * @param buffer 584 * The buffer into which bytes are to be transferred 585 * 586 * @param attachment 587 * The object to attach to the receive operation; can be 588 * {@code null} 589 * 590 * @param handler 591 * A handler to handle notifications from the SCTP stack, or 592 * {@code null} to ignore any notifications. 593 * 594 * @return The {@code MessageInfo}, {@code null} if this channel is in 595 * non-blocking mode and no messages are immediately available or 596 * the notification handler returns {@code RETURN} after handling 597 * a notification 598 * 599 * @throws java.nio.channels.ClosedChannelException 600 * If this channel is closed 601 * 602 * @throws java.nio.channels.AsynchronousCloseException 603 * If another thread closes this channel 604 * while the read operation is in progress 605 * 606 * @throws java.nio.channels.ClosedByInterruptException 607 * If another thread interrupts the current thread 608 * while the read operation is in progress, thereby 609 * closing the channel and setting the current thread's 610 * interrupt status 611 * 612 * @throws NotYetBoundException 613 * If this channel is not yet bound 614 * 615 * @throws IllegalReceiveException 616 * If the given handler invokes the {@code receive} method of this 617 * channel 618 * 619 * @throws SecurityException 620 * If a security manager has been installed and it does not permit 621 * new associations to be accepted from the message's sender 622 * 623 * @throws IOException 624 * If some other I/O error occurs 625 */ receive(ByteBuffer buffer, T attachment, NotificationHandler<T> handler)626 public abstract <T> MessageInfo receive(ByteBuffer buffer, 627 T attachment, 628 NotificationHandler<T> handler) 629 throws IOException; 630 631 /** 632 * Sends a message via this channel. 633 * 634 * <P> If this channel is unbound then this method will invoke {@link 635 * #bind(SocketAddress, int) bind(null, 0)} before sending any data. 636 * 637 * <P> If there is no association existing between this channel's socket 638 * and the intended receiver, identified by the address in the given messageInfo, then one 639 * will be automatically setup to the intended receiver. This is considered 640 * to be Implicit Association Setup. Upon successful association setup, an 641 * {@link AssociationChangeNotification association changed} 642 * notification will be put to the SCTP stack with its {@code event} parameter set 643 * to {@link AssociationChangeNotification.AssocChangeEvent#COMM_UP COMM_UP} 644 * . This notification can be received by invoking {@link #receive 645 * receive}. 646 * 647 * <P> If this channel is in blocking mode, there is sufficient room in the 648 * underlying output buffer, then the remaining bytes in the given byte 649 * buffer are transmitted as a single message. Sending a message 650 * is atomic unless explicit message completion {@link 651 * SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE SCTP_EXPLICIT_COMPLETE} 652 * socket option is enabled on this channel's socket. 653 * 654 * <P> If this channel is in non-blocking mode, there is sufficient room 655 * in the underlying output buffer, and an implicit association setup is 656 * required, then the remaining bytes in the given byte buffer are 657 * transmitted as a single message, subject to {@link 658 * SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE SCTP_EXPLICIT_COMPLETE}. 659 * If for any reason the message cannot 660 * be delivered an {@link AssociationChangeNotification association 661 * changed} notification is put on the SCTP stack with its {@code event} parameter set 662 * to {@link AssociationChangeNotification.AssocChangeEvent#CANT_START CANT_START}. 663 * 664 * <P> The message is transferred from the byte buffer as if by a regular 665 * {@link java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 666 * write} operation. 667 * 668 * <P> If a security manager has been installed then for each new association 669 * setup this method verifies that the given remote peers address and port 670 * number are permitted by the security manager's {@link 671 * java.lang.SecurityManager#checkConnect(String,int) checkConnect} method. 672 * 673 * <P> This method may be invoked at any time. If another thread has already 674 * initiated a send operation upon this channel, then an invocation of 675 * this method will block until the first operation is complete. 676 * 677 * @param buffer 678 * The buffer containing the message to be sent 679 * 680 * @param messageInfo 681 * Ancillary data about the message to be sent 682 * 683 * @return The number of bytes sent, which will be either the number of 684 * bytes that were remaining in the messages buffer when this method 685 * was invoked or, if this channel is non-blocking, may be zero if 686 * there was insufficient room for the message in the underlying 687 * output buffer 688 * 689 * @throws InvalidStreamException 690 * If {@code streamNumber} is negative, or if an association already 691 * exists and {@code streamNumber} is greater than the maximum number 692 * of outgoing streams 693 * 694 * @throws java.nio.channels.ClosedChannelException 695 * If this channel is closed 696 * 697 * @throws java.nio.channels.AsynchronousCloseException 698 * If another thread closes this channel 699 * while the read operation is in progress 700 * 701 * @throws java.nio.channels.ClosedByInterruptException 702 * If another thread interrupts the current thread 703 * while the read operation is in progress, thereby 704 * closing the channel and setting the current thread's 705 * interrupt status 706 * 707 * @throws SecurityException 708 * If a security manager has been installed and it does not permit 709 * new associations to be setup with the the messages's address 710 * 711 * @throws IOException 712 * If some other I/O error occurs 713 */ send(ByteBuffer buffer, MessageInfo messageInfo)714 public abstract int send(ByteBuffer buffer, MessageInfo messageInfo) 715 throws IOException; 716 717 /** 718 * Branches off an association. 719 * 720 * <P> An application can invoke this method to branch off an association 721 * into a separate channel. The new bound and connected {@link SctpChannel} 722 * will be created for the association. The branched off association will no 723 * longer be part of this channel. 724 * 725 * <P> This is particularly useful when, for instance, the application 726 * wishes to have a number of sporadic message senders/receivers remain 727 * under the original SCTP multi channel but branch off those 728 * associations carrying high volume data traffic into their own 729 * separate SCTP channels. 730 * 731 * @param association 732 * The association to branch off 733 * 734 * @return The {@code SctpChannel} 735 * 736 * @throws java.nio.channels.ClosedChannelException 737 * If this channel is closed 738 * 739 * @throws IOException 740 * If some other I/O error occurs 741 */ branch(Association association)742 public abstract SctpChannel branch(Association association) 743 throws IOException; 744 } 745