1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.nio.channels; 19 20import java.io.IOException; 21import java.net.Socket; 22import java.net.SocketAddress; 23import java.nio.ByteBuffer; 24import java.nio.channels.spi.AbstractSelectableChannel; 25import java.nio.channels.spi.SelectorProvider; 26 27/** 28 * A {@code SocketChannel} is a selectable channel that provides a partial 29 * abstraction of stream connecting socket. {@code socket()} returns the related 30 * {@link Socket} instance which can handle the socket. 31 * <p> 32 * A socket channel is open but not connected when created by {@code open()}. 33 * After connecting it by calling {@code connect(SocketAddress)}, it will remain 34 * connected until it gets closed. If the connection is non-blocking then 35 * {@code connect(SocketAddress)} is used to initiate the connection, followed 36 * by a call of {@code finishConnect()} to perform the final steps of 37 * connecting. {@code isConnectionPending()} indicates if the connection is 38 * blocked or not; {@code isConnected()} indicates if the socket is finally 39 * connected or not. 40 * <p> 41 * The input and output sides of a channel can be shut down independently and 42 * asynchronously without closing the channel. The {@code shutdownInput} method 43 * is used for the input side of a channel and subsequent read operations return 44 * -1, which means end of stream. If another thread is blocked in a read 45 * operation when the shutdown occurs, the read will end without effect and 46 * return end of stream. The {@code shutdownOutput} method is used for the 47 * output side of the channel; subsequent write operations throw a 48 * {@link ClosedChannelException}. If the output is shut down and another thread 49 * is blocked in a write operation, an {@link AsynchronousCloseException} will 50 * be thrown to the pending thread. 51 * <p> 52 * Socket channels are thread-safe, no more than one thread can read or write at 53 * any given time. The {@code connect(SocketAddress)} and {@code 54 * finishConnect()} methods are synchronized against each other; when they are 55 * processing, calls to {@code read} and {@code write} will block. 56 */ 57public abstract class SocketChannel extends AbstractSelectableChannel implements 58 ByteChannel, ScatteringByteChannel, GatheringByteChannel { 59 60 /** 61 * Constructs a new {@code SocketChannel}. 62 * 63 * @param selectorProvider 64 * an instance of SelectorProvider. 65 */ 66 protected SocketChannel(SelectorProvider selectorProvider) { 67 super(selectorProvider); 68 } 69 70 /** 71 * Creates an open and unconnected socket channel. 72 * <p> 73 * This channel is created by calling {@code openSocketChannel()} of the 74 * default {@link SelectorProvider} instance. 75 * 76 * @return the new channel which is open but unconnected. 77 * @throws IOException 78 * if an I/O error occurs. 79 */ 80 public static SocketChannel open() throws IOException { 81 return SelectorProvider.provider().openSocketChannel(); 82 } 83 84 /** 85 * Creates a socket channel and connects it to a socket address. 86 * <p> 87 * This method performs a call to {@code open()} followed by a call to 88 * {@code connect(SocketAdress)}. 89 * 90 * @param address 91 * the socket address to be connected to. 92 * @return the new connected channel. 93 * @throws AsynchronousCloseException 94 * if this channel is closed by another thread while this method 95 * is executing. 96 * @throws ClosedByInterruptException 97 * if another thread interrupts the calling thread while this 98 * operation is executing. The calling thread will have the 99 * interrupt state set and the channel will be closed. 100 * @throws SecurityException 101 * if there is a security manager and it denies the access of 102 * {@code address}. 103 * @throws UnresolvedAddressException 104 * if the address is not resolved. 105 * @throws UnsupportedAddressTypeException 106 * if the address type is not supported. 107 * @throws IOException 108 * if an I/O error occurs. 109 */ 110 public static SocketChannel open(SocketAddress address) throws IOException { 111 SocketChannel socketChannel = open(); 112 if (null != socketChannel) { 113 socketChannel.connect(address); 114 } 115 return socketChannel; 116 } 117 118 /** 119 * Gets the valid operations of this channel. Socket channels support 120 * connect, read and write operation, so this method returns 121 * {@code SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE}. 122 * 123 * @return the operations supported by this channel. 124 * @see java.nio.channels.SelectableChannel#validOps() 125 */ 126 @Override 127 public final int validOps() { 128 return (SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE); 129 } 130 131 /** 132 * Returns the socket assigned to this channel, which does not declare any public 133 * methods that are not declared in {@code Socket}. 134 * 135 * @return the socket assigned to this channel. 136 */ 137 public abstract Socket socket(); 138 139 /** 140 * Indicates whether this channel's socket is connected. 141 * 142 * @return {@code true} if this channel's socket is connected, {@code false} 143 * otherwise. 144 */ 145 public abstract boolean isConnected(); 146 147 /** 148 * Indicates whether this channel's socket is still trying to connect. 149 * 150 * @return {@code true} if the connection is initiated but not finished; 151 * {@code false} otherwise. 152 */ 153 public abstract boolean isConnectionPending(); 154 155 /** 156 * Connects this channel's socket with a remote address. 157 * <p> 158 * If this channel is blocking, this method will suspend until connecting is 159 * finished or an I/O exception occurrs. If the channel is non-blocking, 160 * this method will return {@code true} if the connection is finished at 161 * once or return {@code false} when the connection must be finished later 162 * by calling {@code finishConnect()}. 163 * <p> 164 * This method can be called at any moment and can block other read and 165 * write operations while connecting. It executes the same security checks 166 * as the connect method of the {@code Socket} class. 167 * 168 * @param address 169 * the address to connect with. 170 * @return {@code true} if the connection is finished, {@code false} 171 * otherwise. 172 * @throws AlreadyConnectedException 173 * if the channel is already connected. 174 * @throws ConnectionPendingException 175 * a non-blocking connecting operation is already executing on 176 * this channel. 177 * @throws ClosedChannelException 178 * if this channel is closed. 179 * @throws AsynchronousCloseException 180 * if this channel is closed by another thread while this method 181 * is executing. 182 * @throws ClosedByInterruptException 183 * if another thread interrupts the calling thread while this 184 * operation is in progress. The calling thread will have the 185 * interrupt state set and this channel will be closed. 186 * @throws UnresolvedAddressException 187 * if the address is not resolved. 188 * @throws UnsupportedAddressTypeException 189 * if the address type is not supported. 190 * @throws SecurityException 191 * if there is a security manager and it denies the access of 192 * {@code address}. 193 * @throws IOException 194 * if an I/O error occurs. 195 */ 196 public abstract boolean connect(SocketAddress address) throws IOException; 197 198 /** 199 * Completes the connection process initiated by a call of {@code 200 * connect(SocketAddress)}. 201 * <p> 202 * This method returns {@code true} if the connection is finished already 203 * and returns {@code false} if the channel is non-blocking and the 204 * connection is not finished yet. 205 * <p> 206 * If this channel is in blocking mode, this method will suspend and return 207 * {@code true} when the connection is finished. It closes this channel and 208 * throws an exception if the connection fails. 209 * <p> 210 * This method can be called at any moment and it can block other {@code 211 * read} and {@code write} operations while connecting. 212 * 213 * @return {@code true} if the connection is successfully finished, {@code 214 * false} otherwise. 215 * @throws NoConnectionPendingException 216 * if the channel is not connected and the connection process 217 * has not been initiated. 218 * @throws ClosedChannelException 219 * if this channel is closed. 220 * @throws AsynchronousCloseException 221 * if this channel is closed by another thread while this method 222 * is executing. 223 * @throws ClosedByInterruptException 224 * if another thread interrupts the calling thread while this 225 * operation is in progress. The calling thread has the 226 * interrupt state set, and this channel is closed. 227 * @throws IOException 228 * if an I/O error occurs. 229 */ 230 public abstract boolean finishConnect() throws IOException; 231 232 /** 233 * Reads bytes from this socket channel into the given buffer. 234 * <p> 235 * The maximum number of bytes that will be read is the remaining number of 236 * bytes in the buffer when the method is invoked. The bytes will be copied 237 * into the buffer starting at the buffer's current position. 238 * <p> 239 * The call may block if other threads are also attempting to read from this 240 * channel. 241 * <p> 242 * Upon completion, the buffer's position is set to the end of the bytes 243 * that have been read. The buffer's limit is not changed. 244 * 245 * @param target 246 * the byte buffer to receive the bytes. 247 * @return the number of bytes actually read. 248 * @throws AsynchronousCloseException 249 * if another thread closes the channel during the read. 250 * @throws NotYetConnectedException 251 * if this channel is not yet connected. 252 * @throws ClosedByInterruptException 253 * if another thread interrupts the calling thread while this 254 * operation is in progress. The interrupt state of the calling 255 * thread is set and the channel is closed. 256 * @throws ClosedChannelException 257 * if this channel is closed. 258 * @throws IOException 259 * if another I/O error occurs. 260 * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer) 261 */ 262 public abstract int read(ByteBuffer target) throws IOException; 263 264 /** 265 * Reads bytes from this socket channel into a subset of the given buffers. 266 * This method attempts to read all {@code remaining()} bytes from {@code 267 * length} byte buffers, in order, starting at {@code targets[offset]}. The 268 * number of bytes actually read is returned. 269 * <p> 270 * If a read operation is in progress, subsequent threads will block until 271 * the read is completed and will then contend for the ability to read. 272 * 273 * @param targets 274 * the array of byte buffers into which the bytes will be copied. 275 * @param offset 276 * the index of the first buffer to store bytes in. 277 * @param length 278 * the maximum number of buffers to store bytes in. 279 * @return the number of bytes actually read. 280 * @throws AsynchronousCloseException 281 * if this channel is closed by another thread during this read 282 * operation. 283 * @throws ClosedByInterruptException 284 * if another thread interrupts the calling thread while this 285 * operation is in progress. The interrupt state of the calling 286 * thread is set and the channel is closed. 287 * @throws ClosedChannelException 288 * if this channel is closed. 289 * @throws IndexOutOfBoundsException 290 * if {@code offset < 0} or {@code length < 0}, or if {@code 291 * offset + length} is greater than the size of {@code targets}. 292 * @throws IOException 293 * if another I/O error occurs. 294 * @throws NotYetConnectedException 295 * if this channel is not yet connected. 296 * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[], 297 * int, int) 298 */ 299 public abstract long read(ByteBuffer[] targets, int offset, int length) 300 throws IOException; 301 302 /** 303 * Reads bytes from this socket channel and stores them in the specified 304 * array of buffers. This method attempts to read as many bytes as can be 305 * stored in the buffer array from this channel and returns the number of 306 * bytes actually read. 307 * <p> 308 * If a read operation is in progress, subsequent threads will block until 309 * the read is completed and will then contend for the ability to read. 310 * <p> 311 * Calling this method is equivalent to calling {@code read(targets, 0, 312 * targets.length);} 313 * 314 * @param targets 315 * the array of byte buffers into which the bytes will be copied. 316 * @return the number of bytes actually read. 317 * @throws AsynchronousCloseException 318 * if this channel is closed by another thread during this read 319 * operation. 320 * @throws ClosedByInterruptException 321 * if another thread interrupts the calling thread while this 322 * operation is in progress. The interrupt state of the calling 323 * thread is set and the channel is closed. 324 * @throws ClosedChannelException 325 * if this channel is closed. 326 * @throws IOException 327 * if another I/O error occurs. 328 * @throws NotYetConnectedException 329 * if this channel is not yet connected. 330 */ 331 public synchronized final long read(ByteBuffer[] targets) 332 throws IOException { 333 return read(targets, 0, targets.length); 334 } 335 336 /** 337 * Writes bytes from the given byte buffer to this socket channel. The 338 * maximum number of bytes that are written is the remaining number of bytes 339 * in the buffer when this method is invoked. The bytes are taken from the 340 * buffer starting at the buffer's position. 341 * <p> 342 * The call may block if other threads are also attempting to write to the 343 * same channel. 344 * <p> 345 * Upon completion, the buffer's position is updated to the end of the bytes 346 * that have been written. The buffer's limit is not changed. 347 * 348 * @param source 349 * the byte buffer containing the bytes to be written. 350 * @return the number of bytes actually written. 351 * @throws AsynchronousCloseException 352 * if another thread closes the channel during the write. 353 * @throws ClosedByInterruptException 354 * if another thread interrupts the calling thread while this 355 * operation is in progress. The interrupt state of the calling 356 * thread is set and the channel is closed. 357 * @throws ClosedChannelException 358 * if the channel was already closed. 359 * @throws IOException 360 * if another I/O error occurs. 361 * @throws NotYetConnectedException 362 * if this channel is not connected yet. 363 * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 364 */ 365 public abstract int write(ByteBuffer source) throws IOException; 366 367 /** 368 * Attempts to write a subset of the given bytes from the buffers to this 369 * socket channel. This method attempts to write all {@code remaining()} 370 * bytes from {@code length} byte buffers, in order, starting at {@code 371 * sources[offset]}. The number of bytes actually written is returned. 372 * <p> 373 * If a write operation is in progress, subsequent threads will block until 374 * the write is completed and then contend for the ability to write. 375 * 376 * @param sources 377 * the array of byte buffers that is the source for bytes written 378 * to this channel. 379 * @param offset 380 * the index of the first buffer in {@code buffers }to get bytes 381 * from. 382 * @param length 383 * the number of buffers to get bytes from. 384 * @return the number of bytes actually written to this channel. 385 * @throws AsynchronousCloseException 386 * if this channel is closed by another thread during this write 387 * operation. 388 * @throws ClosedByInterruptException 389 * if another thread interrupts the calling thread while this 390 * operation is in progress. The interrupt state of the calling 391 * thread is set and the channel is closed. 392 * @throws ClosedChannelException 393 * if this channel is closed. 394 * @throws IndexOutOfBoundsException 395 * if {@code offset < 0} or {@code length < 0}, or if {@code 396 * offset + length} is greater than the size of {@code sources}. 397 * @throws IOException 398 * if another I/O error occurs. 399 * @throws NotYetConnectedException 400 * if this channel is not yet connected. 401 * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[], 402 * int, int) 403 */ 404 public abstract long write(ByteBuffer[] sources, int offset, int length) 405 throws IOException; 406 407 /** 408 * Writes bytes from all the given byte buffers to this socket channel. 409 * <p> 410 * Calling this method is equivalent to calling {@code write(sources, 0, 411 * sources.length);} 412 * 413 * @param sources 414 * the buffers containing bytes to write. 415 * @return the number of bytes actually written. 416 * @throws AsynchronousCloseException 417 * if this channel is closed by another thread during this write 418 * operation. 419 * @throws ClosedByInterruptException 420 * if another thread interrupts the calling thread while this 421 * operation is in progress. The interrupt state of the calling 422 * thread is set and the channel is closed. 423 * @throws ClosedChannelException 424 * if this channel is closed. 425 * @throws IOException 426 * if another I/O error occurs. 427 * @throws NotYetConnectedException 428 * if this channel is not yet connected. 429 * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[]) 430 */ 431 public synchronized final long write(ByteBuffer[] sources) 432 throws IOException { 433 return write(sources, 0, sources.length); 434 } 435} 436