Build 1.0_r1(from source)

java.nio.channels
Class SocketChannel

java.lang.Object
  extended by java.nio.channels.spi.AbstractInterruptibleChannel
      extended by java.nio.channels.SelectableChannel
          extended by java.nio.channels.spi.AbstractSelectableChannel
              extended by 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[])

Build 1.0_r1(from source)

Please submit a feedback, bug or feature