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