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