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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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
295 public abstract SocketAddress getLocalAddress() throws IOException;
296
297 }