KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > nio > channels > SocketChannel


1 /*
2  * @(#)SocketChannel.java 1.33 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.nio.channels;
9
10 import java.io.IOException JavaDoc;
11 import java.net.Socket JavaDoc;
12 import java.net.SocketAddress JavaDoc;
13 import java.nio.ByteBuffer JavaDoc;
14 import java.nio.channels.spi.*;
15
16
17 /**
18  * A selectable channel for stream-oriented connecting sockets.
19  *
20  * <p> Socket channels are not a complete abstraction of connecting network
21  * sockets. Binding, shutdown, and the manipulation of socket options must be
22  * done through an associated {@link java.net.Socket} object obtained by
23  * invoking the {@link #socket() socket} method. It is not possible to create
24  * a channel for an arbitrary, pre-existing socket, nor is it possible to
25  * specify the {@link java.net.SocketImpl} object to be used by a socket
26  * associated with a socket channel.
27  *
28  * <p> A socket channel is created by invoking one of the {@link #open open}
29  * methods of this class. A newly-created socket channel is open but not yet
30  * connected. An attempt to invoke an I/O operation upon an unconnected
31  * channel will cause a {@link NotYetConnectedException} to be thrown. A
32  * socket channel can be connected by invoking its {@link #connect connect}
33  * method; once connected, a socket channel remains connected until it is
34  * closed. Whether or not a socket channel is connected may be determined by
35  * invoking its {@link #isConnected isConnected} method.
36  *
37  * <p> Socket channels support <i>non-blocking connection:</i>&nbsp;A socket
38  * channel may be created and the process of establishing the link to the
39  * remote socket may be initiated via the {@link #connect connect} method for
40  * later completion by the {@link #finishConnect finishConnect} method.
41  * Whether or not a connection operation is in progress may be determined by
42  * invoking the {@link #isConnectionPending isConnectionPending} method.
43  *
44  * <p> The input and output sides of a socket channel may independently be
45  * <i>shut down</i> without actually closing the channel. Shutting down the
46  * input side of a channel by invoking the {@link java.net.Socket#shutdownInput
47  * shutdownInput} method of an associated socket object will cause further
48  * reads on the channel to return <tt>-1</tt>, the end-of-stream indication.
49  * Shutting down the output side of the channel by invoking the {@link
50  * java.net.Socket#shutdownOutput shutdownOutput} method of an associated
51  * socket object will cause further writes on the channel to throw a {@link
52  * ClosedChannelException}.
53  *
54  * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar
55  * to the asynchronous close operation specified in the {@link Channel} class.
56  * If the input side of a socket is shut down by one thread while another
57  * thread is blocked in a read operation on the socket's channel, then the read
58  * operation in the blocked thread will complete without reading any bytes and
59  * will return <tt>-1</tt>. If the output side of a socket is shut down by one
60  * thread while another thread is blocked in a write operation on the socket's
61  * channel, then the blocked thread will receive an {@link
62  * AsynchronousCloseException}.
63  *
64  * <p> Socket channels are safe for use by multiple concurrent threads. They
65  * support concurrent reading and writing, though at most one thread may be
66  * reading and at most one thread may be writing at any given time. The {@link
67  * #connect connect} and {@link #finishConnect finishConnect} methods are
68  * mutually synchronized against each other, and an attempt to initiate a read
69  * or write operation while an invocation of one of these methods is in
70  * progress will block until that invocation is complete. </p>
71  *
72  *
73  * @author Mark Reinhold
74  * @author JSR-51 Expert Group
75  * @version 1.33, 03/12/19
76  * @since 1.4
77  */

