java.nio.channels
Class SocketChannel

java.lang.Object
  java.nio.channels.spi.AbstractInterruptibleChannel
      java.nio.channels.SelectableChannel
          java.nio.channels.spi.AbstractSelectableChannel
              java.nio.channels.SocketChannel

All Implemented Interfaces:

Closeable, ByteChannel, Channel, GatheringByteChannel, InterruptibleChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel

public abstract class SocketChannel
extends AbstractSelectableChannel
implements ByteChannel, ScatteringByteChannel, GatheringByteChannel

A SocketChannel is a selectable channel for part abstraction of stream connecting socket. The socket method of this class can return the related Socket instance, which can handle the socket.

A socket channel is open but not connected when created by open method. After connected by calling the connect method, it will keep connected before closed. The connection is non-blocking that the connect method is for the initial connection and following finishConnect method is for the final steps of connection. The isConnectionPending method can tell the connection is blocked or not; the isConnected method can tell the socket is connected finally or not.

The shut down operation can be independent and asynchronous for input and output. The shutdownInput method is for input, and can make the following read operation fail as end of stream. If the input is shut down and another thread is pending in read operation, the read will end without effect and return end of stream. The shutdownOutput method is for output, and can make the following write operation throwing a ClosedChannelException. If the output is shut down and another is pending in a write operation, an AsynchronousCloseException will thrown to the pending thread.

Socket channels are thread-safe, no more than one thread can read or write at given time. The connect and finishConnect methods are concurrent each other, when they are processing, other read and write will block.

Constructor Summary

protected

SocketChannel(SelectorProvider selectorProvider) Constructor for this class.

Method Summary

abstract boolean	connect(SocketAddress address) Connect the socket to remote address.
abstract boolean	finishConnect() Complete the connection.
abstract boolean	isConnected() Answer whether this channel's socket is connected or not.
abstract boolean	isConnectionPending() Answer whether this channel's socket is in connecting or not.
static SocketChannel	open() Create a open and not-connected socket channel.
static SocketChannel	open(SocketAddress address) Create a socket channel and connect it to a socket address.
abstract int	read(ByteBuffer target) Reads bytes from the channel into the given buffer.
long	read(ByteBuffer[] targets) Reads bytes from the channel into all the given buffers.
abstract long	read(ByteBuffer[] targets, int offset, int length) Reads bytes from the channel into a subset of the given buffers.
abstract Socket	socket() Return the related socket of this channel, which won't declare public methods that not declared in Socket.
int	validOps() Get the valid operations of this channel.
abstract int	write(ByteBuffer source) Writes bytes from the given buffer to the channel.
long	write(ByteBuffer[] sources) Writes bytes from all the given buffers to the channel.
abstract long	write(ByteBuffer[] sources, int offset, int length) Writes a subset of the given bytes from the buffers to the channel.

Methods inherited from class java.nio.channels.spi.AbstractSelectableChannel

blockingLock, configureBlocking, implCloseChannel, implCloseSelectableChannel, implConfigureBlocking, isBlocking, isRegistered, keyFor, provider, register

Methods inherited from class java.nio.channels.SelectableChannel

register

Methods inherited from class java.nio.channels.spi.AbstractInterruptibleChannel

begin, close, end, isOpen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Constructor Detail

SocketChannel

protected SocketChannel(SelectorProvider selectorProvider)

Constructor for this class.

Parameters:

selectorProvider - A instance of SelectorProvider

Method Detail

open

public static SocketChannel open()
                          throws IOException

Create a open and not-connected socket channel.

This channel is got by openSocketChannel method of the default SelectorProvider instance.

Returns:

The new created channel which is open but not-connected.

Throws:

IOException - If some IO problem occurs.

open

public static SocketChannel open(SocketAddress address)
                          throws IOException

Create a socket channel and connect it to a socket address.

This method perform just as open method following by the connect method.

Parameters:

address - The socket address to be connected.

Returns:

The new opened channel.

Throws:

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. 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.

SecurityException - If there is a security manager, and the address is not permitted to access.

IOException - Some other IO error occurred.

validOps

public final int validOps()

Get 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 ).

Specified by:

validOps in class SelectableChannel

Returns:

Valid operations in bit-set.

See Also:

SelectableChannel.validOps()

socket

public abstract Socket socket()

Return the related socket of this channel, which won't declare public methods that not declared in Socket.

Returns:

The related Socket instance.

isConnected

public abstract boolean isConnected()

Answer whether this channel's socket is connected or not.

Returns:

true for this channel's socket is connected; false otherwise.

isConnectionPending

public abstract boolean isConnectionPending()

Answer whether this channel's socket is in connecting or not.

Returns:

true for the connection is initiated but not finished; false otherwise.

