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<AsynchronousSocketChannel,Void>() { 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 } 329
