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