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