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