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.nio.channels.spi.AbstractSelectableChannel;
23import java.nio.channels.spi.SelectorProvider;
24
25/**
26 * A {@code ServerSocketChannel} is a partial abstraction of a selectable,
27 * stream-oriented listening socket. Binding and manipulation of socket options
28 * can only be done through the associated {@link ServerSocket} object, returned
29 * by calling {@code socket()}. ServerSocketChannels can not be constructed for
30 * an already existing server-socket, nor can a {@link java.net.SocketImpl} be assigned.
31 * <p>
32 * A server-socket channel is open but not bound when created by the {@code
33 * open()} method. Calling {@code accept} before bound will cause a
34 * {@link NotYetBoundException}. It can be bound by calling the bind method of a
35 * related {@code ServerSocket} instance.
36 */
37public abstract class ServerSocketChannel extends AbstractSelectableChannel {
38
39    /**
40     * Constructs a new {@link ServerSocketChannel}.
41     *
42     * @param selectorProvider
43     *            an instance of SelectorProvider.
44     */
45    protected ServerSocketChannel(SelectorProvider selectorProvider) {
46        super(selectorProvider);
47    }
48
49    /**
50     * Creates an open and unbound server-socket channel.
51     * <p>
52     * This channel is created by calling {@code openServerSocketChannel} method
53     * of the default {@code SelectorProvider} instance.
54     *
55     * @return the new channel which is open but unbound.
56     * @throws IOException
57     *             if an I/O error occurs.
58     */
59    public static ServerSocketChannel open() throws IOException {
60        return SelectorProvider.provider().openServerSocketChannel();
61    }
62
63    /**
64     * Gets the valid operations of this channel. Server-socket channels support
65     * accepting operation, so this method returns {@code
66     * SelectionKey.OP_ACCEPT}.
67     *
68     * @see java.nio.channels.SelectableChannel#validOps()
69     * @return the operations supported by this channel.
70     */
71    @Override
72    public final int validOps() {
73        return SelectionKey.OP_ACCEPT;
74    }
75
76    /**
77     * Return the server-socket assigned this channel, which does not declare
78     * any public methods that are not declared in {@code ServerSocket}.
79     *
80     * @return the server-socket assigned to this channel.
81     */
82    public abstract ServerSocket socket();
83
84    /**
85     * Accepts a connection to this server-socket channel.
86     * <p>
87     * This method returns {@code null} when this channel is non-blocking and no
88     * connection is available, otherwise it blocks until a new connection is
89     * available or an I/O error occurs. The socket channel returned by this
90     * method will always be in blocking mode.
91     * <p>
92     * This method just executes the same security checks as the {@code
93     * accept()} method of the {@link ServerSocket} class.
94     *
95     * @return the accepted {@code SocketChannel} instance, or {@code null} if
96     *         the channel is non-blocking and no connection is available.
97     * @throws AsynchronousCloseException
98     *             if this channel is closed by another thread while this method
99     *             is in operation.
100     * @throws ClosedByInterruptException
101     *             if another thread interrupts the calling thread while this
102     *             operation is in progress. The interrupt state of the calling
103     *             thread is set and the channel is closed.
104     * @throws ClosedChannelException
105     *             if this channel is closed.
106     * @throws IOException
107     *             if another I/O error occurs.
108     * @throws NotYetBoundException
109     *             if the socket has not yet been bound.
110     */
111    public abstract SocketChannel accept() throws IOException;
112}
113