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