1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.nio.channels;
19
20import java.io.IOException;
21import java.net.ServerSocket;
22import java.net.SocketAddress;
23import java.nio.channels.spi.AbstractSelectableChannel;
24import java.nio.channels.spi.SelectorProvider;
25import java.util.Set;
26
27/**
28 * A {@code ServerSocketChannel} is a partial abstraction of a selectable,
29 * stream-oriented listening socket. Binding and manipulation of socket options
30 * can only be done through the associated {@link ServerSocket} object, returned
31 * by calling {@code socket()}. ServerSocketChannels can not be constructed for
32 * an already existing server-socket, nor can a {@link java.net.SocketImpl} be assigned.
33 * <p>
34 * A server-socket channel is open but not bound when created by the {@code
35 * open()} method. Calling {@code accept} before bound will cause a
36 * {@link NotYetBoundException}. It can be bound by calling the bind method of a
37 * related {@code ServerSocket} instance.
38 */
39public abstract class ServerSocketChannel extends AbstractSelectableChannel {
40    /**
41     * Constructs a new {@link ServerSocketChannel}.
42     *
43     * @param selectorProvider
44     *            an instance of SelectorProvider.
45     */
46    protected ServerSocketChannel(SelectorProvider selectorProvider) {
47        super(selectorProvider);
48    }
49
50    /**
51     * Creates an open and unbound server-socket channel.
52     * <p>
53     * This channel is created by calling {@code openServerSocketChannel} method
54     * of the default {@code SelectorProvider} instance.
55     *
56     * @return the new channel which is open but unbound.
57     * @throws IOException
58     *             if an I/O error occurs.
59     */
60    public static ServerSocketChannel open() throws IOException {
61        return SelectorProvider.provider().openServerSocketChannel();
62    }
63
64    /**
65     * Gets the valid operations of this channel. Server-socket channels support
66     * accepting operation, so this method returns {@code
67     * SelectionKey.OP_ACCEPT}.
68     *
69     * @see java.nio.channels.SelectableChannel#validOps()
70     * @return the operations supported by this channel.
71     */
72    @Override
73    public final int validOps() {
74        return SelectionKey.OP_ACCEPT;
75    }
76
77    /**
78     * Return the server-socket assigned this channel, which does not declare
79     * any public methods that are not declared in {@code ServerSocket}.
80     *
81     * @return the server-socket assigned to this channel.
82     */
83    public abstract ServerSocket socket();
84
85    /**
86     * Accepts a connection to this server-socket channel.
87     * <p>
88     * This method returns {@code null} when this channel is non-blocking and no
89     * connection is available, otherwise it blocks until a new connection is
90     * available or an I/O error occurs. The socket channel returned by this
91     * method will always be in blocking mode.
92     * <p>
93     * This method just executes the same security checks as the {@code
94     * accept()} method of the {@link ServerSocket} class.
95     *
96     * @return the accepted {@code SocketChannel} instance, or {@code null} if
97     *         the channel is non-blocking and no connection is available.
98     * @throws AsynchronousCloseException
99     *             if this channel is closed by another thread while this method
100     *             is in operation.
101     * @throws ClosedByInterruptException
102     *             if another thread interrupts the calling thread while this
103     *             operation is in progress. The interrupt state of the calling
104     *             thread is set and the channel is closed.
105     * @throws ClosedChannelException
106     *             if this channel is closed.
107     * @throws IOException
108     *             if another I/O error occurs.
109     * @throws NotYetBoundException
110     *             if the socket has not yet been bound.
111     */
112    public abstract SocketChannel accept() throws IOException;
113}
114