connect

public abstract boolean connect(SocketAddress address)
                         throws IOException

Connect the socket to remote address.

If the channel is blocking, this method will suspend before connection finished or an I/O exception. If the channel is non-blocking, this method will return true if the connection is finished at once or return false and the connection must wait finishConnect to finished otherwise.

This method can be called at any moment, and can block other read and write operations while connecting.

This method just execute the same security checks as the connect method of the Socket class.

Parameters:

address - The address to be connected.

Returns:

true if connection is finished,false otherwise.

Throws:

AlreadyConnectedException - If the channel is connected already.

ConnectionPendingException - A non-blocking connecting is doing on this channel.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. 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.

SecurityException - If there is a security manager, and the address is not permitted to access.

IOException - Some other IO error occurred.

finishConnect

public abstract boolean finishConnect()
                               throws IOException

Complete the connection.

This method is used when the channel is connectable to finish the connection, and the connectable status of a channel means the channel is after initiating in non-blocking mode and calling its connect method. It will throw related IOException if the connection failed.

This method will return true if the connection is finished already, and return false if the channel is non-blocking and the connection is not finished yet.

If the channel is in blocking mode, this method will suspend, and return true for connection finished or throw some exception otherwise. The channel will be closed if the connection failed and this method thrown some exception.

This method can be called at any moment, and can block other read and write operations while connecting.

Returns:

true if the connection is successfully finished, false otherwise.

Throws:

NoConnectionPendingException - If the channel is not connected and the connection is not initiated.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

read

public abstract int read(ByteBuffer target)
                  throws IOException

Reads bytes from the 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 invoked. The bytes will be read into the buffer starting at the buffer's position.

The call may block if other threads are also attempting to read on the same channel.

Upon completion, the buffer's position() is updated to the end of the bytes that were read. The buffer's limit() is unmodified.

Specified by:

read in interface ReadableByteChannel

Parameters:

target - The byte buffer to receive the bytes.

Returns:

The number of bytes actually read.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

ReadableByteChannel.read(java.nio.ByteBuffer)

read

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

Reads bytes from the channel into a subset of the given buffers.

This method attempts to read all of the 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.

Specified by:

read in interface ScatteringByteChannel

Parameters:

targets - the array of byte buffers into which the bytes will be read.

offset - the index of the first buffer to read.

length - the maximum number of buffers to read.

Returns:

the number of bytes actually read.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

ScatteringByteChannel.read(java.nio.ByteBuffer[], int, int)

read

public final long read(ByteBuffer[] targets)
                throws IOException

Reads bytes from the channel into all the given buffers.

This method is equivalent to:

 read(targets, 0, targets.length);
 

Specified by:

read in interface ScatteringByteChannel

Parameters:

targets - the array of byte buffers to receive the bytes being read.

Returns:

the number of bytes actually read.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

ScatteringByteChannel.read(java.nio.ByteBuffer[])

write

public abstract int write(ByteBuffer source)
                   throws IOException

Writes bytes from the given buffer to the channel.

The maximum number of bytes that will be written is the remaining() number of bytes in the buffer when the method invoked. The bytes will be written from the buffer starting at the buffer's position.

The call may block if other threads are also attempting to write on the same channel.

Upon completion, the buffer's position() is updated to the end of the bytes that were written. The buffer's limit() is unmodified.

Specified by:

write in interface WritableByteChannel

Parameters:

source - the byte buffer containing the bytes to be written.

Returns:

the number of bytes actually written.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

WritableByteChannel.write(java.nio.ByteBuffer)

write

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

Writes a subset of the given bytes from the buffers to the channel.

This method attempts to write all of the 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 will then contend for the ability to write.

Specified by:

write in interface GatheringByteChannel

Parameters:

sources - the array of byte buffers containing the source of remaining bytes that will be attempted to be written.

offset - the index of the first buffer to write.

length - the number of buffers to write.

Returns:

the number of bytes actually written.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

GatheringByteChannel.write(java.nio.ByteBuffer[], int, int)

write

public final long write(ByteBuffer[] sources)
                 throws IOException

Writes bytes from all the given buffers to the channel.

This method is equivalent to:

 write(buffers, 0, buffers.length);
 

Specified by:

write in interface GatheringByteChannel

Parameters:

sources - the buffers containing bytes to be written.

Returns:

the number of bytes actually written.

Throws:

NotYetConnectedException - If the channel is not connected yet.

ClosedChannelException - If the channel is already closed.

AsynchronousCloseException - If the channel is closed by another thread while this method is in operation.

ClosedByInterruptException - If another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.

IOException - Some other IO error occurred.

See Also:

GatheringByteChannel.write(java.nio.ByteBuffer[])