1 // 2 // ======================================================================== 3 // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd. 4 // ------------------------------------------------------------------------ 5 // All rights reserved. This program and the accompanying materials 6 // are made available under the terms of the Eclipse Public License v1.0 7 // and Apache License v2.0 which accompanies this distribution. 8 // 9 // The Eclipse Public License is available at 10 // http://www.eclipse.org/legal/epl-v10.html 11 // 12 // The Apache License v2.0 is available at 13 // http://www.opensource.org/licenses/apache2.0.php 14 // 15 // You may elect to redistribute this code under either of these licenses. 16 // ======================================================================== 17 // 18 19 package org.eclipse.jetty.io; 20 21 import java.io.IOException; 22 import java.io.InputStream; 23 import java.io.OutputStream; 24 import java.nio.charset.Charset; 25 26 27 /** 28 * Byte Buffer interface. 29 * 30 * This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different 31 * pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex. 32 * 33 * This buffer interface is designed to be similar, but not dependent on the java.nio buffers, which may 34 * be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have 35 * their valid _content before the position and a flip is required to access that data. 36 * 37 * For this buffer it is always true that: 38 * markValue <= getIndex <= putIndex <= capacity 39 * 40 * 41 * @version 1.0 42 */ 43 public interface Buffer extends Cloneable 44 { 45 public final static int 46 IMMUTABLE=0, // neither indexes or contexts can be changed 47 READONLY=1, // indexes may be changed, but not content 48 READWRITE=2; // anything can be changed 49 public final boolean VOLATILE=true; // The buffer may change outside of current scope. 50 public final boolean NON_VOLATILE=false; 51 52 /** 53 * Get the underlying array, if one exists. 54 * @return a <code>byte[]</code> backing this buffer or null if none exists. 55 */ array()56 byte[] array(); 57 58 /** 59 * 60 * @return a <code>byte[]</code> value of the bytes from the getIndex to the putIndex. 61 */ asArray()62 byte[] asArray(); 63 64 /** 65 * Get the underlying buffer. If this buffer wraps a backing buffer. 66 * @return The root backing buffer or this if there is no backing buffer; 67 */ buffer()68 Buffer buffer(); 69 70 /** 71 * 72 * @return a non volatile version of this <code>Buffer</code> value 73 */ asNonVolatileBuffer()74 Buffer asNonVolatileBuffer(); 75 76 /** 77 * 78 * @return a readonly version of this <code>Buffer</code>. 79 */ asReadOnlyBuffer()80 Buffer asReadOnlyBuffer(); 81 82 /** 83 * 84 * @return an immutable version of this <code>Buffer</code>. 85 */ asImmutableBuffer()86 Buffer asImmutableBuffer(); 87 88 /** 89 * 90 * @return an immutable version of this <code>Buffer</code>. 91 */ asMutableBuffer()92 Buffer asMutableBuffer(); 93 94 /** 95 * 96 * The capacity of the buffer. This is the maximum putIndex that may be set. 97 * @return an <code>int</code> value 98 */ capacity()99 int capacity(); 100 101 /** 102 * the space remaining in the buffer. 103 * @return capacity - putIndex 104 */ space()105 int space(); 106 107 /** 108 * Clear the buffer. getIndex=0, putIndex=0. 109 */ clear()110 void clear(); 111 112 /** 113 * Compact the buffer by discarding bytes before the postion (or mark if set). 114 * Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of 115 * the buffer and the values adjusted accordingly. 116 */ compact()117 void compact(); 118 119 /** 120 * Get the byte at the current getIndex and increment it. 121 * @return The <code>byte</code> value from the current getIndex. 122 */ get()123 byte get(); 124 125 /** 126 * Get bytes from the current postion and put them into the passed byte array. 127 * The getIndex is incremented by the number of bytes copied into the array. 128 * @param b The byte array to fill. 129 * @param offset Offset in the array. 130 * @param length The max number of bytes to read. 131 * @return The number of bytes actually read. 132 */ get(byte[] b, int offset, int length)133 int get(byte[] b, int offset, int length); 134 135 /** 136 * 137 * @param length an <code>int</code> value 138 * @return a <code>Buffer</code> value 139 */ get(int length)140 Buffer get(int length); 141 142 /** 143 * The index within the buffer that will next be read or written. 144 * @return an <code>int</code> value >=0 <= putIndex() 145 */ getIndex()146 int getIndex(); 147 148 /** 149 * @return true of putIndex > getIndex 150 */ hasContent()151 boolean hasContent(); 152 153 /** 154 * 155 * @return a <code>boolean</code> value true if case sensitive comparison on this buffer 156 */ equalsIgnoreCase(Buffer buffer)157 boolean equalsIgnoreCase(Buffer buffer); 158 159 160 /** 161 * 162 * @return a <code>boolean</code> value true if the buffer is immutable and that neither 163 * the buffer contents nor the indexes may be changed. 164 */ isImmutable()165 boolean isImmutable(); 166 167 /** 168 * 169 * @return a <code>boolean</code> value true if the buffer is readonly. The buffer indexes may 170 * be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be 171 * read only. 172 */ isReadOnly()173 boolean isReadOnly(); 174 175 /** 176 * 177 * @return a <code>boolean</code> value true if the buffer contents may change 178 * via alternate paths than this buffer. If the contents of this buffer are to be used outside of the 179 * current context, then a copy must be made. 180 */ isVolatile()181 boolean isVolatile(); 182 183 /** 184 * The number of bytes from the getIndex to the putIndex 185 * @return an <code>int</code> == putIndex()-getIndex() 186 */ length()187 int length(); 188 189 /** 190 * Set the mark to the current getIndex. 191 */ mark()192 void mark(); 193 194 /** 195 * Set the mark relative to the current getIndex 196 * @param offset an <code>int</code> value to add to the current getIndex to obtain the mark value. 197 */ mark(int offset)198 void mark(int offset); 199 200 /** 201 * The current index of the mark. 202 * @return an <code>int</code> index in the buffer or -1 if the mark is not set. 203 */ markIndex()204 int markIndex(); 205 206 /** 207 * Get the byte at the current getIndex without incrementing the getIndex. 208 * @return The <code>byte</code> value from the current getIndex. 209 */ peek()210 byte peek(); 211 212 /** 213 * Get the byte at a specific index in the buffer. 214 * @param index an <code>int</code> value 215 * @return a <code>byte</code> value 216 */ peek(int index)217 byte peek(int index); 218 219 /** 220 * 221 * @param index an <code>int</code> value 222 * @param length an <code>int</code> value 223 * @return The <code>Buffer</code> value from the requested getIndex. 224 */ peek(int index, int length)225 Buffer peek(int index, int length); 226 227 /** 228 * 229 * @param index an <code>int</code> value 230 * @param b The byte array to peek into 231 * @param offset The offset into the array to start peeking 232 * @param length an <code>int</code> value 233 * @return The number of bytes actually peeked 234 */ peek(int index, byte[] b, int offset, int length)235 int peek(int index, byte[] b, int offset, int length); 236 237 /** 238 * Put the contents of the buffer at the specific index. 239 * @param index an <code>int</code> value 240 * @param src a <code>Buffer</code>. If the source buffer is not modified 241 242 * @return The number of bytes actually poked 243 */ poke(int index, Buffer src)244 int poke(int index, Buffer src); 245 246 /** 247 * Put a specific byte to a specific getIndex. 248 * @param index an <code>int</code> value 249 * @param b a <code>byte</code> value 250 */ poke(int index, byte b)251 void poke(int index, byte b); 252 253 /** 254 * Put a specific byte to a specific getIndex. 255 * @param index an <code>int</code> value 256 * @param b a <code>byte array</code> value 257 * @return The number of bytes actually poked 258 */ poke(int index, byte b[], int offset, int length)259 int poke(int index, byte b[], int offset, int length); 260 261 /** 262 * Write the bytes from the source buffer to the current getIndex. 263 * @param src The source <code>Buffer</code> it is not modified. 264 * @return The number of bytes actually poked 265 */ put(Buffer src)266 int put(Buffer src); 267 268 /** 269 * Put a byte to the current getIndex and increment the getIndex. 270 * @param b a <code>byte</code> value 271 */ put(byte b)272 void put(byte b); 273 274 /** 275 * Put a byte to the current getIndex and increment the getIndex. 276 * @param b a <code>byte</code> value 277 * @return The number of bytes actually poked 278 */ put(byte[] b,int offset, int length)279 int put(byte[] b,int offset, int length); 280 281 /** 282 * Put a byte to the current getIndex and increment the getIndex. 283 * @param b a <code>byte</code> value 284 * @return The number of bytes actually poked 285 */ put(byte[] b)286 int put(byte[] b); 287 288 /** 289 * The index of the first element that should not be read. 290 * @return an <code>int</code> value >= getIndex() 291 */ putIndex()292 int putIndex(); 293 294 /** 295 * Reset the current getIndex to the mark 296 */ reset()297 void reset(); 298 299 /** 300 * Set the buffers start getIndex. 301 * @param newStart an <code>int</code> value 302 */ setGetIndex(int newStart)303 void setGetIndex(int newStart); 304 305 /** 306 * Set a specific value for the mark. 307 * @param newMark an <code>int</code> value 308 */ setMarkIndex(int newMark)309 void setMarkIndex(int newMark); 310 311 /** 312 * 313 * @param newLimit an <code>int</code> value 314 */ setPutIndex(int newLimit)315 void setPutIndex(int newLimit); 316 317 /** 318 * Skip _content. The getIndex is updated by min(remaining(), n) 319 * @param n The number of bytes to skip 320 * @return the number of bytes skipped. 321 */ skip(int n)322 int skip(int n); 323 324 /** 325 * 326 * @return a volitile <code>Buffer</code> from the postion to the putIndex. 327 */ slice()328 Buffer slice(); 329 330 /** 331 * 332 * 333 * @return a volitile <code>Buffer</code> value from the mark to the putIndex 334 */ sliceFromMark()335 Buffer sliceFromMark(); 336 337 /** 338 * 339 * 340 * @param length an <code>int</code> value 341 * @return a valitile <code>Buffer</code> value from the mark of the length requested. 342 */ sliceFromMark(int length)343 Buffer sliceFromMark(int length); 344 345 /** 346 * 347 * @return a <code>String</code> value describing the state and contents of the buffer. 348 */ toDetailString()349 String toDetailString(); 350 351 /* ------------------------------------------------------------ */ 352 /** Write the buffer's contents to the output stream 353 * @param out 354 */ writeTo(OutputStream out)355 void writeTo(OutputStream out) throws IOException; 356 357 /* ------------------------------------------------------------ */ 358 /** Read the buffer's contents from the input stream 359 * @param in input stream 360 * @param max maximum number of bytes that may be read 361 * @return actual number of bytes read or -1 for EOF 362 */ readFrom(InputStream in, int max)363 int readFrom(InputStream in, int max) throws IOException; 364 365 366 /* ------------------------------------------------------------ */ toString(String charset)367 String toString(String charset); 368 369 /* ------------------------------------------------------------ */ toString(Charset charset)370 String toString(Charset charset); 371 372 /* 373 * Buffers implementing this interface should be compared with case insensitive equals 374 * 375 */ 376 public interface CaseInsensitve 377 {} 378 379 380 } 381