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  ;
11  import java.net.Socket  ;
12  import java.net.SocketAddress  ;
13  import java.nio.ByteBuffer  ;
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  , ScatteringByteChannel  , GatheringByteChannel  
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   open() throws IOException   {
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   open(SocketAddress   remote)
143     throws IOException  
144     {
145     SocketChannel   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   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   remote) throws IOException  ;
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  ;
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   dst) throws IOException  ;
326 
327     /**
328      * @throws  NotYetConnectedException
329      *          If this channel is not yet connected
330      */
331     public abstract long read(ByteBuffer  [] dsts, int offset, int length)
332     throws IOException  ;
333 
334     /**
335      * @throws  NotYetConnectedException
336      *          If this channel is not yet connected
337      */
338     public final long read(ByteBuffer  [] dsts) throws IOException   {
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   src) throws IOException  ;
347 
348     /**
349      * @throws  NotYetConnectedException
350      *          If this channel is not yet connected
351      */
352     public abstract long write(ByteBuffer  [] srcs, int offset, int length)
353     throws IOException  ;
354 
355     /**
356      * @throws  NotYetConnectedException
357      *          If this channel is not yet connected
358      */
359     public final long write(ByteBuffer  [] srcs) throws IOException   {
360     return write(srcs, 0, srcs.length);
361     }
362 
363 }
364
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags