View Javadoc
1   /*
2    * Copyright (c) 2007, 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  
26  package java.nio.channels;
27  
28  import java.nio.channels.spi.*;
29  import java.net.SocketOption;
30  import java.net.SocketAddress;
31  import java.util.concurrent.Future;
32  import java.io.IOException;
33  
34  /**
35   * An asynchronous channel for stream-oriented listening sockets.
36   *
37   * <p> An asynchronous server-socket channel is created by invoking the
38   * {@link #open open} method of this class.
39   * A newly-created asynchronous server-socket channel is open but not yet bound.
40   * It can be bound to a local address and configured to listen for connections
41   * by invoking the {@link #bind(SocketAddress,int) bind} method. Once bound,
42   * the {@link #accept(Object,CompletionHandler) accept} method
43   * is used to initiate the accepting of connections to the channel's socket.
44   * An attempt to invoke the <tt>accept</tt> method on an unbound channel will
45   * cause a {@link NotYetBoundException} to be thrown.
46   *
47   * <p> Channels of this type are safe for use by multiple concurrent threads
48   * though at most one accept operation can be outstanding at any time.
49   * If a thread initiates an accept operation before a previous accept operation
50   * has completed then an {@link AcceptPendingException} will be thrown.
51   *
52   * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
53   * setOption} method. Channels of this type support the following options:
54   * <blockquote>
55   * <table border summary="Socket options">
56   *   <tr>
57   *     <th>Option Name</th>
58   *     <th>Description</th>
59   *   </tr>
60   *   <tr>
61   *     <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
62   *     <td> The size of the socket receive buffer </td>
63   *   </tr>
64   *   <tr>
65   *     <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
66   *     <td> Re-use address </td>
67   *   </tr>
68   * </table>
69   * </blockquote>
70   * Additional (implementation specific) options may also be supported.
71   *
72   * <p> <b>Usage Example:</b>
73   * <pre>
74   *  final AsynchronousServerSocketChannel listener =
75   *      AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));
76   *
77   *  listener.accept(null, new CompletionHandler&lt;AsynchronousSocketChannel,Void&gt;() {
78   *      public void completed(AsynchronousSocketChannel ch, Void att) {
79   *          // accept the next connection
80   *          listener.accept(null, this);
81   *
82   *          // handle this connection
83   *          handle(ch);
84   *      }
85   *      public void failed(Throwable exc, Void att) {
86   *          ...
87   *      }
88   *  });
89   * </pre>
90   *
91   * @since 1.7
92   */
93  
94  public abstract class AsynchronousServerSocketChannel
95      implements AsynchronousChannel, NetworkChannel
96  {
97      private final AsynchronousChannelProvider provider;
98  
99      /**
100      * Initializes a new instance of this class.
101      *
102      * @param  provider
103      *         The provider that created this channel
104      */
105     protected AsynchronousServerSocketChannel(AsynchronousChannelProvider provider) {
106         this.provider = provider;
107     }
108 
109     /**
110      * Returns the provider that created this channel.
111      *
112      * @return  The provider that created this channel
113      */
114     public final AsynchronousChannelProvider provider() {
115         return provider;
116     }
117 
118     /**
119      * Opens an asynchronous server-socket channel.
120      *
121      * <p> The new channel is created by invoking the {@link
122      * java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousServerSocketChannel
123      * openAsynchronousServerSocketChannel} method on the {@link
124      * java.nio.channels.spi.AsynchronousChannelProvider} object that created
125      * the given group. If the group parameter is <tt>null</tt> then the
126      * resulting channel is created by the system-wide default provider, and
127      * bound to the <em>default group</em>.
128      *
129      * @param   group
130      *          The group to which the newly constructed channel should be bound,
131      *          or <tt>null</tt> for the default group
132      *
133      * @return  A new asynchronous server socket channel
134      *
135      * @throws  ShutdownChannelGroupException
136      *          If the channel group is shutdown
137      * @throws  IOException
138      *          If an I/O error occurs
139      */
140     public static AsynchronousServerSocketChannel open(AsynchronousChannelGroup group)
141         throws IOException
142     {
143         AsynchronousChannelProvider provider = (group == null) ?
144             AsynchronousChannelProvider.provider() : group.provider();
145         return provider.openAsynchronousServerSocketChannel(group);
146     }
147 
148     /**
149      * Opens an asynchronous server-socket channel.
150      *
151      * <p> This method returns an asynchronous server socket channel that is
152      * bound to the <em>default group</em>. This method is equivalent to evaluating
153      * the expression:
154      * <blockquote><pre>
155      * open((AsynchronousChannelGroup)null);
156      * </pre></blockquote>
157      *
158      * @return  A new asynchronous server socket channel
159      *
160      * @throws  IOException
161      *          If an I/O error occurs
162      */
163     public static AsynchronousServerSocketChannel open()
164         throws IOException
165     {
166         return open(null);
167     }
168 
169     /**
170      * Binds the channel's socket to a local address and configures the socket to
171      * listen for connections.
172      *
173      * <p> An invocation of this method is equivalent to the following:
174      * <blockquote><pre>
175      * bind(local, 0);
176      * </pre></blockquote>
177      *
178      * @param   local
179      *          The local address to bind the socket, or <tt>null</tt> to bind
180      *          to an automatically assigned socket address
181      *
182      * @return  This channel
183      *
184      * @throws  AlreadyBoundException               {@inheritDoc}
185      * @throws  UnsupportedAddressTypeException     {@inheritDoc}
186      * @throws  SecurityException                   {@inheritDoc}
187      * @throws  ClosedChannelException              {@inheritDoc}
188      * @throws  IOException                         {@inheritDoc}
189      */
190     public final AsynchronousServerSocketChannel bind(SocketAddress local)
191         throws IOException
192     {
193         return bind(local, 0);
194     }
195 
196     /**
197      * Binds the channel's socket to a local address and configures the socket to
198      * listen for connections.
199      *
200      * <p> This method is used to establish an association between the socket and
201      * a local address. Once an association is established then the socket remains
202      * bound until the associated channel is closed.
203      *
204      * <p> The {@code backlog} parameter is the maximum number of pending
205      * connections on the socket. Its exact semantics are implementation specific.
206      * In particular, an implementation may impose a maximum length or may choose
207      * to ignore the parameter altogther. If the {@code backlog} parameter has
208      * the value {@code 0}, or a negative value, then an implementation specific
209      * default is used.
210      *
211      * @param   local
212      *          The local address to bind the socket, or {@code null} to bind
213      *          to an automatically assigned socket address
214      * @param   backlog
215      *          The maximum number of pending connections
216      *
217      * @return  This channel
218      *
219      * @throws  AlreadyBoundException
220      *          If the socket is already bound
221      * @throws  UnsupportedAddressTypeException
222      *          If the type of the given address is not supported
223      * @throws  SecurityException
224      *          If a security manager has been installed and its {@link
225      *          SecurityManager#checkListen checkListen} method denies the operation
226      * @throws  ClosedChannelException
227      *          If the channel is closed
228      * @throws  IOException
229      *          If some other I/O error occurs
230      */
231     public abstract AsynchronousServerSocketChannel bind(SocketAddress local, int backlog)
232         throws IOException;
233 
234     /**
235      * @throws  IllegalArgumentException                {@inheritDoc}
236      * @throws  ClosedChannelException                  {@inheritDoc}
237      * @throws  IOException                             {@inheritDoc}
238      */
239     public abstract <T> AsynchronousServerSocketChannel setOption(SocketOption<T> name, T value)
240         throws IOException;
241 
242     /**
243      * Accepts a connection.
244      *
245      * <p> This method initiates an asynchronous operation to accept a
246      * connection made to this channel's socket. The {@code handler} parameter is
247      * a completion handler that is invoked when a connection is accepted (or
248      * the operation fails). The result passed to the completion handler is
249      * the {@link AsynchronousSocketChannel} to the new connection.
250      *
251      * <p> When a new connection is accepted then the resulting {@code
252      * AsynchronousSocketChannel} will be bound to the same {@link
253      * AsynchronousChannelGroup} as this channel. If the group is {@link
254      * AsynchronousChannelGroup#isShutdown shutdown} and a connection is accepted,
255      * then the connection is closed, and the operation completes with an {@code
256      * IOException} and cause {@link ShutdownChannelGroupException}.
257      *
258      * <p> To allow for concurrent handling of new connections, the completion
259      * handler is not invoked directly by the initiating thread when a new
260      * connection is accepted immediately (see <a
261      * href="AsynchronousChannelGroup.html#threading">Threading</a>).
262      *
263      * <p> If a security manager has been installed then it verifies that the
264      * address and port number of the connection's remote endpoint are permitted
265      * by the security manager's {@link SecurityManager#checkAccept checkAccept}
266      * method. The permission check is performed with privileges that are restricted
267      * by the calling context of this method. If the permission check fails then
268      * the connection is closed and the operation completes with a {@link
269      * SecurityException}.
270      *
271      * @param   <A>
272      *          The type of the attachment
273      * @param   attachment
274      *          The object to attach to the I/O operation; can be {@code null}
275      * @param   handler
276      *          The handler for consuming the result
277      *
278      * @throws  AcceptPendingException
279      *          If an accept operation is already in progress on this channel
280      * @throws  NotYetBoundException
281      *          If this channel's socket has not yet been bound
282      * @throws  ShutdownChannelGroupException
283      *          If the channel group has terminated
284      */
285     public abstract <A> void accept(A attachment,
286                                     CompletionHandler<AsynchronousSocketChannel,? super A> handler);
287 
288     /**
289      * Accepts a connection.
290      *
291      * <p> This method initiates an asynchronous operation to accept a
292      * connection made to this channel's socket. The method behaves in exactly
293      * the same manner as the {@link #accept(Object, CompletionHandler)} method
294      * except that instead of specifying a completion handler, this method
295      * returns a {@code Future} representing the pending result. The {@code
296      * Future}'s {@link Future#get() get} method returns the {@link
297      * AsynchronousSocketChannel} to the new connection on successful completion.
298      *
299      * @return  a {@code Future} object representing the pending result
300      *
301      * @throws  AcceptPendingException
302      *          If an accept operation is already in progress on this channel
303      * @throws  NotYetBoundException
304      *          If this channel's socket has not yet been bound
305      */
306     public abstract Future<AsynchronousSocketChannel> accept();
307 
308     /**
309      * {@inheritDoc}
310      * <p>
311      * If there is a security manager set, its {@code checkConnect} method is
312      * called with the local address and {@code -1} as its arguments to see
313      * if the operation is allowed. If the operation is not allowed,
314      * a {@code SocketAddress} representing the
315      * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
316      * local port of the channel's socket is returned.
317      *
318      * @return  The {@code SocketAddress} that the socket is bound to, or the
319      *          {@code SocketAddress} representing the loopback address if
320      *          denied by the security manager, or {@code null} if the
321      *          channel's socket is not bound
322      *
323      * @throws  ClosedChannelException     {@inheritDoc}
324      * @throws  IOException                {@inheritDoc}
325      */
326     @Override
327     public abstract SocketAddress getLocalAddress() throws IOException;
328 }