Android APIs
public abstract class

SocketChannel

extends AbstractSelectableChannel
implements ByteChannel ScatteringByteChannel GatheringByteChannel
java.lang.Object
   ↳ java.nio.channels.spi.AbstractInterruptibleChannel
     ↳ java.nio.channels.SelectableChannel
       ↳ java.nio.channels.spi.AbstractSelectableChannel
         ↳ java.nio.channels.SocketChannel

Class Overview

A SocketChannel is a selectable channel that provides a partial abstraction of stream connecting socket. The socket() method returns a Socket instance which allows a wider range of socket operations than SocketChannel itself.

A socket channel is open but not connected when created by open(). After connecting it by calling connect(SocketAddress), it will remain connected until 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() to tests whether we're still trying to connect; isConnected() tests whether the socket connect completed successfully. Note that realistic code should use a Selector instead of polling. Note also that Socket can connect with a timeout, which is the most common use for a non-blocking connect.

The input and output sides of a channel can be shut down independently and asynchronously without closing the channel. The shutdownInput() method on the socket returned by socket() 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. Likewise 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(ByteBuffer) and write(ByteBuffer) will block.

Summary

Protected Constructors
SocketChannel(SelectorProvider selectorProvider)
Constructs a new SocketChannel.
Public Methods
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.
abstract long read(ByteBuffer[] targets, int offset, int length)
Reads bytes from this socket channel into a subset of the given buffers.
final long read(ByteBuffer[] targets)
Reads bytes from this socket channel and stores them in the specified array of buffers.
abstract Socket socket()
Returns the socket assigned to this channel, which does not declare any public methods that are not declared in Socket.
final int validOps()
Gets the valid operations of this channel.
final 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.
abstract int write(ByteBuffer source)
Writes bytes from the given byte buffer to this socket channel.
[Expand]
Inherited Methods
From class java.nio.channels.spi.AbstractSelectableChannel
From class java.nio.channels.SelectableChannel
From class java.nio.channels.spi.AbstractInterruptibleChannel
From class java.lang.Object
From interface java.nio.channels.Channel
From interface java.nio.channels.InterruptibleChannel
From interface java.nio.channels.ScatteringByteChannel
From interface java.nio.channels.GatheringByteChannel
From interface java.io.Closeable
From interface java.nio.channels.ReadableByteChannel
From interface java.nio.channels.WritableByteChannel
From interface java.lang.AutoCloseable

Protected Constructors

protected SocketChannel (SelectorProvider selectorProvider)

Added in API level 1

Constructs a new SocketChannel.

Parameters
selectorProvider SelectorProvider: an instance of SelectorProvider.

Public Methods

public abstract boolean connect (SocketAddress address)

Added in API level 1

Connects this channel's socket with a remote address.

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.

Parameters
address SocketAddress: the address to connect with.
Returns
boolean true if the connection is finished, false otherwise.
Throws
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 ()

Added in API level 1

Completes the connection process initiated by a call of 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.

Returns
boolean true if the connection is successfully finished, false otherwise.
Throws
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 boolean isConnected ()

Added in API level 1

Indicates whether this channel's socket is connected.

Returns
boolean true if this channel's socket is connected, false otherwise.

public abstract boolean isConnectionPending ()

Added in API level 1

Indicates whether this channel's socket is still trying to connect.

Returns
boolean true if the connection is initiated but not finished; false otherwise.

public static SocketChannel open ()

Added in API level 1

Creates an open and unconnected socket channel.

This channel is created by calling openSocketChannel() of the default SelectorProvider instance.

Returns
SocketChannel the new channel which is open but unconnected.
Throws
IOException if an I/O error occurs.

public static SocketChannel open (SocketAddress address)

Added in API level 1

Creates a socket channel and connects it to a socket address.

This method performs a call to open() followed by a call to connect(SocketAddress).

Parameters
address SocketAddress: the socket address to be connected to.
Returns
SocketChannel the new connected channel.
Throws
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 abstract int read (ByteBuffer target)

Added in API level 1

Reads bytes from this socket channel into the given buffer.

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.

Parameters
target ByteBuffer: the byte buffer to receive the bytes.
Returns
int the number of bytes actually read.
Throws
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.

public abstract long read (ByteBuffer[] targets, int offset, int length)

Added in API level 1

Reads bytes from this socket channel into a subset of the given buffers. This method attempts to read all 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.

Parameters
targets ByteBuffer: the array of byte buffers into which the bytes will be copied.
offset int: the index of the first buffer to store bytes in.
length int: the maximum number of buffers to store bytes in.
Returns
long the number of bytes actually read.
Throws
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.

public final long read (ByteBuffer[] targets)

Added in API level 1

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.

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);

Parameters
targets ByteBuffer: the array of byte buffers into which the bytes will be copied.
Returns
long the number of bytes actually read.
Throws
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 Socket socket ()

Added in API level 1

Returns the socket assigned to this channel, which does not declare any public methods that are not declared in Socket.

Returns
Socket the socket assigned to this channel.

public final int validOps ()

Added in API level 1

Gets the valid operations of this channel. Socket channels support connect, read and write operation, so this method returns SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE.

Returns
int the operations supported by this channel.

See also:

public final long write (ByteBuffer[] sources)

Added in API level 1

Writes bytes from all the given byte buffers to this socket channel.

Calling this method is equivalent to calling write(sources, 0, sources.length);

Parameters
sources ByteBuffer: the buffers containing bytes to write.
Returns
long the number of bytes actually written.
Throws
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.

public abstract long write (ByteBuffer[] sources, int offset, int length)

Added in API level 1

Attempts to write a subset of the given bytes from the buffers to this socket channel. This method attempts to write all 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.

Parameters
sources ByteBuffer: the array of byte buffers that is the source for bytes written to this channel.
offset int: the index of the first buffer in buffers to get bytes from.
length int: the number of buffers to get bytes from.
Returns
long the number of bytes actually written to this channel.
Throws
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.

public abstract int write (ByteBuffer source)

Added in API level 1

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.

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.

Parameters
source ByteBuffer: the byte buffer containing the bytes to be written.
Returns
int the number of bytes actually written.
Throws
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.