1 /* 2 * Copyright (c) 2007, 2017, 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 scope="col">Option Name</th> 60 * <th scope="col">Description</th> 61 * </tr> 62 * </thead> 63 * <tbody> 64 * <tr> 65 * <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th> 66 * <td> The size of the socket receive buffer </td> 67 * </tr> 68 * <tr> 69 * <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th> 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 */ AsynchronousServerSocketChannel(AsynchronousChannelProvider provider)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 */ provider()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 */ open(AsynchronousChannelGroup group)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 */ open()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 */ bind(SocketAddress local)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 */ bind(SocketAddress local, int backlog)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 */ setOption(SocketOption<T> name, T value)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 */ accept(A attachment, CompletionHandler<AsynchronousSocketChannel,? super A> handler)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 */ accept()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 getLocalAddress()332 public abstract SocketAddress getLocalAddress() throws IOException; 333 } 334