001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http.nio.reactor; 029 030import java.io.IOException; 031import java.nio.ByteBuffer; 032import java.nio.channels.ReadableByteChannel; 033import java.nio.channels.WritableByteChannel; 034import java.nio.charset.CharacterCodingException; 035 036import org.apache.http.util.CharArrayBuffer; 037 038/** 039 * Session input buffer for non-blocking connections. This interface facilitates 040 * intermediate buffering of input data streamed from a source channel and 041 * reading buffered data to a destination, usually {@link ByteBuffer} or 042 * {@link WritableByteChannel}. This interface also provides methods for reading 043 * lines of text. 044 * 045 * @since 4.0 046 */ 047public interface SessionInputBuffer { 048 049 /** 050 * Determines if the buffer contains data. 051 * 052 * @return {@code true} if there is data in the buffer, 053 * {@code false} otherwise. 054 */ 055 boolean hasData(); 056 057 /** 058 * Returns the length of this buffer. 059 * 060 * @return buffer length. 061 */ 062 int length(); 063 064 /** 065 * Makes an attempt to fill the buffer with data from the given 066 * {@link ReadableByteChannel}. 067 * 068 * @param src the source channel 069 * @return The number of bytes read, possibly zero, or {@code -1} if the 070 * channel has reached end-of-stream. 071 * @throws IOException in case of an I/O error. 072 */ 073 int fill(ReadableByteChannel src) throws IOException; 074 075 /** 076 * Reads one byte from the buffer. If the buffer is empty this method can 077 * throw a runtime exception. The exact type of runtime exception thrown 078 * by this method depends on implementation. 079 * 080 * @return one byte 081 */ 082 int read(); 083 084 /** 085 * Reads a sequence of bytes from this buffer into the destination buffer, 086 * up to the given maximum limit. The exact number of bytes transferred 087 * depends on availability of data in this buffer and capacity of the 088 * destination buffer, but cannot be more than {@code maxLen} value. 089 * 090 * @param dst the destination buffer. 091 * @param maxLen the maximum number of bytes to be read. 092 * @return The number of bytes read, possibly zero. 093 */ 094 int read(ByteBuffer dst, int maxLen); 095 096 /** 097 * Reads a sequence of bytes from this buffer into the destination buffer. 098 * The exact number of bytes transferred depends on availability of data 099 * in this buffer and capacity of the destination buffer. 100 * 101 * @param dst the destination buffer. 102 * @return The number of bytes read, possibly zero. 103 */ 104 int read(ByteBuffer dst); 105 106 /** 107 * Reads a sequence of bytes from this buffer into the destination channel, 108 * up to the given maximum limit. The exact number of bytes transferred 109 * depends on availability of data in this buffer, but cannot be more than 110 * {@code maxLen} value. 111 * 112 * @param dst the destination channel. 113 * @param maxLen the maximum number of bytes to be read. 114 * @return The number of bytes read, possibly zero. 115 * @throws IOException in case of an I/O error. 116 */ 117 int read(WritableByteChannel dst, int maxLen) throws IOException; 118 119 /** 120 * Reads a sequence of bytes from this buffer into the destination channel. 121 * The exact number of bytes transferred depends on availability of data in 122 * this buffer. 123 * 124 * @param dst the destination channel. 125 * @return The number of bytes read, possibly zero. 126 * @throws IOException in case of an I/O error. 127 */ 128 int read(WritableByteChannel dst) throws IOException; 129 130 /** 131 * Attempts to transfer a complete line of characters up to a line delimiter 132 * from this buffer to the destination buffer. If a complete line is 133 * available in the buffer, the sequence of chars is transferred to the 134 * destination buffer the method returns {@code true}. The line 135 * delimiter itself is discarded. If a complete line is not available in 136 * the buffer, this method returns {@code false} without transferring 137 * anything to the destination buffer. If {@code endOfStream} parameter 138 * is set to {@code true} this method assumes the end of stream has 139 * been reached and the content currently stored in the buffer should be 140 * treated as a complete line. 141 * <p> 142 * The choice of a char encoding and line delimiter sequence is up to the 143 * specific implementations of this interface. 144 * 145 * @param dst the destination buffer. 146 * @param endOfStream end of stream flag 147 * @return {@code true} if a sequence of chars representing a complete 148 * line has been transferred to the destination buffer, {@code false} 149 * otherwise. 150 * 151 * @throws CharacterCodingException in case a character encoding or decoding 152 * error occurs. 153 */ 154 boolean readLine(CharArrayBuffer dst, boolean endOfStream) 155 throws CharacterCodingException; 156 157 /** 158 * Attempts to transfer a complete line of characters up to a line delimiter 159 * from this buffer to a newly created string. If a complete line is 160 * available in the buffer, the sequence of chars is transferred to a newly 161 * created string. The line delimiter itself is discarded. If a complete 162 * line is not available in the buffer, this method returns 163 * {@code null}. If {@code endOfStream} parameter 164 * is set to {@code true} this method assumes the end of stream has 165 * been reached and the content currently stored in the buffer should be 166 * treated as a complete line. 167 * <p> 168 * The choice of a char encoding and line delimiter sequence is up to the 169 * specific implementations of this interface. 170 * 171 * @param endOfStream end of stream flag 172 * @return a string representing a complete line, if available. 173 * {@code null} otherwise. 174 * 175 * @throws CharacterCodingException in case a character encoding or decoding 176 * error occurs. 177 */ 178 String readLine(boolean endOfStream) 179 throws CharacterCodingException; 180 181}