com.sun.sgs.nio.channels
Interface AsynchronousByteChannel

All Superinterfaces:

Channel, Closeable

All Known Implementing Classes:

AsynchronousDatagramChannel, AsynchronousSocketChannel

public interface AsynchronousByteChannel
extends Channel

A channel that can read and write bytes asynchronously. Some channels may not allow more than one read to be outstanding at any given time. If a thread invokes a read method before a previous read operation has completed then a ReadPendingException will be thrown. Similarly, if a write method is invoked before a previous write has completed then WritePendingException is thrown. Whether or not other kinds of I/O operations may proceed concurrently with a read operation depends upon the type of the channel.

See Also:

Channels.newInputStream(AsynchronousByteChannel), Channels.newOutputStream(AsynchronousByteChannel)

Method Summary

<A> IoFuture<Integer,A>	read(ByteBuffer dst, A attachment, CompletionHandler<Integer,? super A> handler) Reads a sequence of bytes from this channel into the given buffer.
<A> IoFuture<Integer,A>	read(ByteBuffer dst, CompletionHandler<Integer,? super A> handler) Reads a sequence of bytes from this channel into the given buffer.
<A> IoFuture<Integer,A>	write(ByteBuffer src, A attachment, CompletionHandler<Integer,? super A> handler) Writes a sequence of bytes to this channel from the given buffer.
<A> IoFuture<Integer,A>	write(ByteBuffer src, CompletionHandler<Integer,? super A> handler) Writes a sequence of bytes to this channel from the given buffer.

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

read

<A> IoFuture<Integer,A> read(ByteBuffer dst,
                             A attachment,
                             CompletionHandler<Integer,? super A> handler)

Reads a sequence of bytes from this channel into the given buffer.

This method initiates an operation to read a sequence of bytes from this channel into the given buffer. The method returns an IoFuture representing the pending result of the operation. The result of the operation, obtained by invoking the IoFuture's get method, is the number of bytes read, possibly zero, or -1 if all bytes have been read and the channel has reached end-of-stream.

This method initiates a read operation to read up to r bytes from the channel, where r is the number of bytes remaining in the buffer, that is, dst.remaining() at the time that the read is attempted.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment the read is performed. Upon completion the buffer's position will be equal to p + n; its limit will not have changed.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not to access the buffer until the operaton has completed.

This method may be invoked at any time. Some channel types may not allow more than one read to be outstanding at any given time. If a thread initiates a read operation before a previous read operation has completed then a ReadPendingException will be thrown.

The handler parameter is used to specify a CompletionHandler. When the read operation completes the handler's completed method is executed.

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which bytes are to be transferred

attachment - the object to attach to the returned IoFuture object; can be null

handler - the completion handler object; can be null

Returns:

a future representing the result of the operation

Throws:

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if the channel does not allow more than one read to be outstanding and a previous read has not completed

read

<A> IoFuture<Integer,A> read(ByteBuffer dst,
                             CompletionHandler<Integer,? super A> handler)

Reads a sequence of bytes from this channel into the given buffer.

An invocation of this method of the form c.read(dst,handler) behaves in exactly the same manner as the invocation

   c.read(dst, null, handler);
 

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which bytes are to be transferred

handler - the completion handler object; can be null

Returns:

a future representing the result of the operation

Throws:

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if the channel does not allow more than one read to be outstanding and a previous read has not completed

write

<A> IoFuture<Integer,A> write(ByteBuffer src,
                              A attachment,
                              CompletionHandler<Integer,? super A> handler)

Writes a sequence of bytes to this channel from the given buffer.

This method initiates an operation to write a sequence of bytes to this channel from the given buffer. The method returns an IoFuture representing the pending result of the operation. The result of the operation, obtained by invoking the IoFuture's get method, is the number of bytes written, possibly zero.

This method initiates a write operation to write up to r bytes from the channel, where r is the number of bytes remaining in the buffer, that is, src.remaining() at the time that the write is attempted.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment the write is performed; the index of the last byte written will be p + n - 1. Upon completion the buffer's position will be equal to p + n; its limit will not have changed.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not to access the buffer until the operaton has completed.

This method may be invoked at any time. Some channel types may not allow more than one write to be outstanding at any given time. If a thread initiates a write operation before a previous write operation has completed then a WritePendingException will be thrown.

The handler parameter is used to specify a CompletionHandler. When the write operation completes the handler's completed method is executed.

Type Parameters:

A - the attachment type

Parameters:

src - the buffer from which bytes are to be retrieved

attachment - the object to attach to the returned IoFuture object; can be null

handler - the completion handler object; can be null

Returns:

a future representing the result of the operation

Throws:

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if the channel does not allow more than one write to be outstanding and a previous write has not completed

write

<A> IoFuture<Integer,A> write(ByteBuffer src,
                              CompletionHandler<Integer,? super A> handler)

Writes a sequence of bytes to this channel from the given buffer.

An invocation of this method of the form c.write(src,handler) behaves in exactly the same manner as the invocation

   c.write(src, null, handler);
 

Type Parameters:

A - the attachment type

Parameters:

src - the buffer from which bytes are to be retrieved

handler - the completion handler object; can be null

Returns:

a future representing the result of the operation

Throws:

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if the channel does not allow more than one write to be outstanding and a previous write has not completed