org.jperipheral

Interface InterruptibleCharChannel

public interface InterruptibleCharChannel

An AsynchronousCharChannel whose operations may be interrupted.

Author:

Gili Tzabari

Method Summary

Methods

Modifier and Type	Method and Description
<A> void	close(A attachment, CompletionHandler<Void,? super A> handler) Closes this channel.
<A> void	read(CharBuffer target, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Reads a sequence of characters from this channel into the given buffer.
<A> void	readLine(long timeout, TimeUnit unit, A attachment, CompletionHandler<String,? super A> handler) Reads a line of characters from this channel into the given buffer.
<A> void	write(CharBuffer source, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Writes a sequence of characters to this channel from the given buffer.

Method Detail

read

<A> void read(CharBuffer target,
            long timeout,
            TimeUnit unit,
            A attachment,
            CompletionHandler<Integer,? super A> handler)
          throws IllegalArgumentException,
                 ReadPendingException,
                 ShutdownChannelGroupException

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

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.

If a timeout is specified and the timeout elapses before the operation completes then the operation completes with the exception InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that characters have not been read, or will not be read from the channel into the given buffer, then further attempts to read from the channel will cause an unspecific runtime exception to be thrown.

Otherwise this method works in the same manner as the AsynchronousByteChannel.read(ByteBuffer,Object,CompletionHandler) method.

Type Parameters:

A - The attachment type

Parameters:

target - The buffer into which characters are to be transferred

timeout - The timeout, or 0L for no timeout

unit - The time unit of the timeout argument

attachment - The object to attach to the I/O operation; can be null

handler - The handler for consuming the result

Throws:

IllegalArgumentException - If the timeout parameter is negative or the buffer is read-only

ReadPendingException - If a read operation is already in progress on this channel

ShutdownChannelGroupException - If the channel is associated with a group that has terminated

UnsupportedOperationException - If the implementation does not support this operation

readLine

<A> void readLine(long timeout,
                TimeUnit unit,
                A attachment,
                CompletionHandler<String,? super A> handler)
              throws IllegalArgumentException,
                     ReadPendingException,
                     ShutdownChannelGroupException

Reads a line of characters from this channel into the given buffer.

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.

Type Parameters:

A - The attachment type

Parameters:

timeout - The timeout, or 0L for no timeout

unit - The time unit of the timeout argument

attachment - The object to attach to the I/O operation; can be null

handler - The completion handler

Throws:

IllegalArgumentException - If the buffer is read-only

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

ShutdownChannelGroupException - If the channel is associated with a group that has terminated

write

<A> void write(CharBuffer source,
             long timeout,
             TimeUnit unit,
             A attachment,
             CompletionHandler<Integer,? super A> handler)

Writes a sequence of characters to this channel from the given buffer. (optional operation)

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.

If a timeout is specified and the timeout elapses before the operation completes then it completes with the exception InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that characters have not been written, or will not be written to the channel from the given buffer, then further attempts to write to the channel will cause an unspecific runtime exception to be thrown.

Otherwise this method works in the same manner as the AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler,boolean) method. 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.

Type Parameters:

A - The attachment type

Parameters:

source - The buffer from which characters are to be retrieved

timeout - The timeout, or 0L for no timeout

unit - The time unit of the timeout argument

attachment - The object to attach to the I/O operation; can be null

handler - The handler for consuming the result

Throws:

IllegalArgumentException - If the timeout parameter is negative

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

ShutdownChannelGroupException - If the channel is associated with a group that has terminated

UnsupportedOperationException - If the implementation does not support this operation

close

<A> void close(A attachment,
             CompletionHandler<Void,? super A> handler)

Closes this channel. The underlying channel might take an arbitrary amount of time to cancel outstanding operations. As such, this method returns immediately and a completion handler is notified when the operation completes.

This method otherwise behaves exactly as specified by AsynchronousChannel.close().

Type Parameters:

A - The attachment type

Parameters:

attachment - The object to attach to the I/O operation; can be null

handler - The handler for consuming the result