78
79 public abstract class SocketChannel
80     extends AbstractSelectableChannel
81     implements ByteChannel JavaDoc, ScatteringByteChannel JavaDoc, GatheringByteChannel JavaDoc
82 {
83
84     /**
85      * Initializes a new instance of this class.
86      */

87     protected SocketChannel(SelectorProvider provider) {
88     super(provider);
89     }
90
91     /**
92      * Opens a socket channel.
93      *
94      * <p> The new channel is created by invoking the {@link
95      * java.nio.channels.spi.SelectorProvider#openSocketChannel
96      * openSocketChannel} method of the system-wide default {@link
97      * java.nio.channels.spi.SelectorProvider} object. </p>
98      *
99      * @return A new socket channel
100      *
101      * @throws IOException
102      * If an I/O error occurs
103      */

104     public static SocketChannel JavaDoc open() throws IOException JavaDoc {
105     return SelectorProvider.provider().openSocketChannel();
106     }
107
108     /**
109      * Opens a socket channel and connects it to a remote address.
110      *
111      * <p> This convenience method works as if by invoking the {@link #open()}
112      * method, invoking the {@link #connect(SocketAddress) connect} method upon
113      * the resulting socket channel, passing it <tt>remote</tt>, and then
114      * returning that channel. </p>
115      *
116      * @param remote
117      * The remote address to which the new channel is to be connected
118      *
119      * @throws AsynchronousCloseException
120      * If another thread closes this channel
121      * while the connect operation is in progress
122      *
123      * @throws ClosedByInterruptException
124      * If another thread interrupts the current thread
125      * while the connect operation is in progress, thereby
126      * closing the channel and setting the current thread's
127      * interrupt status
128      *
129      * @throws UnresolvedAddressException
130      * If the given remote address is not fully resolved
131      *
132      * @throws UnsupportedAddressTypeException
133      * If the type of the given remote address is not supported
134      *
135      * @throws SecurityException
136      * If a security manager has been installed
137      * and it does not permit access to the given remote endpoint
138      *
139      * @throws IOException
140      * If some other I/O error occurs
141      */

142     public static SocketChannel JavaDoc open(SocketAddress JavaDoc remote)
143     throws IOException JavaDoc
144     {
145     SocketChannel JavaDoc sc = open();
146     sc.connect(remote);
147     return sc;
148     }
149
150     /**
151      * Returns an operation set identifying this channel's supported
152      * operations.
153      *
154      * <p> Socket channels support connecting, reading, and writing, so this
155      * method returns <tt>(</tt>{@link SelectionKey#OP_CONNECT}
156      * <tt>|</tt>&nbsp;{@link SelectionKey#OP_READ} <tt>|</tt>&nbsp;{@link
157      * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
158      *
159      * @return The valid-operation set
160      */

161     public final int validOps() {
162     return (SelectionKey.OP_READ
163         | SelectionKey.OP_WRITE
164         | SelectionKey.OP_CONNECT);
165     }
166
167
168     // -- Socket-specific operations --
169

170     /**
171      * Retrieves a socket associated with this channel.
172      *
173      * <p> The returned object will not declare any public methods that are not
174      * declared in the {@link java.net.Socket} class. </p>
175      *
176      * @return A socket associated with this channel
177      */

178     public abstract Socket JavaDoc socket();
179
180     /**
181      * Tells whether or not this channel's network socket is connected. </p>
182      *
183      * @return <tt>true</tt> if, and only if, this channel's network socket
184      * is connected
185      */

186     public abstract boolean isConnected();
187
188     /**
189      * Tells whether or not a connection operation is in progress on this
190      * channel. </p>
191      *
192      * @return <tt>true</tt> if, and only if, a connection operation has been
193      * initiated on this channel but not yet completed by invoking the
194      * {@link #finishConnect finishConnect} method
195      */

196     public abstract boolean isConnectionPending();
197
198     /**
199      * Connects this channel's socket.
200      *
201      * <p> If this channel is in non-blocking mode then an invocation of this
202      * method initiates a non-blocking connection operation. If the connection
203      * is established immediately, as can happen with a local connection, then
204      * this method returns <tt>true</tt>. Otherwise this method returns
205      * <tt>false</tt> and the connection operation must later be completed by
206      * invoking the {@link #finishConnect finishConnect} method.
207      *
208      * <p> If this channel is in blocking mode then an invocation of this
209      * method will block until the connection is established or an I/O error
210      * occurs.
211      *
212      * <p> This method performs exactly the same security checks as the {@link
213      * java.net.Socket} class. That is, if a security manager has been
214      * installed then this method verifies that its {@link
215      * java.lang.SecurityManager#checkConnect checkConnect} method permits
216      * connecting to the address and port number of the given remote endpoint.
217      *
218      * <p> This method may be invoked at any time. If a read or write
219      * operation upon this channel is invoked while an invocation of this
220      * method is in progress then that operation will first block until this
221      * invocation is complete. If a connection attempt is initiated but fails,
222      * that is, if an invocation of this method throws a checked exception,
223      * then the channel will be closed. </p>
224      *
225      * @param remote
226      * The remote address to which this channel is to be connected
227      *
228      * @return <tt>true</tt> if a connection was established,
229      * <tt>false</tt> if this channel is in non-blocking mode
230      * and the connection operation is in progress
231      *
232      * @throws AlreadyConnectedException
233      * If this channel is already connected
234      *
235      * @throws ConnectionPendingException
236      * If a non-blocking connection operation is already in progress
237      * on this channel
238      *
239      * @throws ClosedChannelException
240      * If this channel is closed
241      *
242      * @throws AsynchronousCloseException
243      * If another thread closes this channel
244      * while the connect operation is in progress
245      *
246      * @throws ClosedByInterruptException
247      * If another thread interrupts the current thread
248      * while the connect operation is in progress, thereby
249      * closing the channel and setting the current thread's
250      * interrupt status
251      *
252      * @throws UnresolvedAddressException
253      * If the given remote address is not fully resolved
254      *
255      * @throws UnsupportedAddressTypeException
256      * If the type of the given remote address is not supported
257      *
258      * @throws SecurityException
259      * If a security manager has been installed
260      * and it does not permit access to the given remote endpoint
261      *
262      * @throws IOException
263      * If some other I/O error occurs
264      */

265     public abstract boolean connect(SocketAddress JavaDoc remote) throws IOException JavaDoc;
266
267     /**
268      * Finishes the process of connecting a socket channel.
269      *
270      * <p> A non-blocking connection operation is initiated by placing a socket
271      * channel in non-blocking mode and then invoking its {@link #connect
272      * connect} method. Once the connection is established, or the attempt has
273      * failed, the socket channel will become connectable and this method may
274      * be invoked to complete the connection sequence. If the connection
275      * operation failed then invoking this method will cause an appropriate
276      * {@link java.io.IOException} to be thrown.
277      *
278      * <p> If this channel is already connected then this method will not block
279      * and will immediately return <tt>true</tt>. If this channel is in
280      * non-blocking mode then this method will return <tt>false</tt> if the
281      * connection process is not yet complete. If this channel is in blocking
282      * mode then this method will block until the connection either completes
283      * or fails, and will always either return <tt>true</tt> or throw a checked
284      * exception describing the failure.
285      *
286      * <p> This method may be invoked at any time. If a read or write
287      * operation upon this channel is invoked while an invocation of this
288      * method is in progress then that operation will first block until this
289      * invocation is complete. If a connection attempt fails, that is, if an
290      * invocation of this method throws a checked exception, then the channel
291      * will be closed. </p>
292      *
293      * @return <tt>true</tt> if, and only if, this channel's socket is now
294      * connected
295      *
296      * @throws NoConnectionPendingException
297      * If this channel is not connected and a connection operation
298      * has not been initiated
299      *
300      * @throws ClosedChannelException
301      * If this channel is closed
302      *
303      * @throws AsynchronousCloseException
304      * If another thread closes this channel
305      * while the connect operation is in progress
306      *
307      * @throws ClosedByInterruptException
308      * If another thread interrupts the current thread
309      * while the connect operation is in progress, thereby
310      * closing the channel and setting the current thread's
311      * interrupt status
312      *
313      * @throws IOException
314      * If some other I/O error occurs
315      */

316     public abstract boolean finishConnect() throws IOException JavaDoc;
317
318
319     // -- ByteChannel operations --
320

321     /**
322      * @throws NotYetConnectedException
323      * If this channel is not yet connected
324      */

325     public abstract int read(ByteBuffer JavaDoc dst) throws IOException JavaDoc;
326
327     /**
328      * @throws NotYetConnectedException
329      * If this channel is not yet connected
330      */

331     public abstract long read(ByteBuffer JavaDoc[] dsts, int offset, int length)
332     throws IOException JavaDoc;
333
334     /**
335      * @throws NotYetConnectedException
336      * If this channel is not yet connected
337      */

338     public final long read(ByteBuffer JavaDoc[] dsts) throws IOException JavaDoc {
339     return read(dsts, 0, dsts.length);
340     }
341
342     /**
343      * @throws NotYetConnectedException
344      * If this channel is not yet connected
345      */

346     public abstract int write(ByteBuffer JavaDoc src) throws IOException JavaDoc;
347
348     /**
349      * @throws NotYetConnectedException
350      * If this channel is not yet connected
351      */

352     public abstract long write(ByteBuffer JavaDoc[] srcs, int offset, int length)
353     throws IOException JavaDoc;
354
355     /**
356      * @throws NotYetConnectedException
357      * If this channel is not yet connected
358      */

359     public final long write(ByteBuffer JavaDoc[] srcs) throws IOException JavaDoc {
360     return write(srcs, 0, srcs.length);
361     }
362
363 }
364
Popular Tags