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