| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package java.nio.channels; |
| |
| import java.io.IOException; |
| import java.net.Socket; |
| import java.net.SocketAddress; |
| import java.nio.ByteBuffer; |
| import java.nio.channels.spi.AbstractSelectableChannel; |
| import java.nio.channels.spi.SelectorProvider; |
| |
| /** |
| * A {@code SocketChannel} is a selectable channel that provides a partial |
| * abstraction of stream connecting socket. {@code socket()} returns the related |
| * {@link Socket} instance which can handle the socket. |
| * <p> |
| * A socket channel is open but not connected when created by {@code open()}. |
| * After connecting it by calling {@code connect(SocketAddress)}, it will remain |
| * connected until it gets closed. If the connection is non-blocking then |
| * {@code connect(SocketAddress)} is used to initiate the connection, followed |
| * by a call of {@code finishConnect()} to perform the final steps of |
| * connecting. {@code isConnectionPending()} indicates if the connection is |
| * blocked or not; {@code isConnected()} indicates if the socket is finally |
| * connected or not. |
| * <p> |
| * The input and output sides of a channel can be shut down independently and |
| * asynchronously without closing the channel. The {@code shutdownInput} method |
| * is used for the input side of a channel and subsequent read operations return |
| * -1, which means end of stream. If another thread is blocked in a read |
| * operation when the shutdown occurs, the read will end without effect and |
| * return end of stream. The {@code shutdownOutput} method is used for the |
| * output side of the channel; subsequent write operations throw a |
| * {@link ClosedChannelException}. If the output is shut down and another thread |
| * is blocked in a write operation, an {@link AsynchronousCloseException} will |
| * be thrown to the pending thread. |
| * <p> |
| * Socket channels are thread-safe, no more than one thread can read or write at |
| * any given time. The {@code connect(SocketAddress)} and {@code |
| * finishConnect()} methods are synchronized against each other; when they are |
| * processing, calls to {@code read} and {@code write} will block. |
| */ |
| public abstract class SocketChannel extends AbstractSelectableChannel implements |
| ByteChannel, ScatteringByteChannel, GatheringByteChannel { |
| |
| /** |
| * Constructs a new {@code SocketChannel}. |
| * |
| * @param selectorProvider |
| * an instance of SelectorProvider. |
| */ |
| protected SocketChannel(SelectorProvider selectorProvider) { |
| super(selectorProvider); |
| } |
| |
| /** |
| * Creates an open and unconnected socket channel. |
| * <p> |
| * This channel is created by calling {@code openSocketChannel()} of the |
| * default {@link SelectorProvider} instance. |
| * |
| * @return the new channel which is open but unconnected. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public static SocketChannel open() throws IOException { |
| return SelectorProvider.provider().openSocketChannel(); |
| } |
| |
| /** |
| * Creates a socket channel and connects it to a socket address. |
| * <p> |
| * This method performs a call to {@code open()} followed by a call to |
| * {@code connect(SocketAdress)}. |
| * |
| * @param address |
| * the socket address to be connected to. |
| * @return the new connected channel. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread while this method |
| * is executing. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is executing. The calling thread will have the |
| * interrupt state set and the channel will be closed. |
| * @throws SecurityException |
| * if there is a security manager and it denies the access of |
| * {@code address}. |
| * @throws UnresolvedAddressException |
| * if the address is not resolved. |
| * @throws UnsupportedAddressTypeException |
| * if the address type is not supported. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public static SocketChannel open(SocketAddress address) throws IOException { |
| SocketChannel socketChannel = open(); |
| if (null != socketChannel) { |
| socketChannel.connect(address); |
| } |
| return socketChannel; |
| } |
| |
| /** |
| * Gets the valid operations of this channel. Socket channels support |
| * connect, read and write operation, so this method returns |
| * {@code SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE}. |
| * |
| * @return the operations supported by this channel. |
| * @see java.nio.channels.SelectableChannel#validOps() |
| */ |
| @Override |
| public final int validOps() { |
| return (SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE); |
| } |
| |
| /** |
| * Returns the socket assigned to this channel, which does not declare any public |
| * methods that are not declared in {@code Socket}. |
| * |
| * @return the socket assigned to this channel. |
| */ |
| public abstract Socket socket(); |
| |
| /** |
| * Indicates whether this channel's socket is connected. |
| * |
| * @return {@code true} if this channel's socket is connected, {@code false} |
| * otherwise. |
| */ |
| public abstract boolean isConnected(); |
| |
| /** |
| * Indicates whether this channel's socket is still trying to connect. |
| * |
| * @return {@code true} if the connection is initiated but not finished; |
| * {@code false} otherwise. |
| */ |
| public abstract boolean isConnectionPending(); |
| |
| /** |
| * Connects this channel's socket with a remote address. |
| * <p> |
| * If this channel is blocking, this method will suspend until connecting is |
| * finished or an I/O exception occurrs. If the channel is non-blocking, |
| * this method will return {@code true} if the connection is finished at |
| * once or return {@code false} when the connection must be finished later |
| * by calling {@code finishConnect()}. |
| * <p> |
| * This method can be called at any moment and can block other read and |
| * write operations while connecting. It executes the same security checks |
| * as the connect method of the {@code Socket} class. |
| * |
| * @param address |
| * the address to connect with. |
| * @return {@code true} if the connection is finished, {@code false} |
| * otherwise. |
| * @throws AlreadyConnectedException |
| * if the channel is already connected. |
| * @throws ConnectionPendingException |
| * a non-blocking connecting operation is already executing on |
| * this channel. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread while this method |
| * is executing. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The calling thread will have the |
| * interrupt state set and this channel will be closed. |
| * @throws UnresolvedAddressException |
| * if the address is not resolved. |
| * @throws UnsupportedAddressTypeException |
| * if the address type is not supported. |
| * @throws SecurityException |
| * if there is a security manager and it denies the access of |
| * {@code address}. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public abstract boolean connect(SocketAddress address) throws IOException; |
| |
| /** |
| * Completes the connection process initiated by a call of {@code |
| * connect(SocketAddress)}. |
| * <p> |
| * This method returns {@code true} if the connection is finished already |
| * and returns {@code false} if the channel is non-blocking and the |
| * connection is not finished yet. |
| * <p> |
| * If this channel is in blocking mode, this method will suspend and return |
| * {@code true} when the connection is finished. It closes this channel and |
| * throws an exception if the connection fails. |
| * <p> |
| * This method can be called at any moment and it can block other {@code |
| * read} and {@code write} operations while connecting. |
| * |
| * @return {@code true} if the connection is successfully finished, {@code |
| * false} otherwise. |
| * @throws NoConnectionPendingException |
| * if the channel is not connected and the connection process |
| * has not been initiated. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread while this method |
| * is executing. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The calling thread has the |
| * interrupt state set, and this channel is closed. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public abstract boolean finishConnect() throws IOException; |
| |
| /** |
| * Reads bytes from this socket channel into the given buffer. |
| * <p> |
| * The maximum number of bytes that will be read is the remaining number of |
| * bytes in the buffer when the method is invoked. The bytes will be copied |
| * into the buffer starting at the buffer's current position. |
| * <p> |
| * The call may block if other threads are also attempting to read from this |
| * channel. |
| * <p> |
| * Upon completion, the buffer's position is set to the end of the bytes |
| * that have been read. The buffer's limit is not changed. |
| * |
| * @param target |
| * the byte buffer to receive the bytes. |
| * @return the number of bytes actually read. |
| * @throws AsynchronousCloseException |
| * if another thread closes the channel during the read. |
| * @throws NotYetConnectedException |
| * if this channel is not yet connected. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer) |
| */ |
| public abstract int read(ByteBuffer target) throws IOException; |
| |
| /** |
| * Reads bytes from this socket channel into a subset of the given buffers. |
| * This method attempts to read all {@code remaining()} bytes from {@code |
| * length} byte buffers, in order, starting at {@code targets[offset]}. The |
| * number of bytes actually read is returned. |
| * <p> |
| * If a read operation is in progress, subsequent threads will block until |
| * the read is completed and will then contend for the ability to read. |
| * |
| * @param targets |
| * the array of byte buffers into which the bytes will be copied. |
| * @param offset |
| * the index of the first buffer to store bytes in. |
| * @param length |
| * the maximum number of buffers to store bytes in. |
| * @return the number of bytes actually read. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread during this read |
| * operation. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IndexOutOfBoundsException |
| * if {@code offset < 0} or {@code length < 0}, or if {@code |
| * offset + length} is greater than the size of {@code targets}. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @throws NotYetConnectedException |
| * if this channel is not yet connected. |
| * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[], |
| * int, int) |
| */ |
| public abstract long read(ByteBuffer[] targets, int offset, int length) |
| throws IOException; |
| |
| /** |
| * Reads bytes from this socket channel and stores them in the specified |
| * array of buffers. This method attempts to read as many bytes as can be |
| * stored in the buffer array from this channel and returns the number of |
| * bytes actually read. |
| * <p> |
| * If a read operation is in progress, subsequent threads will block until |
| * the read is completed and will then contend for the ability to read. |
| * <p> |
| * Calling this method is equivalent to calling {@code read(targets, 0, |
| * targets.length);} |
| * |
| * @param targets |
| * the array of byte buffers into which the bytes will be copied. |
| * @return the number of bytes actually read. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread during this read |
| * operation. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @throws NotYetConnectedException |
| * if this channel is not yet connected. |
| */ |
| public synchronized final long read(ByteBuffer[] targets) |
| throws IOException { |
| return read(targets, 0, targets.length); |
| } |
| |
| /** |
| * Writes bytes from the given byte buffer to this socket channel. The |
| * maximum number of bytes that are written is the remaining number of bytes |
| * in the buffer when this method is invoked. The bytes are taken from the |
| * buffer starting at the buffer's position. |
| * <p> |
| * The call may block if other threads are also attempting to write to the |
| * same channel. |
| * <p> |
| * Upon completion, the buffer's position is updated to the end of the bytes |
| * that have been written. The buffer's limit is not changed. |
| * |
| * @param source |
| * the byte buffer containing the bytes to be written. |
| * @return the number of bytes actually written. |
| * @throws AsynchronousCloseException |
| * if another thread closes the channel during the write. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if the channel was already closed. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @throws NotYetConnectedException |
| * if this channel is not connected yet. |
| * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) |
| */ |
| public abstract int write(ByteBuffer source) throws IOException; |
| |
| /** |
| * Attempts to write a subset of the given bytes from the buffers to this |
| * socket channel. This method attempts to write all {@code remaining()} |
| * bytes from {@code length} byte buffers, in order, starting at {@code |
| * sources[offset]}. The number of bytes actually written is returned. |
| * <p> |
| * If a write operation is in progress, subsequent threads will block until |
| * the write is completed and then contend for the ability to write. |
| * |
| * @param sources |
| * the array of byte buffers that is the source for bytes written |
| * to this channel. |
| * @param offset |
| * the index of the first buffer in {@code buffers }to get bytes |
| * from. |
| * @param length |
| * the number of buffers to get bytes from. |
| * @return the number of bytes actually written to this channel. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread during this write |
| * operation. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IndexOutOfBoundsException |
| * if {@code offset < 0} or {@code length < 0}, or if {@code |
| * offset + length} is greater than the size of {@code sources}. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @throws NotYetConnectedException |
| * if this channel is not yet connected. |
| * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[], |
| * int, int) |
| */ |
| public abstract long write(ByteBuffer[] sources, int offset, int length) |
| throws IOException; |
| |
| /** |
| * Writes bytes from all the given byte buffers to this socket channel. |
| * <p> |
| * Calling this method is equivalent to calling {@code write(sources, 0, |
| * sources.length);} |
| * |
| * @param sources |
| * the buffers containing bytes to write. |
| * @return the number of bytes actually written. |
| * @throws AsynchronousCloseException |
| * if this channel is closed by another thread during this write |
| * operation. |
| * @throws ClosedByInterruptException |
| * if another thread interrupts the calling thread while this |
| * operation is in progress. The interrupt state of the calling |
| * thread is set and the channel is closed. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IOException |
| * if another I/O error occurs. |
| * @throws NotYetConnectedException |
| * if this channel is not yet connected. |
| * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[]) |
| */ |
| public synchronized final long write(ByteBuffer[] sources) |
| throws IOException { |
| return write(sources, 0, sources.length); |
| } |
| } |
