2
|
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 |
}
|