public interface AsynchronousCharChannel extends AsynchronousChannel
Some channels may not allow more than one read or write to be outstanding
at any given time. If a thread invokes a read method before a previous read
operation has completed then a ReadPendingException might be thrown.
Similarly, if a write method is invoked before a previous write has completed
then WritePendingException might be thrown. Whether or not other kinds of
I/O operations may proceed concurrently with a read operation depends upon
the type of the channel.
Note that CharBuffers are not safe for use by
multiple concurrent threads. When a read or write operation is initiated then
care must be taken to ensure that the buffer is not accessed until the
operation completes.
Some implementations may not perform one or more of these operations,
throwing a runtime exception (UnsupportedOperationException) if
they are attempted. Implementations must specify in their documentation which
optional operations they support.
The read
and write
methods defined by this class allow a timeout to be specified when initiating
a read or write operation. If the timeout elapses before an operation completes
then the operation completes with the exception InterruptedByTimeoutException. A timeout may leave the channel, or the
underlying connection, in an inconsistent state. Where the implementation
cannot guarantee that bytes have not been read from the channel then it puts
the channel into an implementation specific error state. A subsequent
attempt to initiate a read operation causes an unspecified runtime
exception to be thrown. Similarly if a write operation times out and
the implementation cannot guarantee bytes have not been written to the
channel then further attempts to write to the channel cause an
unspecified runtime exception to be thrown. When a timeout elapses then the
state of the ByteBuffer, or the sequence of buffers, for the I/O
operation is not defined. Buffers should be discarded or at least care must
be taken to ensure that the buffers are not accessed while the channel remains
open. All methods that accept timeout parameters treat values less than or equal to zero to mean
that the I/O operation times out immediately, and a value of Long.MAX_VALUE to mean
that the I/O operation does not timeout.
| Modifier and Type | Method and Description |
|---|---|
Future<Integer> |
read(CharBuffer target)
Reads a sequence of characters from this channel into the given buffer.
|
<A> void |
read(CharBuffer target,
A attachment,
CompletionHandler<Integer,? super A> handler)
Reads a sequence of characters from this channel into the given buffer.
|
Future<String> |
readLine()
Reads a line of characters from this channel into the given buffer.
|
<A> void |
readLine(A attachment,
CompletionHandler<String,? super A> handler)
Reads a line of characters from this channel into the given buffer.
|
Future<Integer> |
write(CharBuffer source)
Writes a sequence of characters to this channel from the given buffer.
|
<A> void |
write(CharBuffer source,
A attachment,
CompletionHandler<Integer,? super A> handler)
Writes a sequence of characters to this channel from the given buffer.
|
close<A> void read(CharBuffer target, A attachment, CompletionHandler<Integer,? super A> handler) throws IllegalArgumentException, ReadPendingException, ShutdownChannelGroupException
This method initiates an asynchronous read operation to read a
sequence of characters from this channel into the given buffer. The handler parameter is a completion handler that is invoked when the read
operation completes (or fails). The result passed to the completion
handler is the number of characters read or -1 if no characters could be
read because the channel has reached end-of-stream.
The read operation may read up to r characters from the channel,
where r is the number of characters remaining in the buffer, that is,
target.remaining() at the time that the read is attempted. Where
r is 0, the read operation completes immediately with a result of
0 without initiating an I/O operation.
Suppose that a character sequence of length n is read, where 0 < n <= r. This character sequence will be transferred into the buffer so that the first character in the sequence is at index p and the last character 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 operation 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 might be thrown.
A - The attachment typetarget - The buffer into which characters are to be transferredattachment - The object to attach to the I/O operation; can be nullhandler - The completion handlerIllegalArgumentException - If the buffer is read-onlyReadPendingException - If the channel does not allow more than one read to be outstanding
and a previous read has not completedShutdownChannelGroupException - If the channel is associated with a group that has terminatedFuture<Integer> read(CharBuffer target) throws IllegalArgumentException, ReadPendingException
This method initiates an asynchronous read operation to read a
sequence of characters from this channel into the given buffer. The method
behaves in exactly the same manner as the read(CharBuffer,Object,CompletionHandler) method except that instead
of a completion handler, this method returns a Future
representing the pending result. The get method
returns the number of characters read or -1 if no characters could be
read because the channel has reached end-of-stream.
target - The buffer into which characters are to be transferredIllegalArgumentException - If the buffer is read-onlyReadPendingException - If the channel does not allow more than one read to be outstanding
and a previous read has not completed<A> void readLine(A attachment,
CompletionHandler<String,? super A> handler)
throws IllegalArgumentException,
ReadPendingException,
ShutdownChannelGroupException
This method initiates an asynchronous read operation to read a
line of characters from this channel into the given buffer. A line
is delimited by any one of a line feed '\n',
a carriage return '\r', or a carriage return followed
immediately by a linefeed. The handler parameter is a completion
handler that is invoked when the read operation completes (or fails).
The result passed to the completion handler is the line of characters
that was read (excluding termination characters) or null if no
characters could be read because the channel has reached end-of-stream.
Suppose that a character sequence of length n is read, where n > 0. This character sequence will be transferred into the buffer so that the first character in the sequence is at index p and the last character is at index p + n - 1 - d, where p is the buffer's position at the moment the read is performed and d is the length of the line delimiter. Upon completion the buffer's position will be equal to p + n - d; 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 operation 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 might be thrown.
A - The attachment typeattachment - The object to attach to the I/O operation; can be nullhandler - The completion handlerIllegalArgumentException - If the buffer is read-onlyReadPendingException - If the channel does not allow more than one read to be outstanding
and a previous read has not completedShutdownChannelGroupException - If the channel is associated with a group that has terminatedFuture<String> readLine() throws IllegalArgumentException, ReadPendingException
This method initiates an asynchronous read operation to read a
line of characters from this channel into the given buffer. A line
is considered to be terminated by any one of a line feed '\n',
a carriage return '\r', or a carriage return followed
immediately by a linefeed. The method behaves in exactly the same manner
as the readLine(StringBuilder,Object,CompletionHandler) method except that instead
of a completion handler, this method returns a Future
representing the pending result. The get method
returns the line of characters that were read (excluding termination characters)
or null if no characters could be read because the channel has reached end-of-stream.
IllegalArgumentException - If the buffer is read-onlyReadPendingException - If the channel does not allow more than one read to be outstanding
and a previous read has not completed<A> void write(CharBuffer source, A attachment, CompletionHandler<Integer,? super A> handler) throws WritePendingException, ShutdownChannelGroupException
This method initiates an asynchronous write operation to write a
sequence of characters to this channel from the given buffer. The handler parameter is a completion handler that is invoked when the write
operation completes (or fails). The result passed to the completion
handler is the number of characters written.
The write operation may write up to r characters to the channel,
where r is the number of characters remaining in the buffer, that is,
src.remaining() at the time that the write is attempted. Where
r is 0, the write operation completes immediately with a result of
0 without initiating an I/O operation.
Suppose that a character sequence of length n is written, where 0 < n <= r. This character 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 character 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 operation 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 might be thrown.
The handler fails with MalformedInputException if source is not a legal
sixteen-bit Unicode sequence or UnmappableCharacterException if source is valid
but cannot be mapped to an output byte sequence.
A - The attachment typesource - The buffer from which characters are to be retrievedattachment - The object to attach to the I/O operation; can be nullhandler - The completion handler objectWritePendingException - If the channel does not allow more than one write to be outstanding
and a previous write has not completedShutdownChannelGroupException - If the channel is associated with a group that has terminatedFuture<Integer> write(CharBuffer source) throws WritePendingException
This method initiates an asynchronous write operation to write a
sequence of characters to this channel from the given buffer. The method
behaves in exactly the same manner as the write(CharBuffer,Object,CompletionHandler) method except that instead
of a completion handler, this method returns a Future
representing the pending result. The get method
returns the number of characters written.
The future fails with MalformedInputException if source is not a legal
sixteen-bit Unicode sequence or UnmappableCharacterException if source is valid
but cannot be mapped to an output byte sequence.
source - The buffer from which characters are to be retrievedWritePendingException - If the channel does not allow more than one write to be outstanding
and a previous write has not completedCopyright © 2011. All Rights Reserved.