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