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