001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.nio.channels;
027
028 import java.io.IOException;
029 import java.net.ServerSocket;
030 import java.net.SocketAddress;
031 import java.nio.channels.spi.*;
032
033 /**
034 * A selectable channel for stream-oriented listening sockets.
035 *
036 * <p> Server-socket channels are not a complete abstraction of listening
037 * network sockets. Binding and the manipulation of socket options must be
038 * done through an associated {@link java.net.ServerSocket} object obtained by
039 * invoking the {@link #socket() socket} method. It is not possible to create
040 * a channel for an arbitrary, pre-existing server socket, nor is it possible
041 * to specify the {@link java.net.SocketImpl} object to be used by a server
042 * socket associated with a server-socket channel.
043 *
044 * <p> A server-socket channel is created by invoking the {@link #open() open}
045 * method of this class. A newly-created server-socket channel is open but not
046 * yet bound. An attempt to invoke the {@link #accept() accept} method of an
047 * unbound server-socket channel will cause a {@link NotYetBoundException} to
048 * be thrown. A server-socket channel can be bound by invoking one of the
049 * {@link java.net.ServerSocket#bind(java.net.SocketAddress,int) bind} methods
050 * of an associated server socket.
051 *
052 * <p> Server-socket channels are safe for use by multiple concurrent threads.
053 * </p>
054 *
055 *
056 * @author Mark Reinhold
057 * @author JSR-51 Expert Group
058 * @version 1.31, 07/05/05
059 * @since 1.4
060 */
061
062 public abstract class ServerSocketChannel extends
063 AbstractSelectableChannel {
064
065 /**
066 * Initializes a new instance of this class.
067 */
068 protected ServerSocketChannel(SelectorProvider provider) {
069 super (provider);
070 }
071
072 /**
073 * Opens a server-socket channel.
074 *
075 * <p> The new channel is created by invoking the {@link
076 * java.nio.channels.spi.SelectorProvider#openServerSocketChannel
077 * openServerSocketChannel} method of the system-wide default {@link
078 * java.nio.channels.spi.SelectorProvider} object.
079 *
080 * <p> The new channel's socket is initially unbound; it must be bound to a
081 * specific address via one of its socket's {@link
082 * java.net.ServerSocket#bind(SocketAddress) bind} methods before
083 * connections can be accepted. </p>
084 *
085 * @return A new socket channel
086 *
087 * @throws IOException
088 * If an I/O error occurs
089 */
090 public static ServerSocketChannel open() throws IOException {
091 return SelectorProvider.provider().openServerSocketChannel();
092 }
093
094 /**
095 * Returns an operation set identifying this channel's supported
096 * operations.
097 *
098 * <p> Server-socket channels only support the accepting of new
099 * connections, so this method returns {@link SelectionKey#OP_ACCEPT}.
100 * </p>
101 *
102 * @return The valid-operation set
103 */
104 public final int validOps() {
105 return SelectionKey.OP_ACCEPT;
106 }
107
108 // -- ServerSocket-specific operations --
109
110 /**
111 * Retrieves a server socket associated with this channel.
112 *
113 * <p> The returned object will not declare any public methods that are not
114 * declared in the {@link java.net.ServerSocket} class. </p>
115 *
116 * @return A server socket associated with this channel
117 */
118 public abstract ServerSocket socket();
119
120 /**
121 * Accepts a connection made to this channel's socket.
122 *
123 * <p> If this channel is in non-blocking mode then this method will
124 * immediately return <tt>null</tt> if there are no pending connections.
125 * Otherwise it will block indefinitely until a new connection is available
126 * or an I/O error occurs.
127 *
128 * <p> The socket channel returned by this method, if any, will be in
129 * blocking mode regardless of the blocking mode of this channel.
130 *
131 * <p> This method performs exactly the same security checks as the {@link
132 * java.net.ServerSocket#accept accept} method of the {@link
133 * java.net.ServerSocket} class. That is, if a security manager has been
134 * installed then for each new connection this method verifies that the
135 * address and port number of the connection's remote endpoint are
136 * permitted by the security manager's {@link
137 * java.lang.SecurityManager#checkAccept checkAccept} method. </p>
138 *
139 * @return The socket channel for the new connection,
140 * or <tt>null</tt> if this channel is in non-blocking mode
141 * and no connection is available to be accepted
142 *
143 * @throws ClosedChannelException
144 * If this channel is closed
145 *
146 * @throws AsynchronousCloseException
147 * If another thread closes this channel
148 * while the accept operation is in progress
149 *
150 * @throws ClosedByInterruptException
151 * If another thread interrupts the current thread
152 * while the accept operation is in progress, thereby
153 * closing the channel and setting the current thread's
154 * interrupt status
155 *
156 * @throws NotYetBoundException
157 * If this channel's socket has not yet been bound
158 *
159 * @throws SecurityException
160 * If a security manager has been installed
161 * and it does not permit access to the remote endpoint
162 * of the new connection
163 *
164 * @throws IOException
165 * If some other I/O error occurs
166 */
167 public abstract SocketChannel accept() throws IOException;
168
169 }
|