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