1 /* 2 * Copyright (c) 2000, 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.io.IOException; 29 import java.net.ServerSocket; 30 import java.net.SocketOption; 31 import java.net.SocketAddress; 32 import java.nio.channels.spi.AbstractSelectableChannel; 33 import java.nio.channels.spi.SelectorProvider; 34 35 /** 36 * A selectable channel for stream-oriented listening sockets. 37 * 38 * <p> A server-socket channel is created by invoking the {@link #open() open} 39 * method of this class. It is not possible to create a channel for an arbitrary, 40 * pre-existing {@link ServerSocket}. A newly-created server-socket channel is 41 * open but not yet bound. An attempt to invoke the {@link #accept() accept} 42 * method of an unbound server-socket channel will cause a {@link NotYetBoundException} 43 * to be thrown. A server-socket 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 {@link #setOption(SocketOption,Object) 47 * setOption} method. Server-socket channels support the following options: 48 * <blockquote> 49 * <table class="striped"> 50 * <caption style="display:none">Socket options</caption> 51 * <thead> 52 * <tr> 53 * <th scope="col">Option Name</th> 54 * <th scope="col">Description</th> 55 * </tr> 56 * </thead> 57 * <tbody> 58 * <tr> 59 * <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th> 60 * <td> The size of the socket receive buffer </td> 61 * </tr> 62 * <tr> 63 * <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th> 64 * <td> Re-use address </td> 65 * </tr> 66 * </tbody> 67 * </table> 68 * </blockquote> 69 * Additional (implementation specific) options may also be supported. 70 * 71 * <p> Server-socket channels are safe for use by multiple concurrent threads. 72 * </p> 73 * 74 * @author Mark Reinhold 75 * @author JSR-51 Expert Group 76 * @since 1.4 77 */ 78 79 public abstract class ServerSocketChannel 80 extends AbstractSelectableChannel 81 implements NetworkChannel 82 { 83 84 /** 85 * Initializes a new instance of this class. 86 * 87 * @param provider 88 * The provider that created this channel 89 */ ServerSocketChannel(SelectorProvider provider)90 protected ServerSocketChannel(SelectorProvider provider) { 91 super(provider); 92 } 93 94 /** 95 * Opens a server-socket channel. 96 * 97 * <p> The new channel is created by invoking the {@link 98 * java.nio.channels.spi.SelectorProvider#openServerSocketChannel 99 * openServerSocketChannel} method of the system-wide default {@link 100 * java.nio.channels.spi.SelectorProvider} object. 101 * 102 * <p> The new channel's socket is initially unbound; it must be bound to a 103 * specific address via one of its socket's {@link 104 * java.net.ServerSocket#bind(SocketAddress) bind} methods before 105 * connections can be accepted. </p> 106 * 107 * @return A new socket channel 108 * 109 * @throws IOException 110 * If an I/O error occurs 111 */ open()112 public static ServerSocketChannel open() throws IOException { 113 return SelectorProvider.provider().openServerSocketChannel(); 114 } 115 116 /** 117 * Returns an operation set identifying this channel's supported 118 * operations. 119 * 120 * <p> Server-socket channels only support the accepting of new 121 * connections, so this method returns {@link SelectionKey#OP_ACCEPT}. 122 * </p> 123 * 124 * @return The valid-operation set 125 */ validOps()126 public final int validOps() { 127 return SelectionKey.OP_ACCEPT; 128 } 129 130 131 // -- ServerSocket-specific operations -- 132 133 /** 134 * Binds the channel's socket to a local address and configures the socket 135 * to listen for connections. 136 * 137 * <p> An invocation of this method is equivalent to the following: 138 * <blockquote><pre> 139 * bind(local, 0); 140 * </pre></blockquote> 141 * 142 * @param local 143 * The local address to bind the socket, or {@code null} to bind 144 * to an automatically assigned socket address 145 * 146 * @return This channel 147 * 148 * @throws AlreadyBoundException {@inheritDoc} 149 * @throws UnsupportedAddressTypeException {@inheritDoc} 150 * @throws ClosedChannelException {@inheritDoc} 151 * @throws IOException {@inheritDoc} 152 * @throws SecurityException 153 * If a security manager has been installed and its {@link 154 * SecurityManager#checkListen checkListen} method denies the 155 * operation 156 * 157 * @since 1.7 158 */ bind(SocketAddress local)159 public final ServerSocketChannel bind(SocketAddress local) 160 throws IOException 161 { 162 return bind(local, 0); 163 } 164 165 /** 166 * Binds the channel's socket to a local address and configures the socket to 167 * listen for connections. 168 * 169 * <p> This method is used to establish an association between the socket and 170 * a local address. Once an association is established then the socket remains 171 * bound until the channel is closed. 172 * 173 * <p> The {@code backlog} parameter is the maximum number of pending 174 * connections on the socket. Its exact semantics are implementation specific. 175 * In particular, an implementation may impose a maximum length or may choose 176 * to ignore the parameter altogther. If the {@code backlog} parameter has 177 * the value {@code 0}, or a negative value, then an implementation specific 178 * default is used. 179 * 180 * @param local 181 * The address to bind the socket, or {@code null} to bind to an 182 * automatically assigned socket address 183 * @param backlog 184 * The maximum number of pending connections 185 * 186 * @return This channel 187 * 188 * @throws AlreadyBoundException 189 * If the socket is already bound 190 * @throws UnsupportedAddressTypeException 191 * If the type of the given address is not supported 192 * @throws ClosedChannelException 193 * If this channel is closed 194 * @throws IOException 195 * If some other I/O error occurs 196 * @throws SecurityException 197 * If a security manager has been installed and its {@link 198 * SecurityManager#checkListen checkListen} method denies the 199 * operation 200 * 201 * @since 1.7 202 */ bind(SocketAddress local, int backlog)203 public abstract ServerSocketChannel bind(SocketAddress local, int backlog) 204 throws IOException; 205 206 /** 207 * @throws UnsupportedOperationException {@inheritDoc} 208 * @throws IllegalArgumentException {@inheritDoc} 209 * @throws ClosedChannelException {@inheritDoc} 210 * @throws IOException {@inheritDoc} 211 * 212 * @since 1.7 213 */ setOption(SocketOption<T> name, T value)214 public abstract <T> ServerSocketChannel setOption(SocketOption<T> name, T value) 215 throws IOException; 216 217 /** 218 * Retrieves a server socket associated with this channel. 219 * 220 * <p> The returned object will not declare any public methods that are not 221 * declared in the {@link java.net.ServerSocket} class. </p> 222 * 223 * @return A server socket associated with this channel 224 */ socket()225 public abstract ServerSocket socket(); 226 227 /** 228 * Accepts a connection made to this channel's socket. 229 * 230 * <p> If this channel is in non-blocking mode then this method will 231 * immediately return {@code null} if there are no pending connections. 232 * Otherwise it will block indefinitely until a new connection is available 233 * or an I/O error occurs. 234 * 235 * <p> The socket channel returned by this method, if any, will be in 236 * blocking mode regardless of the blocking mode of this channel. 237 * 238 * <p> This method performs exactly the same security checks as the {@link 239 * java.net.ServerSocket#accept accept} method of the {@link 240 * java.net.ServerSocket} class. That is, if a security manager has been 241 * installed then for each new connection this method verifies that the 242 * address and port number of the connection's remote endpoint are 243 * permitted by the security manager's {@link 244 * java.lang.SecurityManager#checkAccept checkAccept} method. </p> 245 * 246 * @return The socket channel for the new connection, 247 * or {@code null} if this channel is in non-blocking mode 248 * and no connection is available to be accepted 249 * 250 * @throws ClosedChannelException 251 * If this channel is closed 252 * 253 * @throws AsynchronousCloseException 254 * If another thread closes this channel 255 * while the accept operation is in progress 256 * 257 * @throws ClosedByInterruptException 258 * If another thread interrupts the current thread 259 * while the accept operation is in progress, thereby 260 * closing the channel and setting the current thread's 261 * interrupt status 262 * 263 * @throws NotYetBoundException 264 * If this channel's socket has not yet been bound 265 * 266 * @throws SecurityException 267 * If a security manager has been installed 268 * and it does not permit access to the remote endpoint 269 * of the new connection 270 * 271 * @throws IOException 272 * If some other I/O error occurs 273 */ accept()274 public abstract SocketChannel accept() throws IOException; 275 276 /** 277 * {@inheritDoc} 278 * <p> 279 * If there is a security manager set, its {@code checkConnect} method is 280 * called with the local address and {@code -1} as its arguments to see 281 * if the operation is allowed. If the operation is not allowed, 282 * a {@code SocketAddress} representing the 283 * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the 284 * local port of the channel's socket is returned. 285 * 286 * @return The {@code SocketAddress} that the socket is bound to, or the 287 * {@code SocketAddress} representing the loopback address if 288 * denied by the security manager, or {@code null} if the 289 * channel's socket is not bound 290 * 291 * @throws ClosedChannelException {@inheritDoc} 292 * @throws IOException {@inheritDoc} 293 */ 294 @Override getLocalAddress()295 public abstract SocketAddress getLocalAddress() throws IOException; 296 297 } 298