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