public abstract class SocketChannel extends AbstractSelectableChannel implements ByteChannel, ScatteringByteChannel, GatheringByteChannel
SocketChannel is a selectable channel that provides a partial
abstraction of stream connecting socket. socket() returns the related
Socket instance which can handle the socket.
A socket channel is open but not connected when created by open().
After connecting it by calling connect(SocketAddress), it will remain
connected until it gets closed. If the connection is non-blocking then
connect(SocketAddress) is used to initiate the connection, followed
by a call of finishConnect() to perform the final steps of
connecting. isConnectionPending() indicates if the connection is
blocked or not; isConnected() indicates if the socket is finally
connected or not.
The input and output sides of a channel can be shut down independently and
asynchronously without closing the channel. The 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 shutdownOutput method is used for the
output side of the channel; subsequent write operations throw a
ClosedChannelException. If the output is shut down and another thread
is blocked in a write operation, an AsynchronousCloseException will
be thrown to the pending thread.
Socket channels are thread-safe, no more than one thread can read or write at
any given time. The connect(SocketAddress) and finishConnect() methods are synchronized against each other; when they are
processing, calls to read and write will block.
| Modifier | Constructor and Description |
|---|---|
protected |
SocketChannel(SelectorProvider selectorProvider)
Constructs a new
SocketChannel. |
| Modifier and Type | Method and Description |
|---|---|
abstract boolean |
connect(SocketAddress address)
Connects this channel's socket with a remote address.
|
abstract boolean |
finishConnect()
Completes the connection process initiated by a call of
connect(SocketAddress). |
abstract boolean |
isConnected()
Indicates whether this channel's socket is connected.
|
abstract boolean |
isConnectionPending()
Indicates whether this channel's socket is still trying to connect.
|
static SocketChannel |
open()
Creates an open and unconnected socket channel.
|
static SocketChannel |
open(SocketAddress address)
Creates a socket channel and connects it to a socket address.
|
abstract int |
read(ByteBuffer target)
Reads bytes from this socket channel into the given buffer.
|
long |
read(ByteBuffer[] targets)
Reads bytes from this socket channel and stores them in the specified
array of buffers.
|
abstract long |
read(ByteBuffer[] targets,
int offset,
int length)
Reads bytes from this socket channel into a subset of the given buffers.
|
abstract Socket |
socket()
Returns the socket assigned to this channel, which does not declare any public
methods that are not declared in
Socket. |
int |
validOps()
Gets the valid operations of this channel.
|
abstract int |
write(ByteBuffer source)
Writes bytes from the given byte buffer to this socket channel.
|
long |
write(ByteBuffer[] sources)
Writes bytes from all the given byte buffers to this socket channel.
|
abstract long |
write(ByteBuffer[] sources,
int offset,
int length)
Attempts to write a subset of the given bytes from the buffers to this
socket channel.
|
blockingLock, configureBlocking, implCloseChannel, implCloseSelectableChannel, implConfigureBlocking, isBlocking, isRegistered, keyFor, provider, registerregisterbegin, close, end, isOpenprotected SocketChannel(SelectorProvider selectorProvider)
SocketChannel.selectorProvider - an instance of SelectorProvider.public static SocketChannel open() throws IOException
This channel is created by calling openSocketChannel() of the
default SelectorProvider instance.
IOException - if an I/O error occurs.public static SocketChannel open(SocketAddress address) throws IOException
This method performs a call to open() followed by a call to
connect(SocketAddress).
address - the socket address to be connected to.AsynchronousCloseException - if this channel is closed by another thread while this method
is executing.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.UnresolvedAddressException - if the address is not resolved.UnsupportedAddressTypeException - if the address type is not supported.IOException - if an I/O error occurs.public final int validOps()
SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE.validOps in class SelectableChannelSelectableChannel.validOps()public abstract Socket socket()
Socket.public abstract boolean isConnected()
true if this channel's socket is connected, false
otherwise.public abstract boolean isConnectionPending()
true if the connection is initiated but not finished;
false otherwise.public abstract boolean connect(SocketAddress address) throws IOException
If this channel is blocking, this method will suspend until connecting is
finished or an I/O exception occurs. If the channel is non-blocking,
this method will return true if the connection is finished at
once or return false when the connection must be finished later
by calling finishConnect().
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 Socket class.
address - the address to connect with.true if the connection is finished, false
otherwise.AlreadyConnectedException - if the channel is already connected.ConnectionPendingException - a non-blocking connecting operation is already executing on
this channel.ClosedChannelException - if this channel is closed.AsynchronousCloseException - if this channel is closed by another thread while this method
is executing.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.UnresolvedAddressException - if the address is not resolved.UnsupportedAddressTypeException - if the address type is not supported.IOException - if an I/O error occurs.public abstract boolean finishConnect()
throws IOException
connect(SocketAddress).
This method returns true if the connection is finished already
and returns false if the channel is non-blocking and the
connection is not finished yet.
If this channel is in blocking mode, this method will suspend and return
true when the connection is finished. It closes this channel and
throws an exception if the connection fails.
This method can be called at any moment and it can block other read and write operations while connecting.
true if the connection is successfully finished, false otherwise.NoConnectionPendingException - if the channel is not connected and the connection process
has not been initiated.ClosedChannelException - if this channel is closed.AsynchronousCloseException - if this channel is closed by another thread while this method
is executing.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.IOException - if an I/O error occurs.public abstract int read(ByteBuffer target) throws IOException
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.
The call may block if other threads are also attempting to read from this channel.
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.
read in interface ReadableByteChanneltarget - the byte buffer to receive the bytes.AsynchronousCloseException - if another thread closes the channel during the read.NotYetConnectedException - if this channel is not yet connected.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.ClosedChannelException - if this channel is closed.IOException - if another I/O error occurs.ReadableByteChannel.read(java.nio.ByteBuffer)public abstract long read(ByteBuffer[] targets, int offset, int length) throws IOException
remaining() bytes from length byte buffers, in order, starting at targets[offset]. The
number of bytes actually read is returned.
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.
read in interface ScatteringByteChanneltargets - the array of byte buffers into which the bytes will be copied.offset - the index of the first buffer to store bytes in.length - the maximum number of buffers to store bytes in.AsynchronousCloseException - if this channel is closed by another thread during this read
operation.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.ClosedChannelException - if this channel is closed.IndexOutOfBoundsException - if offset < 0 or length < 0, or if offset + length is greater than the size of targets.IOException - if another I/O error occurs.NotYetConnectedException - if this channel is not yet connected.ScatteringByteChannel.read(java.nio.ByteBuffer[],
int, int)public final long read(ByteBuffer[] targets) throws IOException
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.
Calling this method is equivalent to calling read(targets, 0,
targets.length);
read in interface ScatteringByteChanneltargets - the array of byte buffers into which the bytes will be copied.AsynchronousCloseException - if this channel is closed by another thread during this read
operation.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.ClosedChannelException - if this channel is closed.IOException - if another I/O error occurs.NotYetConnectedException - if this channel is not yet connected.public abstract int write(ByteBuffer source) throws IOException
The call may block if other threads are also attempting to write to the same channel.
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.
write in interface WritableByteChannelsource - the byte buffer containing the bytes to be written.AsynchronousCloseException - if another thread closes the channel during the write.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.ClosedChannelException - if the channel was already closed.IOException - if another I/O error occurs.NotYetConnectedException - if this channel is not connected yet.WritableByteChannel.write(java.nio.ByteBuffer)public abstract long write(ByteBuffer[] sources, int offset, int length) throws IOException
remaining()
bytes from length byte buffers, in order, starting at sources[offset]. The number of bytes actually written is returned.
If a write operation is in progress, subsequent threads will block until the write is completed and then contend for the ability to write.
write in interface GatheringByteChannelsources - the array of byte buffers that is the source for bytes written
to this channel.offset - the index of the first buffer in buffers to get bytes
from.length - the number of buffers to get bytes from.AsynchronousCloseException - if this channel is closed by another thread during this write
operation.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.ClosedChannelException - if this channel is closed.IndexOutOfBoundsException - if offset < 0 or length < 0, or if offset + length is greater than the size of sources.IOException - if another I/O error occurs.NotYetConnectedException - if this channel is not yet connected.GatheringByteChannel.write(java.nio.ByteBuffer[],
int, int)public final long write(ByteBuffer[] sources) throws IOException
Calling this method is equivalent to calling write(sources, 0,
sources.length);
write in interface GatheringByteChannelsources - the buffers containing bytes to write.AsynchronousCloseException - if this channel is closed by another thread during this write
operation.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.ClosedChannelException - if this channel is closed.IOException - if another I/O error occurs.NotYetConnectedException - if this channel is not yet connected.GatheringByteChannel.write(java.nio.ByteBuffer[])