1 /* 2 * Copyright (c) 2009, 2017, 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 class="striped"><caption style="display:none">Socket options</caption> 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 * @throws SecurityException 280 * If a security manager has been installed and its 281 * {@link SecurityManager#checkListen checkListen} method denies 282 * the operation 283 */ 284 public abstract SctpChannel bind(SocketAddress local) 285 throws IOException; 286 287 /** 288 * Adds the given address to the bound addresses for the channel's 289 * socket. 290 * 291 * <P> The given address must not be the {@link 292 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 293 * The channel must be first bound using {@link #bind bind} before 294 * invoking this method, otherwise {@link 295 * java.nio.channels.NotYetBoundException} is thrown. The {@link #bind bind} 296 * method takes a {@code SocketAddress} as its argument which typically 297 * contains a port number as well as an address. Addresses subquently bound 298 * using this method are simply addresses as the SCTP port number remains 299 * the same for the lifetime of the channel. 300 * 301 * <P> Adding addresses to a connected association is optional functionality. 302 * If the endpoint supports dynamic address reconfiguration then it may 303 * send the appropriate message to the peer to change the peers address 304 * lists. 305 * 306 * @param address 307 * The address to add to the bound addresses for the socket 308 * 309 * @return This channel 310 * 311 * @throws java.nio.channels.ClosedChannelException 312 * If this channel is closed 313 * 314 * @throws java.nio.channels.ConnectionPendingException 315 * If a non-blocking connection operation is already in progress on 316 * this channel 317 * 318 * @throws java.nio.channels.NotYetBoundException 319 * If this channel is not yet bound 320 * 321 * @throws java.nio.channels.AlreadyBoundException 322 * If this channel is already bound to the given address 323 * 324 * @throws IllegalArgumentException 325 * If address is {@code null} or the {@link 326 * java.net.InetAddress#isAnyLocalAddress wildcard} address 327 * 328 * @throws IOException 329 * If some other I/O error occurs 330 */ 331 public abstract SctpChannel bindAddress(InetAddress address) 332 throws IOException; 333 334 /** 335 * Removes the given address from the bound addresses for the channel's 336 * socket. 337 * 338 * <P> The given address must not be the {@link 339 * java.net.InetAddress#isAnyLocalAddress wildcard} address. 340 * The channel must be first bound using {@link #bind bind} before 341 * invoking this method, otherwise {@link java.nio.channels.NotYetBoundException} 342 * is thrown. If this method is invoked on a channel that does not have 343 * {@code address} as one of its bound addresses or that has only one 344 * local address bound to it, then this method throws 345 * {@link IllegalUnbindException}. 346 * The initial address that the channel's socket is bound to using {@link 347 * #bind bind} may be removed from the bound addresses for the channel's socket. 348 * 349 * <P> Removing addresses from a connected association is optional 350 * functionality. If the endpoint supports dynamic address reconfiguration 351 * then it may send the appropriate message to the peer to change the peers 352 * address lists. 353 * 354 * @param address 355 * The address to remove from the bound addresses for the socket 356 * 357 * @return This channel 358 * 359 * @throws java.nio.channels.ClosedChannelException 360 * If this channel is closed 361 * 362 * @throws java.nio.channels.ConnectionPendingException 363 * If a non-blocking connection operation is already in progress on 364 * this channel 365 * 366 * @throws java.nio.channels.NotYetBoundException 367 * If this channel is not yet bound 368 * 369 * @throws IllegalArgumentException 370 * If address is {@code null} or the {@link 371 * java.net.InetAddress#isAnyLocalAddress wildcard} address 372 * 373 * @throws IllegalUnbindException 374 * If {@code address} is not bound to the channel's socket. or 375 * the channel has only one address bound to it 376 * 377 * @throws IOException 378 * If some other I/O error occurs 379 */ 380 public abstract SctpChannel unbindAddress(InetAddress address) 381 throws IOException; 382 383 /** 384 * Connects this channel's socket. 385 * 386 * <P> If this channel is in non-blocking mode then an invocation of this 387 * method initiates a non-blocking connection operation. If the connection 388 * is established immediately, as can happen with a local connection, then 389 * this method returns {@code true}. Otherwise this method returns 390 * {@code false} and the connection operation must later be completed by 391 * invoking the {@link #finishConnect finishConnect} method. 392 * 393 * <P> If this channel is in blocking mode then an invocation of this 394 * method will block until the connection is established or an I/O error 395 * occurs. 396 * 397 * <P> If a security manager has been installed then this method verifies 398 * that its {@link java.lang.SecurityManager#checkConnect checkConnect} 399 * method permits connecting to the address and port number of the given 400 * remote peer. 401 * 402 * <p> This method may be invoked at any time. If a {@link #send send} or 403 * {@link #receive receive} operation upon this channel is invoked while an 404 * invocation of this method is in progress then that operation will first 405 * block until this invocation is complete. If a connection attempt is 406 * initiated but fails, that is, if an invocation of this method throws a 407 * checked exception, then the channel will be closed. 408 * 409 * @param remote 410 * The remote peer to which this channel is to be connected 411 * 412 * @return {@code true} if a connection was established, {@code false} if 413 * this channel is in non-blocking mode and the connection 414 * operation is in progress 415 * 416 * @throws java.nio.channels.AlreadyConnectedException 417 * If this channel is already connected 418 * 419 * @throws java.nio.channels.ConnectionPendingException 420 * If a non-blocking connection operation is already in progress on 421 * this channel 422 * 423 * @throws java.nio.channels.ClosedChannelException 424 * If this channel is closed 425 * 426 * @throws java.nio.channels.AsynchronousCloseException 427 * If another thread closes this channel 428 * while the connect operation is in progress 429 * 430 * @throws java.nio.channels.ClosedByInterruptException 431 * If another thread interrupts the current thread 432 * while the connect operation is in progress, thereby 433 * closing the channel and setting the current thread's 434 * interrupt status 435 * 436 * @throws java.nio.channels.UnresolvedAddressException 437 * If the given remote address is not fully resolved 438 * 439 * @throws java.nio.channels.UnsupportedAddressTypeException 440 * If the type of the given remote address is not supported 441 * 442 * @throws SecurityException 443 * If a security manager has been installed 444 * and it does not permit access to the given remote peer 445 * 446 * @throws IOException 447 * If some other I/O error occurs 448 */ 449 public abstract boolean connect(SocketAddress remote) throws IOException; 450 451 /** 452 * Connects this channel's socket. 453 * 454 * <P> This is a convience method and is equivalent to evaluating the 455 * following expression: 456 * <blockquote><pre> 457 * setOption(SctpStandardSocketOptions.SCTP_INIT_MAXSTREAMS, SctpStandardSocketOption.InitMaxStreams.create(maxInStreams, maxOutStreams)) 458 * .connect(remote); 459 * </pre></blockquote> 460 * 461 * <P> The {@code maxOutStreams} and {@code maxInStreams} parameters 462 * represent the maximum number of streams that the application wishes to be 463 * able to send to and receive from. They are negotiated with the remote 464 * peer and may be limited by the operating system. 465 * 466 * @param remote 467 * The remote peer to which this channel is to be connected 468 * 469 * @param maxOutStreams 470 * Must be non negative and no larger than {@code 65536}. 471 * {@code 0} to use the endpoints default value. 472 * 473 * @param maxInStreams 474 * Must be non negative and no larger than {@code 65536}. 475 * {@code 0} to use the endpoints default value. 476 * 477 * @return {@code true} if a connection was established, {@code false} if 478 * this channel is in non-blocking mode and the connection operation 479 * is in progress 480 * 481 * @throws java.nio.channels.AlreadyConnectedException 482 * If this channel is already connected 483 * 484 * @throws java.nio.channels.ConnectionPendingException 485 * If a non-blocking connection operation is already in progress on 486 * this channel 487 * 488 * @throws java.nio.channels.ClosedChannelException 489 * If this channel is closed 490 * 491 * @throws java.nio.channels.AsynchronousCloseException 492 * If another thread closes this channel 493 * while the connect operation is in progress 494 * 495 * @throws java.nio.channels.ClosedByInterruptException 496 * If another thread interrupts the current thread 497 * while the connect operation is in progress, thereby 498 * closing the channel and setting the current thread's 499 * interrupt status 500 * 501 * @throws java.nio.channels.UnresolvedAddressException 502 * If the given remote address is not fully resolved 503 * 504 * @throws java.nio.channels.UnsupportedAddressTypeException 505 * If the type of the given remote address is not supported 506 * 507 * @throws SecurityException 508 * If a security manager has been installed 509 * and it does not permit access to the given remote peer 510 * 511 * @throws IOException 512 * If some other I/O error occurs 513 */ 514 public abstract boolean connect(SocketAddress remote, 515 int maxOutStreams, 516 int maxInStreams) 517 throws IOException; 518 519 /** 520 * Tells whether or not a connection operation is in progress on this channel. 521 * 522 * @return {@code true} if, and only if, a connection operation has been initiated 523 * on this channel but not yet completed by invoking the 524 * {@link #finishConnect} method 525 */ 526 public abstract boolean isConnectionPending(); 527 528 /** 529 * Finishes the process of connecting an SCTP channel. 530 * 531 * <P> A non-blocking connection operation is initiated by placing a socket 532 * channel in non-blocking mode and then invoking one of its {@link #connect 533 * connect} methods. Once the connection is established, or the attempt has 534 * failed, the channel will become connectable and this method may 535 * be invoked to complete the connection sequence. If the connection 536 * operation failed then invoking this method will cause an appropriate 537 * {@link java.io.IOException} to be thrown. 538 * 539 * <P> If this channel is already connected then this method will not block 540 * and will immediately return {@code true}. If this channel is in 541 * non-blocking mode then this method will return {@code false} if the 542 * connection process is not yet complete. If this channel is in blocking 543 * mode then this method will block until the connection either completes 544 * or fails, and will always either return {@code true} or throw a checked 545 * exception describing the failure. 546 * 547 * <P> This method may be invoked at any time. If a {@link #send send} or {@link #receive receive} 548 * operation upon this channel is invoked while an invocation of this 549 * method is in progress then that operation will first block until this 550 * invocation is complete. If a connection attempt fails, that is, if an 551 * invocation of this method throws a checked exception, then the channel 552 * will be closed. 553 * 554 * @return {@code true} if, and only if, this channel's socket is now 555 * connected 556 * 557 * @throws java.nio.channels.NoConnectionPendingException 558 * If this channel is not connected and a connection operation 559 * has not been initiated 560 * 561 * @throws java.nio.channels.ClosedChannelException 562 * If this channel is closed 563 * 564 * @throws java.nio.channels.AsynchronousCloseException 565 * If another thread closes this channel 566 * while the connect operation is in progress 567 * 568 * @throws java.nio.channels.ClosedByInterruptException 569 * If another thread interrupts the current thread 570 * while the connect operation is in progress, thereby 571 * closing the channel and setting the current thread's 572 * interrupt status 573 * 574 * @throws IOException 575 * If some other I/O error occurs 576 */ 577 public abstract boolean finishConnect() throws IOException; 578 579 /** 580 * Returns all of the socket addresses to which this channel's socket is 581 * bound. 582 * 583 * @return All the socket addresses that this channel's socket is 584 * bound to, or an empty {@code Set} if the channel's socket is not 585 * bound 586 * 587 * @throws ClosedChannelException 588 * If the channel is closed 589 * 590 * @throws IOException 591 * If an I/O error occurs 592 */ 593 public abstract Set<SocketAddress> getAllLocalAddresses() 594 throws IOException; 595 596 /** 597 * Returns all of the remote addresses to which this channel's socket 598 * is connected. 599 * 600 * <P> If the channel is connected to a remote peer that is bound to 601 * multiple addresses then it is these addresses that the channel's socket 602 * is connected. 603 * 604 * @return All of the remote addresses to which this channel's socket 605 * is connected, or an empty {@code Set} if the channel's socket is 606 * not connected 607 * 608 * @throws ClosedChannelException 609 * If the channel is closed 610 * 611 * @throws IOException 612 * If an I/O error occurs 613 */ 614 public abstract Set<SocketAddress> getRemoteAddresses() 615 throws IOException; 616 617 /** 618 * Shutdown a connection without closing the channel. 619 * 620 * <P> Sends a shutdown command to the remote peer, effectively preventing 621 * any new data from being written to the socket by either peer. Further 622 * sends will throw {@link java.nio.channels.ClosedChannelException}. The 623 * channel remains open to allow the for any data (and notifications) to be 624 * received that may have been sent by the peer before it received the 625 * shutdown command. If the channel is already shutdown then invoking this 626 * method has no effect. 627 * 628 * @return This channel 629 * 630 * @throws java.nio.channels.NotYetConnectedException 631 * If this channel is not yet connected 632 * 633 * @throws java.nio.channels.ClosedChannelException 634 * If this channel is closed 635 * 636 * @throws IOException 637 * If some other I/O error occurs 638 */ 639 public abstract SctpChannel shutdown() throws IOException; 640 641 /** 642 * Returns the value of a socket option. 643 * 644 * @param <T> 645 * The type of the socket option value 646 * 647 * @param name 648 * The socket option 649 * 650 * @return The value of the socket option. A value of {@code null} may be 651 * a valid value for some socket options. 652 * 653 * @throws UnsupportedOperationException 654 * If the socket option is not supported by this channel 655 * 656 * @throws ClosedChannelException 657 * If this channel is closed 658 * 659 * @throws IOException 660 * If an I/O error occurs 661 * 662 * @see SctpStandardSocketOptions 663 */ 664 public abstract <T> T getOption(SctpSocketOption<T> name) 665 throws IOException; 666 667 /** 668 * Sets the value of a socket option. 669 * 670 * @param <T> 671 * The type of the socket option value 672 * 673 * @param name 674 * The socket option 675 * 676 * @param value 677 * The value of the socket option. A value of {@code null} may be 678 * a valid value for some socket options. 679 * 680 * @return This channel 681 * 682 * @throws UnsupportedOperationException 683 * If the socket option is not supported by this channel 684 * 685 * @throws IllegalArgumentException 686 * If the value is not a valid value for this socket option 687 * 688 * @throws ClosedChannelException 689 * If this channel is closed 690 * 691 * @throws IOException 692 * If an I/O error occurs 693 * 694 * @see SctpStandardSocketOptions 695 */ 696 public abstract <T> SctpChannel setOption(SctpSocketOption<T> name, T value) 697 throws IOException; 698 699 /** 700 * Returns a set of the socket options supported by this channel. 701 * 702 * <P> This method will continue to return the set of options even after the 703 * channel has been closed. 704 * 705 * @return A set of the socket options supported by this channel 706 */ 707 public abstract Set<SctpSocketOption<?>> supportedOptions(); 708 709 /** 710 * Returns an operation set identifying this channel's supported operations. 711 * 712 * <P> SCTP channels support connecting, reading, and writing, so this 713 * method returns {@code (}{@link SelectionKey#OP_CONNECT} 714 * {@code |} {@link SelectionKey#OP_READ} {@code |} {@link 715 * SelectionKey#OP_WRITE}{@code )}. 716 * 717 * @return The valid-operation set 718 */ 719 @Override 720 public final int validOps() { 721 return (SelectionKey.OP_READ | 722 SelectionKey.OP_WRITE | 723 SelectionKey.OP_CONNECT); 724 } 725 726 /** 727 * Receives a message into the given buffer and/or handles a notification. 728 * 729 * <P> If a message or notification is immediately available, or if this 730 * channel is in blocking mode and one eventually becomes available, then 731 * the message or notification is returned or handled, respectively. If this 732 * channel is in non-blocking mode and a message or notification is not 733 * immediately available then this method immediately returns {@code null}. 734 * 735 * <P> If this method receives a message it is copied into the given byte 736 * buffer. The message is transferred into the given byte buffer starting at 737 * its current position and the buffers position is incremented by the 738 * number of bytes read. If there are fewer bytes remaining in the buffer 739 * than are required to hold the message, or the underlying input buffer 740 * does not contain the complete message, then an invocation of {@link 741 * MessageInfo#isComplete isComplete} on the returned {@code 742 * MessageInfo} will return {@code false}, and more invocations of this 743 * method will be necessary to completely consume the messgae. Only 744 * one message at a time will be partially delivered in any stream. The 745 * socket option {@link SctpStandardSocketOptions#SCTP_FRAGMENT_INTERLEAVE 746 * SCTP_FRAGMENT_INTERLEAVE} controls various aspects of what interlacing of 747 * messages occurs. 748 * 749 * <P> If this method receives a notification then the appropriate method of 750 * the given handler, if there is one, is invoked. If the handler returns 751 * {@link HandlerResult#CONTINUE CONTINUE} then this method will try to 752 * receive another message/notification, otherwise, if {@link 753 * HandlerResult#RETURN RETURN} is returned this method will return {@code 754 * null}. If an uncaught exception is thrown by the handler it will be 755 * propagated up the stack through this method. 756 * 757 * <P> This method may be invoked at any time. If another thread has 758 * already initiated a receive operation upon this channel, then an 759 * invocation of this method will block until the first operation is 760 * complete. The given handler is invoked without holding any locks used 761 * to enforce the above synchronization policy, that way handlers 762 * will not stall other threads from receiving. A handler should not invoke 763 * the {@code receive} method of this channel, if it does an 764 * {@link IllegalReceiveException} will be thrown. 765 * 766 * @param <T> 767 * The type of the attachment 768 * 769 * @param dst 770 * The buffer into which message bytes are to be transferred 771 * 772 * @param attachment 773 * The object to attach to the receive operation; can be 774 * {@code null} 775 * 776 * @param handler 777 * A handler to handle notifications from the SCTP stack, or {@code 778 * null} to ignore any notifications. 779 * 780 * @return The {@code MessageInfo}, {@code null} if this channel is in 781 * non-blocking mode and no messages are immediately available or 782 * the notification handler returns {@link HandlerResult#RETURN 783 * RETURN} after handling a notification 784 * 785 * @throws java.nio.channels.ClosedChannelException 786 * If this channel is closed 787 * 788 * @throws java.nio.channels.AsynchronousCloseException 789 * If another thread closes this channel 790 * while the read operation is in progress 791 * 792 * @throws java.nio.channels.ClosedByInterruptException 793 * If another thread interrupts the current thread 794 * while the read operation is in progress, thereby 795 * closing the channel and setting the current thread's 796 * interrupt status 797 * 798 * @throws java.nio.channels.NotYetConnectedException 799 * If this channel is not yet connected 800 * 801 * @throws IllegalReceiveException 802 * If the given handler invokes the {@code receive} method of this 803 * channel 804 * 805 * @throws IOException 806 * If some other I/O error occurs 807 */ 808 public abstract <T> MessageInfo receive(ByteBuffer dst, 809 T attachment, 810 NotificationHandler<T> handler) 811 throws IOException; 812 813 /** 814 * Sends a message via this channel. 815 * 816 * <P> If this channel is in non-blocking mode and there is sufficient room 817 * in the underlying output buffer, or if this channel is in blocking mode 818 * and sufficient room becomes available, then the remaining bytes in the 819 * given byte buffer are transmitted as a single message. Sending a message 820 * is atomic unless explicit message completion {@link 821 * SctpStandardSocketOptions#SCTP_EXPLICIT_COMPLETE SCTP_EXPLICIT_COMPLETE} 822 * socket option is enabled on this channel's socket. 823 * 824 * <P> The message is transferred from the byte buffer as if by a regular 825 * {@link java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 826 * write} operation. 827 * 828 * <P> The bytes will be written to the stream number that is specified by 829 * {@link MessageInfo#streamNumber streamNumber} in the given {@code 830 * messageInfo}. 831 * 832 * <P> This method may be invoked at any time. If another thread has already 833 * initiated a send operation upon this channel, then an invocation of 834 * this method will block until the first operation is complete. 835 * 836 * @param src 837 * The buffer containing the message to be sent 838 * 839 * @param messageInfo 840 * Ancillary data about the message to be sent 841 * 842 * @return The number of bytes sent, which will be either the number of 843 * bytes that were remaining in the messages buffer when this method 844 * was invoked or, if this channel is non-blocking, may be zero if 845 * there was insufficient room for the message in the underlying 846 * output buffer 847 * 848 * @throws InvalidStreamException 849 * If {@code streamNumner} is negative or greater than or equal to 850 * the maximum number of outgoing streams 851 * 852 * @throws java.nio.channels.ClosedChannelException 853 * If this channel is closed 854 * 855 * @throws java.nio.channels.AsynchronousCloseException 856 * If another thread closes this channel 857 * while the read operation is in progress 858 * 859 * @throws java.nio.channels.ClosedByInterruptException 860 * If another thread interrupts the current thread 861 * while the read operation is in progress, thereby 862 * closing the channel and setting the current thread's 863 * interrupt status 864 * 865 * @throws java.nio.channels.NotYetConnectedException 866 * If this channel is not yet connected 867 * 868 * @throws IOException 869 * If some other I/O error occurs 870 */ 871 public abstract int send(ByteBuffer src, MessageInfo messageInfo) 872 throws IOException; 873 }