Mercurial Hosting > luan

comparison src/org/eclipse/jetty/io/Buffer.java @ 1010:2712133d5bce

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