English | Site Directory

Android - An Open Handset Alliance Project

java.nio.channels
public abstract class

java.nio.channels.SocketChannel

java.lang.Object
java.nio.channels.spi.AbstractInterruptibleChannel Channel InterruptibleChannel
java.nio.channels.SelectableChannel Channel
java.nio.channels.spi.AbstractSelectableChannel
java.nio.channels.SocketChannel ByteChannel GatheringByteChannel ScatteringByteChannel

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.

Summary

Protected Constructors

          SocketChannel(SelectorProvider selectorProvider)
Constructor for this class.

Public Methods

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(SocketAddress address)
Create a socket channel and connect it to a socket address.
      static  SocketChannel  open()
Create a open and not-connected socket channel.
abstract        long  read(ByteBuffer[] targets, int offset, int length)
Reads bytes from the channel into a subset of the given buffers.
abstract        int  read(ByteBuffer target)
Reads bytes from the channel into the given buffer.
  synchronized  final    long  read(ByteBuffer[] targets)
Reads bytes from the channel into all the given buffers.
abstract        Socket  socket()
Return the related socket of this channel, which won't declare public methods that not declared in Socket.
    final    int  validOps()
Get the valid operations of this channel.
abstract        long  write(ByteBuffer[] sources, int offset, int length)
Writes a subset of the given bytes from the buffers to the channel.
  synchronized  final    long  write(ByteBuffer[] sources)
Writes bytes from all the given buffers to the channel.
abstract        int  write(ByteBuffer source)
Writes bytes from the given buffer to the channel.
Methods inherited from class java.nio.channels.spi.AbstractSelectableChannel
Methods inherited from class java.nio.channels.SelectableChannel
Methods inherited from class java.nio.channels.spi.AbstractInterruptibleChannel
Methods inherited from class java.lang.Object
Methods inherited from interface java.io.Closeable
Methods inherited from interface java.nio.channels.InterruptibleChannel
Methods inherited from interface java.nio.channels.GatheringByteChannel
Methods inherited from interface java.nio.channels.WritableByteChannel
Methods inherited from interface java.nio.channels.Channel
Methods inherited from interface java.nio.channels.ReadableByteChannel
Methods inherited from interface java.nio.channels.ScatteringByteChannel

Details

Protected Constructors

protected SocketChannel(SelectorProvider selectorProvider)

Constructor for this class.

Parameters

selectorProvider A instance of SelectorProvider

Public Methods

public abstract boolean connect(SocketAddress address)

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.

public abstract boolean finishConnect()

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.

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.

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.

public static SocketChannel open(SocketAddress address)

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.

public static SocketChannel open()

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.

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

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.

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.

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

public abstract int read(ByteBuffer target)

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.

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

public final synchronized long read(ByteBuffer[] targets)

Reads bytes from the channel into all the given buffers.

This method is equivalent to: 

 read(targets, 0, targets.length);

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

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.

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

Returns

  • Valid operations in bit-set.

See Also

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

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.

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

public final synchronized long write(ByteBuffer[] sources)

Writes bytes from all the given buffers to the channel.

This method is equivalent to: 

 write(buffers, 0, buffers.length);

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

public abstract int write(ByteBuffer source)

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.

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

Build m5-rc15i - 10 Jun 2008 13:54