1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.hc.core5.http.nio; 29 30 import java.io.IOException; 31 import java.nio.ByteBuffer; 32 import java.nio.channels.ReadableByteChannel; 33 import java.nio.channels.WritableByteChannel; 34 35 import org.apache.hc.core5.util.CharArrayBuffer; 36 37 /** 38 * Session input buffer for HTTP/1.1 non-blocking connections. 39 * <p> 40 * This interface facilitates intermediate buffering of input data streamed from 41 * a source channel and provides methods for reading lines of text. 42 * </p> 43 * 44 * @since 4.0 45 */ 46 public interface SessionInputBuffer { 47 48 /** 49 * Determines if the buffer contains data. 50 * 51 * @return {@code true} if there is data in the buffer, 52 * {@code false} otherwise. 53 */ 54 boolean hasData(); 55 56 /** 57 * Returns the length of this buffer. 58 * 59 * @return buffer length. 60 */ 61 int length(); 62 63 /** 64 * Makes an attempt to fill the buffer with data from the given 65 * {@link ReadableByteChannel}. 66 * 67 * @param src the source channel 68 * @return The number of bytes read, possibly zero, or {@code -1} if the 69 * channel has reached end-of-stream. 70 * @throws IOException in case of an I/O error. 71 */ 72 int fill(ReadableByteChannel src) throws IOException; 73 74 /** 75 * Reads one byte from the buffer. If the buffer is empty this method can 76 * throw a runtime exception. The exact type of runtime exception thrown 77 * by this method depends on implementation. 78 * 79 * @return one byte 80 */ 81 int read(); 82 83 /** 84 * Reads a sequence of bytes from this buffer into the destination buffer, 85 * up to the given maximum limit. The exact number of bytes transferred 86 * depends on availability of data in this buffer and capacity of the 87 * destination buffer, but cannot be more than {@code maxLen} value. 88 * 89 * @param dst the destination buffer. 90 * @param maxLen the maximum number of bytes to be read. 91 * @return The number of bytes read, possibly zero. 92 */ 93 int read(ByteBuffer dst, int maxLen); 94 95 /** 96 * Reads a sequence of bytes from this buffer into the destination buffer. 97 * The exact number of bytes transferred depends on availability of data 98 * in this buffer and capacity of the destination buffer. 99 * 100 * @param dst the destination buffer. 101 * @return The number of bytes read, possibly zero. 102 */ 103 int read(ByteBuffer dst); 104 105 /** 106 * Reads a sequence of bytes from this buffer into the destination channel, 107 * up to the given maximum limit. The exact number of bytes transferred 108 * depends on availability of data in this buffer, but cannot be more than 109 * {@code maxLen} value. 110 * 111 * @param dst the destination channel. 112 * @param maxLen the maximum number of bytes to be read. 113 * @return The number of bytes read, possibly zero. 114 * @throws IOException in case of an I/O error. 115 */ 116 int read(WritableByteChannel dst, int maxLen) throws IOException; 117 118 /** 119 * Reads a sequence of bytes from this buffer into the destination channel. 120 * The exact number of bytes transferred depends on availability of data in 121 * this buffer. 122 * 123 * @param dst the destination channel. 124 * @return The number of bytes read, possibly zero. 125 * @throws IOException in case of an I/O error. 126 */ 127 int read(WritableByteChannel dst) throws IOException; 128 129 /** 130 * Attempts to transfer a complete line of characters up to a line delimiter 131 * from this buffer to the destination buffer. If a complete line is 132 * available in the buffer, the sequence of chars is transferred to the 133 * destination buffer the method returns {@code true}. The line 134 * delimiter itself is discarded. If a complete line is not available in 135 * the buffer, this method returns {@code false} without transferring 136 * anything to the destination buffer. If {@code endOfStream} parameter 137 * is set to {@code true} this method assumes the end of stream has 138 * been reached and the content currently stored in the buffer should be 139 * treated as a complete line. 140 * <p> 141 * The choice of a char encoding and line delimiter sequence is up to the 142 * specific implementations of this interface. 143 * 144 * @param dst the destination buffer. 145 * @param endOfStream end of stream flag 146 * @return {@code true} if a sequence of chars representing a complete 147 * line has been transferred to the destination buffer, {@code false} 148 * otherwise. 149 * 150 * @throws java.nio.charset.CharacterCodingException in case a character encoding or decoding 151 * error occurs. 152 * @throws org.apache.hc.core5.http.MessageConstraintException in case a message constraint violation. 153 */ 154 boolean readLine(CharArrayBuffer dst, boolean endOfStream) throws IOException; 155 156 }