1 /*
2 * Copyright 2000-2001 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.nio.channels;
27
28 import java.io.IOException;
29 import java.net.Socket;
30 import java.net.SocketAddress;
31 import java.nio.ByteBuffer;
32 import java.nio.channels.spi;
33
34
35 /**
36 * A selectable channel for stream-oriented connecting sockets.
37 *
38 * <p> Socket channels are not a complete abstraction of connecting network
39 * sockets. Binding, shutdown, and the manipulation of socket options must be
40 * done through an associated {@link java.net.Socket} object obtained by
41 * invoking the {@link #socket() socket} method. It is not possible to create
42 * a channel for an arbitrary, pre-existing socket, nor is it possible to
43 * specify the {@link java.net.SocketImpl} object to be used by a socket
44 * associated with a socket channel.
45 *
46 * <p> A socket channel is created by invoking one of the {@link #open open}
47 * methods of this class. A newly-created socket channel is open but not yet
48 * connected. An attempt to invoke an I/O operation upon an unconnected
49 * channel will cause a {@link NotYetConnectedException} to be thrown. A
50 * socket channel can be connected by invoking its {@link #connect connect}
51 * method; once connected, a socket channel remains connected until it is
52 * closed. Whether or not a socket channel is connected may be determined by
53 * invoking its {@link #isConnected isConnected} method.
54 *
55 * <p> Socket channels support <i>non-blocking connection:</i> A socket
56 * channel may be created and the process of establishing the link to the
57 * remote socket may be initiated via the {@link #connect connect} method for
58 * later completion by the {@link #finishConnect finishConnect} method.
59 * Whether or not a connection operation is in progress may be determined by
60 * invoking the {@link #isConnectionPending isConnectionPending} method.
61 *
62 * <p> The input and output sides of a socket channel may independently be
63 * <i>shut down</i> without actually closing the channel. Shutting down the
64 * input side of a channel by invoking the {@link java.net.Socket#shutdownInput
65 * shutdownInput} method of an associated socket object will cause further
66 * reads on the channel to return <tt>-1</tt>, the end-of-stream indication.
67 * Shutting down the output side of the channel by invoking the {@link
68 * java.net.Socket#shutdownOutput shutdownOutput} method of an associated
69 * socket object will cause further writes on the channel to throw a {@link
70 * ClosedChannelException}.
71 *
72 * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar
73 * to the asynchronous close operation specified in the {@link Channel} class.
74 * If the input side of a socket is shut down by one thread while another
75 * thread is blocked in a read operation on the socket's channel, then the read
76 * operation in the blocked thread will complete without reading any bytes and
77 * will return <tt>-1</tt>. If the output side of a socket is shut down by one
78 * thread while another thread is blocked in a write operation on the socket's
79 * channel, then the blocked thread will receive an {@link
80 * AsynchronousCloseException}.
81 *
82 * <p> Socket channels are safe for use by multiple concurrent threads. They
83 * support concurrent reading and writing, though at most one thread may be
84 * reading and at most one thread may be writing at any given time. The {@link
85 * #connect connect} and {@link #finishConnect finishConnect} methods are
86 * mutually synchronized against each other, and an attempt to initiate a read
87 * or write operation while an invocation of one of these methods is in
88 * progress will block until that invocation is complete. </p>
89 *
90 *
91 * @author Mark Reinhold
92 * @author JSR-51 Expert Group
93 * @since 1.4
94 */
95
96 public abstract class SocketChannel
97 extends AbstractSelectableChannel
98 implements ByteChannel, ScatteringByteChannel, GatheringByteChannel
99 {
100
101 /**
102 * Initializes a new instance of this class.
103 */
104 protected SocketChannel(SelectorProvider provider) {
105 super(provider);
106 }
107
108 /**
109 * Opens a socket channel.
110 *
111 * <p> The new channel is created by invoking the {@link
112 * java.nio.channels.spi.SelectorProvider#openSocketChannel
113 * openSocketChannel} method of the system-wide default {@link
114 * java.nio.channels.spi.SelectorProvider} object. </p>
115 *
116 * @return A new socket channel
117 *
118 * @throws IOException
119 * If an I/O error occurs
120 */
121 public static SocketChannel open() throws IOException {
122 return SelectorProvider.provider().openSocketChannel();
123 }
124
125 /**
126 * Opens a socket channel and connects it to a remote address.
127 *
128 * <p> This convenience method works as if by invoking the {@link #open()}
129 * method, invoking the {@link #connect(SocketAddress) connect} method upon
130 * the resulting socket channel, passing it <tt>remote</tt>, and then
131 * returning that channel. </p>
132 *
133 * @param remote
134 * The remote address to which the new channel is to be connected
135 *
136 * @throws AsynchronousCloseException
137 * If another thread closes this channel
138 * while the connect operation is in progress
139 *
140 * @throws ClosedByInterruptException
141 * If another thread interrupts the current thread
142 * while the connect operation is in progress, thereby
143 * closing the channel and setting the current thread's
144 * interrupt status
145 *
146 * @throws UnresolvedAddressException
147 * If the given remote address is not fully resolved
148 *
149 * @throws UnsupportedAddressTypeException
150 * If the type of the given remote address is not supported
151 *
152 * @throws SecurityException
153 * If a security manager has been installed
154 * and it does not permit access to the given remote endpoint
155 *
156 * @throws IOException
157 * If some other I/O error occurs
158 */
159 public static SocketChannel open(SocketAddress remote)
160 throws IOException
161 {
162 SocketChannel sc = open();
163 try {
164 sc.connect(remote);
165 } finally {
166 if (!sc.isConnected()) {
167 try { sc.close(); } catch (IOException x) { }
168 }
169 }
170 assert sc.isConnected();
171 return sc;
172 }
173
174 /**
175 * Returns an operation set identifying this channel's supported
176 * operations.
177 *
178 * <p> Socket channels support connecting, reading, and writing, so this
179 * method returns <tt>(</tt>{@link SelectionKey#OP_CONNECT}
180 * <tt>|</tt> {@link SelectionKey#OP_READ} <tt>|</tt> {@link
181 * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
182 *
183 * @return The valid-operation set
184 */
185 public final int validOps() {
186 return (SelectionKey.OP_READ
187 | SelectionKey.OP_WRITE
188 | SelectionKey.OP_CONNECT);
189 }
190
191
192 // -- Socket-specific operations --
193
194 /**
195 * Retrieves a socket associated with this channel.
196 *
197 * <p> The returned object will not declare any public methods that are not
198 * declared in the {@link java.net.Socket} class. </p>
199 *
200 * @return A socket associated with this channel
201 */
202 public abstract Socket socket();
203
204 /**
205 * Tells whether or not this channel's network socket is connected. </p>
206 *
207 * @return <tt>true</tt> if, and only if, this channel's network socket
208 * is connected
209 */
210 public abstract boolean isConnected();
211
212 /**
213 * Tells whether or not a connection operation is in progress on this
214 * channel. </p>
215 *
216 * @return <tt>true</tt> if, and only if, a connection operation has been
217 * initiated on this channel but not yet completed by invoking the
218 * {@link #finishConnect finishConnect} method
219 */
220 public abstract boolean isConnectionPending();
221
222 /**
223 * Connects this channel's socket.
224 *
225 * <p> If this channel is in non-blocking mode then an invocation of this
226 * method initiates a non-blocking connection operation. If the connection
227 * is established immediately, as can happen with a local connection, then
228 * this method returns <tt>true</tt>. Otherwise this method returns
229 * <tt>false</tt> and the connection operation must later be completed by
230 * invoking the {@link #finishConnect finishConnect} method.
231 *
232 * <p> If this channel is in blocking mode then an invocation of this
233 * method will block until the connection is established or an I/O error
234 * occurs.
235 *
236 * <p> This method performs exactly the same security checks as the {@link
237 * java.net.Socket} class. That is, if a security manager has been
238 * installed then this method verifies that its {@link
239 * java.lang.SecurityManager#checkConnect checkConnect} method permits
240 * connecting to the address and port number of the given remote endpoint.
241 *
242 * <p> This method may be invoked at any time. If a read or write
243 * operation upon this channel is invoked while an invocation of this
244 * method is in progress then that operation will first block until this
245 * invocation is complete. If a connection attempt is initiated but fails,
246 * that is, if an invocation of this method throws a checked exception,
247 * then the channel will be closed. </p>
248 *
249 * @param remote
250 * The remote address to which this channel is to be connected
251 *
252 * @return <tt>true</tt> if a connection was established,
253 * <tt>false</tt> if this channel is in non-blocking mode
254 * and the connection operation is in progress
255 *
256 * @throws AlreadyConnectedException
257 * If this channel is already connected
258 *
259 * @throws ConnectionPendingException
260 * If a non-blocking connection operation is already in progress
261 * on this channel
262 *
263 * @throws ClosedChannelException
264 * If this channel is closed
265 *
266 * @throws AsynchronousCloseException
267 * If another thread closes this channel
268 * while the connect operation is in progress
269 *
270 * @throws ClosedByInterruptException
271 * If another thread interrupts the current thread
272 * while the connect operation is in progress, thereby
273 * closing the channel and setting the current thread's
274 * interrupt status
275 *
276 * @throws UnresolvedAddressException
277 * If the given remote address is not fully resolved
278 *
279 * @throws UnsupportedAddressTypeException
280 * If the type of the given remote address is not supported
281 *
282 * @throws SecurityException
283 * If a security manager has been installed
284 * and it does not permit access to the given remote endpoint
285 *
286 * @throws IOException
287 * If some other I/O error occurs
288 */
289 public abstract boolean connect(SocketAddress remote) throws IOException;
290
291 /**
292 * Finishes the process of connecting a socket channel.
293 *
294 * <p> A non-blocking connection operation is initiated by placing a socket
295 * channel in non-blocking mode and then invoking its {@link #connect
296 * connect} method. Once the connection is established, or the attempt has
297 * failed, the socket channel will become connectable and this method may
298 * be invoked to complete the connection sequence. If the connection
299 * operation failed then invoking this method will cause an appropriate
300 * {@link java.io.IOException} to be thrown.
301 *
302 * <p> If this channel is already connected then this method will not block
303 * and will immediately return <tt>true</tt>. If this channel is in
304 * non-blocking mode then this method will return <tt>false</tt> if the
305 * connection process is not yet complete. If this channel is in blocking
306 * mode then this method will block until the connection either completes
307 * or fails, and will always either return <tt>true</tt> or throw a checked
308 * exception describing the failure.
309 *
310 * <p> This method may be invoked at any time. If a read or write
311 * operation upon this channel is invoked while an invocation of this
312 * method is in progress then that operation will first block until this
313 * invocation is complete. If a connection attempt fails, that is, if an
314 * invocation of this method throws a checked exception, then the channel
315 * will be closed. </p>
316 *
317 * @return <tt>true</tt> if, and only if, this channel's socket is now
318 * connected
319 *
320 * @throws NoConnectionPendingException
321 * If this channel is not connected and a connection operation
322 * has not been initiated
323 *
324 * @throws ClosedChannelException
325 * If this channel is closed
326 *
327 * @throws AsynchronousCloseException
328 * If another thread closes this channel
329 * while the connect operation is in progress
330 *
331 * @throws ClosedByInterruptException
332 * If another thread interrupts the current thread
333 * while the connect operation is in progress, thereby
334 * closing the channel and setting the current thread's
335 * interrupt status
336 *
337 * @throws IOException
338 * If some other I/O error occurs
339 */
340 public abstract boolean finishConnect() throws IOException;
341
342
343 // -- ByteChannel operations --
344
345 /**
346 * @throws NotYetConnectedException
347 * If this channel is not yet connected
348 */
349 public abstract int read(ByteBuffer dst) throws IOException;
350
351 /**
352 * @throws NotYetConnectedException
353 * If this channel is not yet connected
354 */
355 public abstract long read(ByteBuffer[] dsts, int offset, int length)
356 throws IOException;
357
358 /**
359 * @throws NotYetConnectedException
360 * If this channel is not yet connected
361 */
362 public final long read(ByteBuffer[] dsts) throws IOException {
363 return read(dsts, 0, dsts.length);
364 }
365
366 /**
367 * @throws NotYetConnectedException
368 * If this channel is not yet connected
369 */
370 public abstract int write(ByteBuffer src) throws IOException;
371
372 /**
373 * @throws NotYetConnectedException
374 * If this channel is not yet connected
375 */
376 public abstract long write(ByteBuffer[] srcs, int offset, int length)
377 throws IOException;
378
379 /**
380 * @throws NotYetConnectedException
381 * If this channel is not yet connected
382 */
383 public final long write(ByteBuffer[] srcs) throws IOException {
384 return write(srcs, 0, srcs.length);
385 }
386
387 }
Save This Page