View Javadoc
1   /*
2    * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package com.sun.nio.sctp;
26  
27  import java.net.SocketAddress;
28  import java.net.InetAddress;
29  import java.io.IOException;
30  import java.util.Set;
31  import java.nio.channels.SelectionKey;
32  import java.nio.channels.spi.SelectorProvider;
33  import java.nio.channels.spi.AbstractSelectableChannel;
34  
35  /**
36   * A selectable channel for message-oriented listening SCTP sockets.
37   *
38   * <p> An {@code SCTPServerChannel} is created by invoking the
39   * {@link #open open} method of this class. A newly-created SCTP server
40   * channel is open but not yet bound. An attempt to invoke the
41   * {@link #accept accept} method of an unbound channel will cause the
42   * {@link java.nio.channels.NotYetBoundException} to be thrown. An SCTP server
43   * channel can be bound by invoking one of the
44   * {@link #bind(java.net.SocketAddress,int) bind} methods defined by this class.
45   *
46   * <p> Socket options are configured using the
47   * {@link #setOption(SctpSocketOption,Object) setOption} method. SCTP server socket
48   * channels support the following options:
49   * <blockquote>
50   * <table border summary="Socket options">
51   *   <tr>
52   *     <th>Option Name</th>
53   *     <th>Description</th>
54   *   </tr>
55   *   <tr>
56   *     <td> {@link SctpStandardSocketOptions#SCTP_INIT_MAXSTREAMS
57   *                                          SCTP_INIT_MAXSTREAMS} </td>
58   *     <td> The maximum number of streams requested by the local endpoint during
59   *          association initialization </td>
60   *   </tr>
61   * </table>
62   * </blockquote>
63   * Additional (implementation specific) options may also be supported. The list
64   * of options supported is obtained by invoking the {@link #supportedOptions()
65   * supportedOptions} method.
66   *
67   * <p>SCTP server channels are safe for use by multiple concurrent threads.
68   *
69   * @since 1.7
70   */
71  @jdk.Exported
72  public abstract class SctpServerChannel
73      extends AbstractSelectableChannel
74  {
75      /**
76       * Initializes a new instance of this class.
77       *
78       * @param  provider
79       *         The selector provider for this channel
80       */
81      protected SctpServerChannel(SelectorProvider provider) {
82          super(provider);
83      }
84  
85      /**
86       * Opens an SCTP server channel.
87       *
88       * <P> The new channel's socket is initially unbound; it must be bound
89       * to a specific address via one of its socket's {@link #bind bind}
90       * methods before associations can be accepted.
91       *
92       * @return  A new SCTP server channel
93       *
94       * @throws  UnsupportedOperationException
95       *          If the SCTP protocol is not supported
96       *
97       * @throws  IOException
98       *          If an I/O error occurs
99       */
100     public static SctpServerChannel open() throws
101         IOException {
102         return new sun.nio.ch.sctp.SctpServerChannelImpl((SelectorProvider)null);
103     }
104 
105     /**
106      * Accepts an association on this channel's socket.
107      *
108      * <P> If this channel is in non-blocking mode then this method will
109      * immediately return {@code null} if there are no pending associations.
110      * Otherwise it will block indefinitely until a new association is
111      * available or an I/O error occurs.
112      *
113      * <P> The {@code SCTPChannel} returned by this method, if any, will be in
114      *  blocking mode regardless of the blocking mode of this channel.
115      *
116      * <P> If a security manager has been installed then for each new
117      * association this method verifies that the address and port number of the
118      * assocaitions's remote peer are permitted by the security manager's {@link
119      * java.lang.SecurityManager#checkAccept(String,int) checkAccept} method.
120      *
121      * @return  The SCTP channel for the new association, or {@code null}
122      *          if this channel is in non-blocking mode and no association is
123      *          available to be accepted
124      *
125      * @throws  java.nio.channels.ClosedChannelException
126      *          If this channel is closed
127      *
128      * @throws  java.nio.channels.AsynchronousCloseException
129      *          If another thread closes this channel
130      *          while the accept operation is in progress
131      *
132      * @throws  java.nio.channels.ClosedByInterruptException
133      *          If another thread interrupts the current thread
134      *          while the accept operation is in progress, thereby
135      *          closing the channel and setting the current thread's
136      *          interrupt status
137      *
138      * @throws  java.nio.channels.NotYetBoundException
139      *          If this channel's socket has not yet been bound
140      *
141      * @throws  SecurityException
142      *          If a security manager has been installed and it does not permit
143      *          access to the remote peer of the new association
144      *
145      * @throws  IOException
146      *          If some other I/O error occurs
147      */
148     public abstract SctpChannel accept() throws IOException;
149 
150     /**
151      * Binds the channel's socket to a local address and configures the socket
152      * to listen for associations.
153      *
154      * <P> This method works as if invoking it were equivalent to evaluating the
155      * expression:
156      * <blockquote><pre>
157      * bind(local, 0);
158      * </pre></blockquote>
159      *
160      * @param  local
161      *         The local address to bind the socket, or {@code null} to
162      *         bind the socket to an automatically assigned socket address
163      *
164      * @return  This channel
165      *
166      * @throws  java.nio.channels.ClosedChannelException
167      *          If this channel is closed
168      *
169      * @throws  java.nio.channels.AlreadyBoundException
170      *          If this channel is already bound
171      *
172      * @throws  java.nio.channels.UnsupportedAddressTypeException
173      *          If the type of the given address is not supported
174      *
175      * @throws  SecurityException
176      *          If a security manager has been installed and its {@link
177      *          java.lang.SecurityManager#checkListen(int) checkListen} method
178      *          denies the operation
179      *
180      * @throws  IOException
181      *          If some other I/O error occurs
182      */
183     public final SctpServerChannel bind(SocketAddress local)
184         throws IOException {
185         return bind(local, 0);
186     }
187 
188     /**
189      * Binds the channel's socket to a local address and configures the socket
190      * to listen for associations.
191      *
192      * <P> This method is used to establish a relationship between the socket
193      * and the local address. Once a relationship is established then
194      * the socket remains bound until the channel is closed. This relationship
195      * may not necesssarily be with the address {@code local} as it may be
196      * removed by {@link #unbindAddress unbindAddress}, but there will always be
197      * at least one local address bound to the channel's socket once an
198      * invocation of this method successfully completes.
199      *
200      * <P> Once the channel's socket has been successfully bound to a specific
201      * address, that is not automatically assigned, more addresses
202      * may be bound to it using {@link #bindAddress bindAddress}, or removed
203      * using {@link #unbindAddress unbindAddress}.
204      *
205      * <P> The backlog parameter is the maximum number of pending associations
206      * on the socket. Its exact semantics are implementation specific. An
207      * implementation may impose an implementation specific maximum length or
208      * may choose to ignore the parameter. If the backlog parameter has the
209      * value {@code 0}, or a negative value, then an implementation specific
210      * default is used.
211      *
212      * @param  local
213      *         The local address to bind the socket, or {@code null} to
214      *         bind the socket to an automatically assigned socket address
215      *
216      * @param  backlog
217      *         The maximum number number of pending associations
218      *
219      * @return  This channel
220      *
221      * @throws  java.nio.channels.ClosedChannelException
222      *          If this channel is closed
223      *
224      * @throws  java.nio.channels.AlreadyBoundException
225      *          If this channel is already bound
226      *
227      * @throws  java.nio.channels.UnsupportedAddressTypeException
228      *          If the type of the given address is not supported
229      *
230      * @throws  SecurityException
231      *          If a security manager has been installed and its {@link
232      *          java.lang.SecurityManager#checkListen(int) checkListen} method
233      *          denies the operation
234      *
235      * @throws  IOException
236      *          If some other I/O error occurs
237      */
238     public abstract SctpServerChannel bind(SocketAddress local,
239                                            int backlog)
240         throws IOException;
241 
242     /**
243      * Adds the given address to the bound addresses for the channel's
244      * socket.
245      *
246      * <P> The given address must not be the {@link
247      * java.net.InetAddress#isAnyLocalAddress wildcard} address.
248      * The channel must be first bound using {@link #bind bind} before
249      * invoking this method, otherwise {@link
250      * java.nio.channels.NotYetBoundException} is thrown. The {@link #bind bind}
251      * method takes a {@code SocketAddress} as its argument which typically
252      * contains a port number as well as an address. Addresses subquently bound
253      * using this method are simply addresses as the SCTP port number remains
254      * the same for the lifetime of the channel.
255      *
256      * <P> New associations accepted after this method successfully completes
257      * will be associated with the given address.
258      *
259      * @param  address
260      *         The address to add to the bound addresses for the socket
261      *
262      * @return  This channel
263      *
264      * @throws  java.nio.channels.ClosedChannelException
265      *          If this channel is closed
266      *
267      * @throws  java.nio.channels.NotYetBoundException
268      *          If this channel is not yet bound
269      *
270      * @throws  java.nio.channels.AlreadyBoundException
271      *          If this channel is already bound to the given address
272      *
273      * @throws  IllegalArgumentException
274      *          If address is {@code null} or the {@link
275      *          java.net.InetAddress#isAnyLocalAddress wildcard} address
276      *
277      * @throws  IOException
278      *          If some other I/O error occurs
279      */
280     public abstract SctpServerChannel bindAddress(InetAddress address)
281          throws IOException;
282 
283     /**
284      * Removes the given address from the bound addresses for the channel's
285      * socket.
286      *
287      * <P> The given address must not be the {@link
288      * java.net.InetAddress#isAnyLocalAddress wildcard} address.
289      * The channel must be first bound using {@link #bind bind} before
290      * invoking this method, otherwise
291      * {@link java.nio.channels.NotYetBoundException} is thrown.
292      * If this method is invoked on a channel that does not have
293      * {@code address} as one of its bound addresses, or that has only one
294      * local address bound to it, then this method throws {@link
295      * IllegalUnbindException}.
296      * The initial address that the channel's socket is bound to using
297      * {@link #bind bind} may be removed from the bound addresses for the
298      * channel's socket.
299      *
300      * <P> New associations accepted after this method successfully completes
301      * will not be associated with the given address.
302      *
303      * @param  address
304      *         The address to remove from the bound addresses for the socket
305      *
306      * @return  This channel
307      *
308      * @throws  java.nio.channels.ClosedChannelException
309      *          If this channel is closed
310      *
311      * @throws  java.nio.channels.NotYetBoundException
312      *          If this channel is not yet bound
313      *
314      * @throws  IllegalArgumentException
315      *          If address is {@code null} or the {@link
316      *          java.net.InetAddress#isAnyLocalAddress wildcard} address
317      *
318      * @throws  IllegalUnbindException
319      *          If the implementation does not support removing addresses from a
320      *          listening socket, {@code address} is not bound to the channel's
321      *          socket, or the channel has only one address bound to it
322      *
323      * @throws  IOException
324      *          If some other I/O error occurs
325      */
326     public abstract SctpServerChannel unbindAddress(InetAddress address)
327          throws IOException;
328 
329     /**
330      * Returns all of the socket addresses to which this channel's socket is
331      * bound.
332      *
333      * @return  All the socket addresses that this channel's socket is
334      *          bound to, or an empty {@code Set} if the channel's socket is not
335      *          bound
336      *
337      * @throws  java.nio.channels.ClosedChannelException
338      *          If the channel is closed
339      *
340      * @throws  IOException
341      *          If an I/O error occurs
342      */
343     public abstract Set<SocketAddress> getAllLocalAddresses()
344         throws IOException;
345 
346     /**
347      * Returns the value of a socket option.
348      *
349      * @param   <T>
350      *          The type of the socket option value
351      *
352      * @param   name
353      *          The socket option
354      *
355      * @return  The value of the socket option. A value of {@code null} may be
356      *          a valid value for some socket options.
357      *
358      * @throws  UnsupportedOperationException
359      *          If the socket option is not supported by this channel
360      *
361      * @throws  java.nio.channels.ClosedChannelException
362      *          If this channel is closed
363      *
364      * @throws  IOException
365      *          If an I/O error occurs
366      *
367      * @see SctpStandardSocketOptions
368      */
369     public abstract <T> T getOption(SctpSocketOption<T> name) throws IOException;
370 
371     /**
372      * Sets the value of a socket option.
373      *
374      * @param   <T>
375      *          The type of the socket option value
376      *
377      * @param   name
378      *          The socket option
379      *
380      * @param   value
381      *          The value of the socket option. A value of {@code null} may be
382      *          a valid value for some socket options.
383      *
384      * @return  This channel
385      *
386      * @throws  UnsupportedOperationException
387      *          If the socket option is not supported by this channel
388      *
389      * @throws  IllegalArgumentException
390      *          If the value is not a valid value for this socket option
391      *
392      * @throws  java.nio.channels.ClosedChannelException
393      *          If this channel is closed
394      *
395      * @throws  IOException
396      *          If an I/O error occurs
397      *
398      * @see SctpStandardSocketOptions
399      */
400     public abstract <T> SctpServerChannel setOption(SctpSocketOption<T> name,
401                                                     T value)
402         throws IOException;
403 
404     /**
405      * Returns a set of the socket options supported by this channel.
406      *
407      * <P> This method will continue to return the set of options even after the
408      * channel has been closed.
409      *
410      * @return  A set of the socket options supported by this channel
411      */
412     public abstract Set<SctpSocketOption<?>> supportedOptions();
413 
414     /**
415      * Returns an operation set identifying this channel's supported
416      * operations.
417      *
418      * <P> SCTP server channels only support the accepting of new
419      * associations, so this method returns
420      * {@link java.nio.channels.SelectionKey#OP_ACCEPT}.
421      *
422      * @return  The valid-operation set
423      */
424     @Override
425     public final int validOps() {
426         return SelectionKey.OP_ACCEPT;
427     }
428 }