package jperipheral; import java.nio.CharBuffer; import java.util.concurrent.Future; import jperipheral.nio.channels.AsynchronousChannel; import jperipheral.nio.channels.CompletionHandler; import jperipheral.nio.channels.ReadPendingException; import jperipheral.nio.channels.ShutdownChannelGroupException; import jperipheral.nio.channels.WritePendingException; /** * An asynchronous channel that can read and write characters. * *

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 {@link ReadPendingException} will be thrown. * Similarly, if a write method is invoked before a previous write has completed * then {@link 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. * *

Note that {@link java.nio.CharBuffer 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. * * @author Gili Tzabari */ public interface AsynchronousCharChannel extends AsynchronousChannel { /** * 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 {@code * 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 {@code -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, * {@code target.remaining()} at the time that the read is attempted. Where * r is 0, the read operation completes immediately with a result of * {@code 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 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 {@link ReadPendingException} will be thrown. * * @param * The attachment type * @param target * The buffer into which characters are to be transferred * @param attachment * The object to attach to the I/O operation; can be {@code null} * @param handler * The completion handler * * @throws IllegalArgumentException * If the buffer is read-only * @throws ReadPendingException * If the channel does not allow more than one read to be outstanding * and a previous read has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ void read(CharBuffer target, A attachment, CompletionHandler 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 method * behaves in exactly the same manner as the {@link * #read(CharBuffer,Object,CompletionHandler) * read(CharBuffer,Object,CompletionHandler)} method except that instead * of a completion handler, this method returns a {@code Future} * representing the pending result. The {@link Future#get() get} method * returns the number of characters read or {@code -1} if no characters could be * read because the channel has reached end-of-stream. * * @param target * The buffer into which characters are to be transferred * * @return A Future representing the result of the operation * * @throws IllegalArgumentException * If the buffer is read-only * @throws ReadPendingException * If the channel does not allow more than one read to be outstanding * and a previous read has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ Future read(CharBuffer target) 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 {@code 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 (excluding termination characters) or {@code -1} 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 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 {@link ReadPendingException} will be thrown. * * @param * The attachment type * @param target * The buffer into which characters are to be transferred * @param attachment * The object to attach to the I/O operation; can be {@code null} * @param handler * The completion handler * * @throws IllegalArgumentException * If the buffer is read-only * @throws ReadPendingException * If the channel does not allow more than one read to be outstanding * and a previous read has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ void readLine(StringBuilder target, A attachment, CompletionHandler 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 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 {@link #readLine(StringBuilder,Object,CompletionHandler) * readLine(StringBuilder,Object,CompletionHandler)} method except that instead * of a completion handler, this method returns a {@code Future} * representing the pending result. The {@link Future#get() get} method * returns the number of characters read (excluding termination characters) * or {@code -1} if no characters could be read because the channel has reached end-of-stream. * * @param target * The buffer into which characters are to be transferred * * @return A Future representing the result of the operation * * @throws IllegalArgumentException * If the buffer is read-only * @throws ReadPendingException * If the channel does not allow more than one read to be outstanding * and a previous read has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ Future readLine(StringBuilder target) throws IllegalArgumentException, ReadPendingException, ShutdownChannelGroupException; /** * Writes a sequence of characters to this channel from the given buffer. * *

This method initiates an asynchronous write operation to write a * sequence of characters to this channel from the given buffer. The {@code * 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, * {@code src.remaining()} at the time that the write is attempted. Where * r is 0, the write operation completes immediately with a result of * {@code 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 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 {@link WritePendingException} will be thrown. * * @param * The attachment type * @param source * The buffer from which characters are to be retrieved * @param attachment * The object to attach to the I/O operation; can be {@code null} * @param handler * The completion handler object * @param endOfInput * true if, and only if, the invoker can provide no additional input characters beyond * those in the given buffer. * * @throws WritePendingException * If the channel does not allow more than one write to be outstanding * and a previous write has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ void write(CharBuffer source, A attachment, CompletionHandler handler, boolean endOfInput) throws WritePendingException, ShutdownChannelGroupException; /** * Writes a sequence of characters to this channel from the given buffer. * *

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 {@link * #write(CharBuffer,Object,CompletionHandler) * write(CharBuffer,Object,CompletionHandler)} method except that instead * of a completion handler, this method returns a {@code Future} * representing the pending result. The {@link Future#get() get} method * returns the number of characters written. * * @param source * The buffer from which characters are to be retrieved * @param endOfInput * true if, and only if, the invoker can provide no additional input characters beyond * those in the given buffer. * * @return A Future representing the result of the operation * * @throws WritePendingException * If the channel does not allow more than one write to be outstanding * and a previous write has not completed * @throws ShutdownChannelGroupException * If the channel group is shutdown */ Future write(CharBuffer source, boolean endOfInput) throws WritePendingException, ShutdownChannelGroupException; }