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 }