/*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.ok2c.lightnio;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
import java.nio.charset.CharacterCodingException;
import com.ok2c.lightnio.buffer.CharArrayBuffer;
/**
* Session input buffer for non-blocking connections. This interface facilitates
* intermediate buffering of input data streamed from a source channel and
* reading buffered data to a destination, usually {@link ByteBuffer} or
* {@link WritableByteChannel}. This interface also provides methods for reading
* lines of text.
*/
public interface SessionInputBuffer {
/**
* Determines if the buffer contains data.
*
* @return <code>true</code> if there is data in the buffer,
* <code>false</code> otherwise.
*/
boolean hasData();
/**
* Returns the length of this buffer.
*
* @return buffer length.
*/
int length();
/**
* Returns the total capacity of this buffer.
*
* @return total buffer capacity.
*/
int capacity();
/**
* Returns the available capacity of this buffer.
*
* @return available buffer capacity.
*/
int available();
/**
* Makes an attempt to fill the buffer with data from the given
* {@link ReadableByteChannel}.
*
* @param src the source channel
* @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
* channel has reached end-of-stream.
* @throws IOException in case of an I/O error.
*/
int fill(ReadableByteChannel src) throws IOException;
/**
* Reads one byte from the buffer. If the buffer is empty this method can
* throw a runtime exception. The exact type of runtime exception thrown
* by this method depends on implementation.
*
* @return one byte
*/
int read();
/**
* Reads a sequence of bytes from this buffer into the destination buffer,
* up to the given maximum limit. The exact number of bytes transferred
* depends on availability of data in this buffer and capacity of the
* destination buffer, but cannot be more than <code>maxLen</code> value.
*
* @param dst the destination buffer.
* @param maxLen the maximum number of bytes to be read.
* @return The number of bytes read, possibly zero.
*/
int read(ByteBuffer dst, int maxLen);
/**
* Reads a sequence of bytes from this buffer into the destination buffer.
* The exact number of bytes transferred depends on availability of data
* in this buffer and capacity of the destination buffer.
*
* @param dst the destination buffer.
* @return The number of bytes read, possibly zero.
*/
int read(ByteBuffer dst);
/**
* Reads a sequence of bytes from this buffer into the destination channel,
* up to the given maximum limit. The exact number of bytes transferred
* depends on availability of data in this buffer, but cannot be more than
* <code>maxLen</code> value.
*
* @param dst the destination channel.
* @param maxLen the maximum number of bytes to be read.
* @return The number of bytes read, possibly zero.
* @throws IOException in case of an I/O error.
*/
int read(WritableByteChannel dst, int maxLen) throws IOException;
/**
* Reads a sequence of bytes from this buffer into the destination channel.
* The exact number of bytes transferred depends on availability of data in
* this buffer.
*
* @param dst the destination channel.
* @return The number of bytes read, possibly zero.
* @throws IOException in case of an I/O error.
*/
int read(WritableByteChannel dst) throws IOException;
/**
* Attempts to transfer a complete line of characters up to a line delimiter
* from this buffer to the destination buffer. If a complete line is
* available in the buffer, the sequence of chars is transferred to the
* destination buffer the method returns <code>true</code>. The line
* delimiter itself is discarded. If a complete line is not available in
* the buffer, this method returns <code>false</code> without transferring
* anything to the destination buffer. If <code>endOfStream</code> parameter
* is set to <code>true</code> this method assumes the end of stream has
* been reached and the content currently stored in the buffer should be
* treated as a complete line.
* <p>
* The choice of a char encoding and line delimiter sequence is up to the
* specific implementations of this interface.
*
* @param dst the destination buffer.
* @param endOfStream
* @return <code>true</code> if a sequence of chars representing a complete
* line has been transferred to the destination buffer, <code>false</code>
* otherwise.
*
* @throws CharacterCodingException in case a character encoding or decoding
* error occurs.
*/
boolean readLine(CharArrayBuffer dst, boolean endOfStream)
throws CharacterCodingException;
/**
* Attempts to transfer a complete line of characters up to a line delimiter
* from this buffer to a newly created string. If a complete line is
* available in the buffer, the sequence of chars is transferred to a newly
* created string. The line delimiter itself is discarded. If a complete
* line is not available in the buffer, this method returns
* <code>null</code>. If <code>endOfStream</code> parameter
* is set to <code>true</code> this method assumes the end of stream has
* been reached and the content currently stored in the buffer should be
* treated as a complete line.
* <p>
* The choice of a char encoding and line delimiter sequence is up to the
* specific implementations of this interface.
*
* @param endOfStream
* @return a string representing a complete line, if available.
* <code>null</code> otherwise.
*
* @throws CharacterCodingException in case a character encoding or decoding
* error occurs.
*/
String readLine(boolean endOfStream)
throws CharacterCodingException;
}