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