1 /* 2 * Copyright (c) 2009, 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.SelectionKey; 36 37 /** 38 * A selectable channel for message-oriented connected SCTP sockets. 39 * 40 * <P> An SCTP channel can only control one SCTP association. 41 * An {@code SCTPChannel} is created by invoking one of the 42 * {@link #open open} methods of this class. A newly-created channel is open but 43 * not yet connected, that is, there is no association setup with a remote peer. 44 * An attempt to invoke an I/O operation upon an unconnected 45 * channel will cause a {@link java.nio.channels.NotYetConnectedException} to be 46 * thrown. An association can be setup by connecting the channel using one of 47 * its {@link #connect connect} methods. Once connected, the channel remains 48 * connected until it is closed. Whether or not a channel is connected may be 49 * determined by invoking {@link #getRemoteAddresses getRemoteAddresses}. 50 * 51 * <p> SCTP channels support <i>non-blocking connection:</i> A 52 * channel may be created and the process of establishing the link to 53 * the remote socket may be initiated via the {@link #connect connect} method 54 * for later completion by the {@link #finishConnect finishConnect} method. 55 * Whether or not a connection operation is in progress may be determined by 56 * invoking the {@link #isConnectionPending isConnectionPending} method. 57 * 58 * <p> Socket options are configured using the 59 * {@link #setOption(SctpSocketOption,Object) setOption} method. An SCTP 60 * channel support the following options: 61 * <blockquote> 62 * <table border> 63 * <tr> 64 * <th>Option Name</th> 65 * <th>Description</th> 66 * </tr> 67 * <tr> 68 * <td> {@link SctpStandardSocketOptions#SCTP_DISABLE_FRAGMENTS 69 * SCTP_DISABLE_FRAGMENTS} </td> 70 * <td> Enables or disables message fragmentation </td> 71 * </tr> 72 * <tr> 73 * <td> {@link SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE 74 * SCTP_EXPLICIT_COMPLETE} </td> 75 * <td> Enables or disables explicit message completion </td> 76 * </tr> 77 * <tr> 78 * <td> {@link SctpStandardSocketOptions#SCTP_FRAGMENT_INTERLEAVE 79 * SCTP_FRAGMENT_INTERLEAVE} </td> 80 * <td> Controls how the presentation of messages occur for the message 81 * receiver </td> 82 * </tr> 83 * <tr> 84 * <td> {@link SctpStandardSocketOptions#SCTP_INIT_MAXSTREAMS 85 * SCTP_INIT_MAXSTREAMS} </td> 86 * <td> The maximum number of streams requested by the local endpoint during 87 * association initialization </td> 88 * </tr> 89 * <tr> 90 * <td> {@link SctpStandardSocketOptions#SCTP_NODELAY SCTP_NODELAY} </td> 91 * <td> Enables or disable a Nagle-like algorithm </td> 92 * </tr> 93 * <tr> 94 * <td> {@link SctpStandardSocketOptions#SCTP_PRIMARY_ADDR 95 * SCTP_PRIMARY_ADDR} </td> 96 * <td> Requests that the local SCTP stack use the given peer address as the 97 * association primary </td> 98 * </tr> 99 * <tr> 100 * <td> {@link SctpStandardSocketOptions#SCTP_SET_PEER_PRIMARY_ADDR 101 * SCTP_SET_PEER_PRIMARY_ADDR} </td> 102 * <td> Requests that the peer mark the enclosed address as the association 103 * primary </td> 104 * </tr> 105 * <tr> 106 * <td> {@link SctpStandardSocketOptions#SO_SNDBUF 107 * SO_SNDBUF} </td> 108 * <td> The size of the socket send buffer </td> 109 * </tr> 110 * <tr> 111 * <td> {@link SctpStandardSocketOptions#SO_RCVBUF 112 * SO_RCVBUF} </td> 113 * <td> The size of the socket receive buffer </td> 114 * </tr> 115 * <tr> 116 * <td> {@link SctpStandardSocketOptions#SO_LINGER 117 * SO_LINGER} </td> 118 * <td> Linger on close if data is present (when configured in blocking mode 119 * only) </td> 120 * </tr> 121 * </table> 122 * </blockquote> 123 * Additional (implementation specific) options may also be supported. The list 124 * of options supported is obtained by invoking the {@link #supportedOptions() 125 * supportedOptions} method. 126 * 127 * <p> SCTP channels are safe for use by multiple concurrent threads. 128 * They support concurrent reading and writing, though at most one thread may be 129 * reading and at most one thread may be writing at any given time. The 130 * {@link #connect connect} and {@link #finishConnect 131 * finishConnect} methods are mutually synchronized against each other, and 132 * an attempt to initiate a send or receive operation while an invocation of one 133 * of these methods is in progress will block until that invocation is complete. 134 * 135 * @since 1.7 136 */ 137 public abstract class SctpChannel 138 extends AbstractSelectableChannel 139 { 140 /** 141 * Initializes a new instance of this class. 142 * 143 * @param provider 144 * The selector provider for this channel 145 */ 146 protected SctpChannel(SelectorProvider provider) { 147 super(provider); 148 } 149 150 /** 151 * Opens an SCTP channel. 152 * 153 * <P> The new channel is unbound and unconnected. 154 * 155 * @return A new SCTP channel 156 * 157 * @throws UnsupportedOperationException 158 * If the SCTP protocol is not supported 159 * 160 * @throws IOException 161 * If an I/O error occurs 162 */ 163 public static SctpChannel open() throws 164 IOException { 165 return new sun.nio.ch.sctp.SctpChannelImpl((SelectorProvider)null); 166 } 167 168 /** 169 * Opens an SCTP channel and connects it to a remote address. 170 * 171 * <P> This is a convenience method and is equivalent to evaluating the 172 * following expression: 173 * <blockquote><pre> 174 * open().connect(remote, maxOutStreams, maxInStreams); 175 * </pre></blockquote> 176 * 177 * @param remote 178 * The remote address to which the new channel is to be connected 179 * 180 * @param maxOutStreams 181 * The number of streams that the application wishes to be able 182 * to send to. Must be non negative and no larger than {@code 65536}. 183 * {@code 0} to use the endpoints default value. 184 * 185 * @param maxInStreams 186 * The maximum number of inbound streams the application is prepared 187 * to support. Must be non negative and no larger than {@code 65536}. 188 * {@code 0} to use the endpoints default value. 189 * 190 * @return A new SCTP channel connected to the given address 191 * 192 * @throws java.nio.channels.AsynchronousCloseException 193 * If another thread closes this channel 194 * while the connect operation is in progress 195 * 196 * @throws java.nio.channels.ClosedByInterruptException 197 * If another thread interrupts the current thread 198 * while the connect operation is in progress, thereby 199 * closing the channel and setting the current thread's 200 * interrupt status 201 * 202 * @throws java.nio.channels.UnresolvedAddressException 203 * If the given remote address is not fully resolved 204 * 205 * @throws java.nio.channels.UnsupportedAddressTypeException 206 * If the type of the given remote address is not supported 207 * 208 * @throws SecurityException 209 * If a security manager has been installed 210 * and it does not permit access to the given remote peer 211 * 212 * @throws UnsupportedOperationException 213 * If the SCTP protocol is not supported 214 * 215 * @throws IOException 216 * If some other I/O error occurs 217 */ 218 public static SctpChannel open(SocketAddress remote, int maxOutStreams, 219 int maxInStreams) throws IOException { 220 SctpChannel ssc = SctpChannel.open(); 221 ssc.connect(remote, maxOutStreams, maxInStreams); 222 return ssc; 223 } 224 225 /** 226 * Returns the association on this channel's socket. 227 * 228 * @return the association, or {@code null} if the channel's socket is not 229 * connected. 230 * 231 * @throws ClosedChannelException 232 * If the channel is closed 233 * 234 * @throws IOException 235 * If some other I/O error occurs 236 */ 237 public abstract Association association() throws IOException; 238 239 /** 240 * Binds the channel's socket to a local address. 241 * 242 * <P> This method is used to establish a relationship between the socket 243 * and the local addresses. Once a relationship is established then 244 * the socket remains bound until the channel is closed. This relationship 245 * may not necesssarily be with the address {@code local} as it may be removed 246 * by {@link #unbindAddress unbindAddress}, but there will always be at least 247 * one local address bound to the channel's socket once an invocation of 248 * this method successfully completes. 249 * 250 * <P> Once the channel's socket has been successfully bound to a specific 251 * address, that is not automatically assigned, more addresses 252 * may be bound to it using {@link #bindAddress bindAddress}, or removed 253 * using {@link #unbindAddress unbindAddress}. 254 * 255 * @param local 256 * The local address to bind the socket, or {@code null} to 257 * bind the socket to an automatically assigned socket address 258 * 259 * @return This channel 260 * 261 * @throws java.nio.channels.AlreadyConnectedException 262 * If this channel is already connected 263 * 264 * @throws java.nio.channels.ClosedChannelException 265 * If this channel is closed 266 * 267 * @throws java.nio.channels.ConnectionPendingException 268 * If a non-blocking connection operation is already in progress on this channel 269 * 270 * @throws java.nio.channels.AlreadyBoundException 271 * If this channel is already bound 272 * 273 * @throws java.nio.channels.UnsupportedAddressTypeException 274 * If the type of the given address is not supported 275 * 276 * @throws IOException 277 * If some other I/O error occurs 278 */ 279 public abstract SctpChannel bind(SocketAddress local) 280 throws IOException; 281 282 /** 283 * Adds the given address to the bound addresses for the channel's 284 * socket. 285 * 286 * <P> The given address must not be the {@link 287 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 288 * The channel must be first bound using {@link #bind bind} before 289 * invoking this method, otherwise {@link 290 * java.nio.channels.NotYetBoundException} is thrown. The {@link #bind bind} 291 * method takes a {@code SocketAddress} as its argument which typically 292 * contains a port number as well as an address. Addresses subquently bound 293 * using this method are simply addresses as the SCTP port number remains 294 * the same for the lifetime of the channel. 295 * 296 * <P> Adding addresses to a connected association is optional functionality. 297 * If the endpoint supports dynamic address reconfiguration then it may 298 * send the appropriate message to the peer to change the peers address 299 * lists. 300 * 301 * @param address 302 * The address to add to the bound addresses for the socket 303 * 304 * @return This channel 305 * 306 * @throws java.nio.channels.ClosedChannelException 307 * If this channel is closed 308 * 309 * @throws java.nio.channels.ConnectionPendingException 310 * If a non-blocking connection operation is already in progress on 311 * this channel 312 * 313 * @throws java.nio.channels.NotYetBoundException 314 * If this channel is not yet bound 315 * 316 * @throws java.nio.channels.AlreadyBoundException 317 * If this channel is already bound to the given address 318 * 319 * @throws IllegalArgumentException 320 * If address is {@code null} or the {@link 321 * java.net.InetAddress#isAnyLocalAddress wildcard} address 322 * 323 * @throws IOException 324 * If some other I/O error occurs 325 */ 326 public abstract SctpChannel bindAddress(InetAddress address) 327 throws IOException; 328 329 /** 330 * Removes the given address from the bound addresses for the channel's 331 * socket. 332 * 333 * <P> The given address must not be the {@link 334 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 335 * The channel must be first bound using {@link #bind bind} before 336 * invoking this method, otherwise {@link java.nio.channels.NotYetBoundException} 337 * is thrown. If this method is invoked on a channel that does not have 338 * {@code address} as one of its bound addresses or that has only one 339 * local address bound to it, then this method throws 340 * {@link IllegalUnbindException}. 341 * The initial address that the channel's socket is bound to using {@link 342 * #bind bind} may be removed from the bound addresses for the channel's socket. 343 * 344 * <P> Removing addresses from a connected association is optional 345 * functionality. If the endpoint supports dynamic address reconfiguration 346 * then it may send the appropriate message to the peer to change the peers 347 * address lists. 348 * 349 * @param address 350 * The address to remove from the bound addresses for the socket 351 * 352 * @return This channel 353 * 354 * @throws java.nio.channels.ClosedChannelException 355 * If this channel is closed 356 * 357 * @throws java.nio.channels.ConnectionPendingException 358 * If a non-blocking connection operation is already in progress on 359 * this channel 360 * 361 * @throws java.nio.channels.NotYetBoundException 362 * If this channel is not yet bound 363 * 364 * @throws IllegalArgumentException 365 * If address is {@code null} or the {@link 366 * java.net.InetAddress#isAnyLocalAddress wildcard} address 367 * 368 * @throws IllegalUnbindException 369 * If {@code address} is not bound to the channel's socket. or 370 * the channel has only one address bound to it 371 * 372 * @throws IOException 373 * If some other I/O error occurs 374 */ 375 public abstract SctpChannel unbindAddress(InetAddress address) 376 throws IOException; 377 378 /** 379 * Connects this channel's socket. 380 * 381 * <P> If this channel is in non-blocking mode then an invocation of this 382 * method initiates a non-blocking connection operation. If the connection 383 * is established immediately, as can happen with a local connection, then 384 * this method returns {@code true}. Otherwise this method returns 385 * {@code false} and the connection operation must later be completed by 386 * invoking the {@link #finishConnect finishConnect} method. 387 * 388 * <P> If this channel is in blocking mode then an invocation of this 389 * method will block until the connection is established or an I/O error 390 * occurs. 391 * 392 * <P> If a security manager has been installed then this method verifies 393 * that its {@link java.lang.SecurityManager#checkConnect checkConnect} 394 * method permits connecting to the address and port number of the given 395 * remote peer. 396 * 397 * <p> This method may be invoked at any time. If a {@link #send send} or 398 * {@link #receive receive} operation upon this channel is invoked while an 399 * invocation of this method is in progress then that operation will first 400 * block until this invocation is complete. If a connection attempt is 401 * initiated but fails, that is, if an invocation of this method throws a 402 * checked exception, then the channel will be closed. 403 * 404 * @param remote 405 * The remote peer to which this channel is to be connected 406 * 407 * @return {@code true} if a connection was established, {@code false} if 408 * this channel is in non-blocking mode and the connection 409 * operation is in progress 410 * 411 * @throws java.nio.channels.AlreadyConnectedException 412 * If this channel is already connected 413 * 414 * @throws java.nio.channels.ConnectionPendingException 415 * If a non-blocking connection operation is already in progress on 416 * this channel 417 * 418 * @throws java.nio.channels.ClosedChannelException 419 * If this channel is closed 420 * 421 * @throws java.nio.channels.AsynchronousCloseException 422 * If another thread closes this channel 423 * while the connect operation is in progress 424 * 425 * @throws java.nio.channels.ClosedByInterruptException 426 * If another thread interrupts the current thread 427 * while the connect operation is in progress, thereby 428 * closing the channel and setting the current thread's 429 * interrupt status 430 * 431 * @throws java.nio.channels.UnresolvedAddressException 432 * If the given remote address is not fully resolved 433 * 434 * @throws java.nio.channels.UnsupportedAddressTypeException 435 * If the type of the given remote address is not supported 436 * 437 * @throws SecurityException 438 * If a security manager has been installed 439 * and it does not permit access to the given remote peer 440 * 441 * @throws IOException 442 * If some other I/O error occurs 443 */ 444 public abstract boolean connect(SocketAddress remote) throws IOException; 445 446 /** 447 * Connects this channel's socket. 448 * 449 * <P> This is a convience method and is equivalent to evaluating the 450 * following expression: 451 * <blockquote><pre> 452 * setOption(SctpStandardSocketOptions.SCTP_INIT_MAXSTREAMS, SctpStandardSocketOption.InitMaxStreams.create(maxInStreams, maxOutStreams)) 453 * .connect(remote); 454 * </pre></blockquote> 455 * 456 * <P> The {@code maxOutStreams} and {@code maxInStreams} parameters 457 * represent the maximum number of streams that the application wishes to be 458 * able to send to and receive from. They are negotiated with the remote 459 * peer and may be limited by the operating system. 460 * 461 * @param remote 462 * The remote peer to which this channel is to be connected 463 * 464 * @param maxOutStreams 465 * Must be non negative and no larger than {@code 65536}. 466 * {@code 0} to use the endpoints default value. 467 * 468 * @param maxInStreams 469 * Must be non negative and no larger than {@code 65536}. 470 * {@code 0} to use the endpoints default value. 471 * 472 * @return {@code true} if a connection was established, {@code false} if 473 * this channel is in non-blocking mode and the connection operation 474 * is in progress 475 * 476 * @throws java.nio.channels.AlreadyConnectedException 477 * If this channel is already connected 478 * 479 * @throws java.nio.channels.ConnectionPendingException 480 * If a non-blocking connection operation is already in progress on 481 * this channel 482 * 483 * @throws java.nio.channels.ClosedChannelException 484 * If this channel is closed 485 * 486 * @throws java.nio.channels.AsynchronousCloseException 487 * If another thread closes this channel 488 * while the connect operation is in progress 489 * 490 * @throws java.nio.channels.ClosedByInterruptException 491 * If another thread interrupts the current thread 492 * while the connect operation is in progress, thereby 493 * closing the channel and setting the current thread's 494 * interrupt status 495 * 496 * @throws java.nio.channels.UnresolvedAddressException 497 * If the given remote address is not fully resolved 498 * 499 * @throws java.nio.channels.UnsupportedAddressTypeException 500 * If the type of the given remote address is not supported 501 * 502 * @throws SecurityException 503 * If a security manager has been installed 504 * and it does not permit access to the given remote peer 505 * 506 * @throws IOException 507 * If some other I/O error occurs 508 */ 509 public abstract boolean connect(SocketAddress remote, 510 int maxOutStreams, 511 int maxInStreams) 512 throws IOException; 513 514 /** 515 * Tells whether or not a connection operation is in progress on this channel. 516 * 517 * @return {@code true} if, and only if, a connection operation has been initiated 518 * on this channel but not yet completed by invoking the 519 * {@link #finishConnect} method 520 */ 521 public abstract boolean isConnectionPending(); 522 523 /** 524 * Finishes the process of connecting an SCTP channel. 525 * 526 * <P> A non-blocking connection operation is initiated by placing a socket 527 * channel in non-blocking mode and then invoking one of its {@link #connect 528 * connect} methods. Once the connection is established, or the attempt has 529 * failed, the channel will become connectable and this method may 530 * be invoked to complete the connection sequence. If the connection 531 * operation failed then invoking this method will cause an appropriate 532 * {@link java.io.IOException} to be thrown. 533 * 534 * <P> If this channel is already connected then this method will not block 535 * and will immediately return <tt>true</tt>. If this channel is in 536 * non-blocking mode then this method will return <tt>false</tt> if the 537 * connection process is not yet complete. If this channel is in blocking 538 * mode then this method will block until the connection either completes 539 * or fails, and will always either return <tt>true</tt> or throw a checked 540 * exception describing the failure. 541 * 542 * <P> This method may be invoked at any time. If a {@link #send send} or {@link #receive receive} 543 * operation upon this channel is invoked while an invocation of this 544 * method is in progress then that operation will first block until this 545 * invocation is complete. If a connection attempt fails, that is, if an 546 * invocation of this method throws a checked exception, then the channel 547 * will be closed. 548 * 549 * @return {@code true} if, and only if, this channel's socket is now 550 * connected 551 * 552 * @throws java.nio.channels.NoConnectionPendingException 553 * If this channel is not connected and a connection operation 554 * has not been initiated 555 * 556 * @throws java.nio.channels.ClosedChannelException 557 * If this channel is closed 558 * 559 * @throws java.nio.channels.AsynchronousCloseException 560 * If another thread closes this channel 561 * while the connect operation is in progress 562 * 563 * @throws java.nio.channels.ClosedByInterruptException 564 * If another thread interrupts the current thread 565 * while the connect operation is in progress, thereby 566 * closing the channel and setting the current thread's 567 * interrupt status 568 * 569 * @throws IOException 570 * If some other I/O error occurs 571 */ 572 public abstract boolean finishConnect() throws IOException; 573 574 /** 575 * Returns all of the socket addresses to which this channel's socket is 576 * bound. 577 * 578 * @return All the socket addresses that this channel's socket is 579 * bound to, or an empty {@code Set} if the channel's socket is not 580 * bound 581 * 582 * @throws ClosedChannelException 583 * If the channel is closed 584 * 585 * @throws IOException 586 * If an I/O error occurs 587 */ 588 public abstract Set<SocketAddress> getAllLocalAddresses() 589 throws IOException; 590 591 /** 592 * Returns all of the remote addresses to which this channel's socket 593 * is connected. 594 * 595 * <P> If the channel is connected to a remote peer that is bound to 596 * multiple addresses then it is these addresses that the channel's socket 597 * is connected. 598 * 599 * @return All of the remote addresses to which this channel's socket 600 * is connected, or an empty {@code Set} if the channel's socket is 601 * not connected 602 * 603 * @throws ClosedChannelException 604 * If the channel is closed 605 * 606 * @throws IOException 607 * If an I/O error occurs 608 */ 609 public abstract Set<SocketAddress> getRemoteAddresses() 610 throws IOException; 611 612 /** 613 * Shutdown a connection without closing the channel. 614 * 615 * <P> Sends a shutdown command to the remote peer, effectively preventing 616 * any new data from being written to the socket by either peer. Further 617 * sends will throw {@link java.nio.channels.ClosedChannelException}. The 618 * channel remains open to allow the for any data (and notifications) to be 619 * received that may have been sent by the peer before it received the 620 * shutdown command. If the channel is already shutdown then invoking this 621 * method has no effect. 622 * 623 * @return This channel 624 * 625 * @throws java.nio.channels.NotYetConnectedException 626 * If this channel is not yet connected 627 * 628 * @throws java.nio.channels.ClosedChannelException 629 * If this channel is closed 630 * 631 * @throws IOException 632 * If some other I/O error occurs 633 */ 634 public abstract SctpChannel shutdown() throws IOException; 635 636 /** 637 * Returns the value of a socket option. 638 * 639 * @param name 640 * The socket option 641 * 642 * @return The value of the socket option. A value of {@code null} may be 643 * a valid value for some socket options. 644 * 645 * @throws UnsupportedOperationException 646 * If the socket option is not supported by this channel 647 * 648 * @throws ClosedChannelException 649 * If this channel is closed 650 * 651 * @throws IOException 652 * If an I/O error occurs 653 * 654 * @see SctpStandardSocketOptions 655 */ 656 public abstract <T> T getOption(SctpSocketOption<T> name) 657 throws IOException; 658 659 /** 660 * Sets the value of a socket option. 661 * 662 * @param name 663 * The socket option 664 * 665 * @param value 666 * The value of the socket option. A value of {@code null} may be 667 * a valid value for some socket options. 668 * 669 * @return This channel 670 * 671 * @throws UnsupportedOperationException 672 * If the socket option is not supported by this channel 673 * 674 * @throws IllegalArgumentException 675 * If the value is not a valid value for this socket option 676 * 677 * @throws ClosedChannelException 678 * If this channel is closed 679 * 680 * @throws IOException 681 * If an I/O error occurs 682 * 683 * @see SctpStandardSocketOptions 684 */ 685 public abstract <T> SctpChannel setOption(SctpSocketOption<T> name, T value) 686 throws IOException; 687 688 /** 689 * Returns a set of the socket options supported by this channel. 690 * 691 * <P> This method will continue to return the set of options even after the 692 * channel has been closed. 693 * 694 * @return A set of the socket options supported by this channel 695 */ 696 public abstract Set<SctpSocketOption<?>> supportedOptions(); 697 698 /** 699 * Returns an operation set identifying this channel's supported operations. 700 * 701 * <P> SCTP channels support connecting, reading, and writing, so this 702 * method returns <tt>(</tt>{@link SelectionKey#OP_CONNECT} 703 * <tt>|</tt> {@link SelectionKey#OP_READ} <tt>|</tt> {@link 704 * SelectionKey#OP_WRITE}<tt>)</tt>. </p> 705 * 706 * @return The valid-operation set 707 */ 708 @Override 709 public final int validOps() { 710 return (SelectionKey.OP_READ | 711 SelectionKey.OP_WRITE | 712 SelectionKey.OP_CONNECT); 713 } 714 715 /** 716 * Receives a message into the given buffer and/or handles a notification. 717 * 718 * <P> If a message or notification is immediately available, or if this 719 * channel is in blocking mode and one eventually becomes available, then 720 * the message or notification is returned or handled, respectively. If this 721 * channel is in non-blocking mode and a message or notification is not 722 * immediately available then this method immediately returns {@code null}. 723 * 724 * <P> If this method receives a message it is copied into the given byte 725 * buffer. The message is transferred into the given byte buffer starting at 726 * its current position and the buffers position is incremented by the 727 * number of bytes read. If there are fewer bytes remaining in the buffer 728 * than are required to hold the message, or the underlying input buffer 729 * does not contain the complete message, then an invocation of {@link 730 * MessageInfo#isComplete isComplete} on the returned {@code 731 * MessageInfo} will return {@code false}, and more invocations of this 732 * method will be necessary to completely consume the messgae. Only 733 * one message at a time will be partially delivered in any stream. The 734 * socket option {@link SctpStandardSocketOptions#SCTP_FRAGMENT_INTERLEAVE 735 * SCTP_FRAGMENT_INTERLEAVE} controls various aspects of what interlacing of 736 * messages occurs. 737 * 738 * <P> If this method receives a notification then the appropriate method of 739 * the given handler, if there is one, is invoked. If the handler returns 740 * {@link HandlerResult#CONTINUE CONTINUE} then this method will try to 741 * receive another message/notification, otherwise, if {@link 742 * HandlerResult#RETURN RETURN} is returned this method will return {@code 743 * null}. If an uncaught exception is thrown by the handler it will be 744 * propagated up the stack through this method. 745 * 746 * <P> This method may be invoked at any time. If another thread has 747 * already initiated a receive operation upon this channel, then an 748 * invocation of this method will block until the first operation is 749 * complete. The given handler is invoked without holding any locks used 750 * to enforce the above synchronization policy, that way handlers 751 * will not stall other threads from receiving. A handler should not invoke 752 * the {@code receive} method of this channel, if it does an 753 * {@link IllegalReceiveException} will be thrown. 754 * 755 * @param dst 756 * The buffer into which message bytes are to be transferred 757 * 758 * @param attachment 759 * The object to attach to the receive operation; can be 760 * {@code null} 761 * 762 * @param handler 763 * A handler to handle notifications from the SCTP stack, or {@code 764 * null} to ignore any notifications. 765 * 766 * @return The {@code MessageInfo}, {@code null} if this channel is in 767 * non-blocking mode and no messages are immediately available or 768 * the notification handler returns {@link HandlerResult#RETURN 769 * RETURN} after handling a notification 770 * 771 * @throws java.nio.channels.ClosedChannelException 772 * If this channel is closed 773 * 774 * @throws java.nio.channels.AsynchronousCloseException 775 * If another thread closes this channel 776 * while the read operation is in progress 777 * 778 * @throws java.nio.channels.ClosedByInterruptException 779 * If another thread interrupts the current thread 780 * while the read operation is in progress, thereby 781 * closing the channel and setting the current thread's 782 * interrupt status 783 * 784 * @throws java.nio.channels.NotYetConnectedException 785 * If this channel is not yet connected 786 * 787 * @throws IllegalReceiveException 788 * If the given handler invokes the {@code receive} method of this 789 * channel 790 * 791 * @throws IOException 792 * If some other I/O error occurs 793 */ 794 public abstract <T> MessageInfo receive(ByteBuffer dst, 795 T attachment, 796 NotificationHandler<T> handler) 797 throws IOException; 798 799 /** 800 * Sends a message via this channel. 801 * 802 * <P> If this channel is in non-blocking mode and there is sufficient room 803 * in the underlying output buffer, or if this channel is in blocking mode 804 * and sufficient room becomes available, then the remaining bytes in the 805 * given byte buffer are transmitted as a single message. Sending a message 806 * is atomic unless explicit message completion {@link 807 * SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE SCTP_EXPLICIT_COMPLETE} 808 * socket option is enabled on this channel's socket. 809 * 810 * <P> The message is transferred from the byte buffer as if by a regular 811 * {@link java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 812 * write} operation. 813 * 814 * <P> The bytes will be written to the stream number that is specified by 815 * {@link MessageInfo#streamNumber streamNumber} in the given {@code 816 * messageInfo}. 817 * 818 * <P> This method may be invoked at any time. If another thread has already 819 * initiated a send operation upon this channel, then an invocation of 820 * this method will block until the first operation is complete. 821 * 822 * @param src 823 * The buffer containing the message to be sent 824 * 825 * @param messageInfo 826 * Ancillary data about the message to be sent 827 * 828 * @return The number of bytes sent, which will be either the number of 829 * bytes that were remaining in the messages buffer when this method 830 * was invoked or, if this channel is non-blocking, may be zero if 831 * there was insufficient room for the message in the underlying 832 * output buffer 833 * 834 * @throws InvalidStreamExcepton 835 * If {@code streamNumner} is negative or greater than or equal to 836 * the maximum number of outgoing streams 837 * 838 * @throws java.nio.channels.ClosedChannelException 839 * If this channel is closed 840 * 841 * @throws java.nio.channels.AsynchronousCloseException 842 * If another thread closes this channel 843 * while the read operation is in progress 844 * 845 * @throws java.nio.channels.ClosedByInterruptException 846 * If another thread interrupts the current thread 847 * while the read operation is in progress, thereby 848 * closing the channel and setting the current thread's 849 * interrupt status 850 * 851 * @throws java.nio.channels.NotYetConnectedException 852 * If this channel is not yet connected 853 * 854 * @throws IOException 855 * If some other I/O error occurs 856 */ 857 public abstract int send(ByteBuffer src, MessageInfo messageInfo) 858 throws IOException; 859 }