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