001: // ========================================================================
002: // Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
003: // ------------------------------------------------------------------------
004: // Licensed under the Apache License, Version 2.0 (the "License");
005: // you may not use this file except in compliance with the License.
006: // You may obtain a copy of the License at
007: // http://www.apache.org/licenses/LICENSE-2.0
008: // Unless required by applicable law or agreed to in writing, software
009: // distributed under the License is distributed on an "AS IS" BASIS,
010: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011: // See the License for the specific language governing permissions and
012: // limitations under the License.
013: // ========================================================================
014:
015: package org.mortbay.io;
016:
017: import java.io.IOException;
018: import java.io.InputStream;
019: import java.io.OutputStream;
020:
021: /**
022: * Byte Buffer interface.
023: *
024: * This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different
025: * pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex.
026: *
027: * This buffer interface is designed to be similar, but not dependant on the java.nio buffers, which may
028: * be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have
029: * their valid _content before the position and a flip is required to access that data.
030: *
031: * For this buffer it is always true that:
032: * markValue <= getIndex <= putIndex <= capacity
033: * @author gregw
034: *
035: * @version 1.0
036: */
037: public interface Buffer extends Cloneable {
038: public final static int IMMUTABLE = 0, // neither indexes or contexts can be changed
039: READONLY = 1, // indexes may be changed, but not content
040: READWRITE = 2; // anything can be changed
041: public final boolean VOLATILE = true; // The buffer may change outside of current scope.
042: public final boolean NON_VOLATILE = false;
043:
044: /**
045: * Get the underlying array, if one exists.
046: * @return a <code>byte[]</code> backing this buffer or null if none exists.
047: */
048: byte[] array();
049:
050: /**
051: *
052: * @return a <code>byte[]</code> value of the bytes from the getIndex to the putIndex.
053: */
054: byte[] asArray();
055:
056: /**
057: * Get the unerlying buffer. If this buffer wraps a backing buffer.
058: * @return The root backing buffer or this if there is no backing buffer;
059: */
060: Buffer buffer();
061:
062: /**
063: *
064: * @return a non volitile version of this <code>Buffer</code> value
065: */
066: Buffer asNonVolatileBuffer();
067:
068: /**
069: *
070: * @return a readonly version of this <code>Buffer</code>.
071: */
072: Buffer asReadOnlyBuffer();
073:
074: /**
075: *
076: * @return an immutable version of this <code>Buffer</code>.
077: */
078: Buffer asImmutableBuffer();
079:
080: /**
081: *
082: * @return an immutable version of this <code>Buffer</code>.
083: */
084: Buffer asMutableBuffer();
085:
086: /**
087: *
088: * The capacity of the buffer. This is the maximum putIndex that may be set.
089: * @return an <code>int</code> value
090: */
091: int capacity();
092:
093: /**
094: * the space remaining in the buffer.
095: * @return capacity - putIndex
096: */
097: int space();
098:
099: /**
100: * Clear the buffer. getIndex=0, putIndex=0.
101: */
102: void clear();
103:
104: /**
105: * Compact the buffer by discarding bytes before the postion (or mark if set).
106: * Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of
107: * the buffer and the values adjusted accordingly.
108: */
109: void compact();
110:
111: /**
112: * Get the byte at the current getIndex and increment it.
113: * @return The <code>byte</code> value from the current getIndex.
114: */
115: byte get();
116:
117: /**
118: * Get bytes from the current postion and put them into the passed byte array.
119: * The getIndex is incremented by the number of bytes copied into the array.
120: * @param b The byte array to fill.
121: * @param offset Offset in the array.
122: * @param length The max number of bytes to read.
123: * @return The number of bytes actually read.
124: */
125: int get(byte[] b, int offset, int length);
126:
127: /**
128: *
129: * @param length an <code>int</code> value
130: * @return a <code>Buffer</code> value
131: */
132: Buffer get(int length);
133:
134: /**
135: * The index within the buffer that will next be read or written.
136: * @return an <code>int</code> value >=0 <= putIndex()
137: */
138: int getIndex();
139:
140: /**
141: * @return true of putIndex > getIndex
142: */
143: boolean hasContent();
144:
145: /**
146: *
147: * @return a <code>boolean</code> value true if case sensitive comparison on this buffer
148: */
149: boolean equalsIgnoreCase(Buffer buffer);
150:
151: /**
152: *
153: * @return a <code>boolean</code> value true if the buffer is immutable and that neither
154: * the buffer contents nor the indexes may be changed.
155: */
156: boolean isImmutable();
157:
158: /**
159: *
160: * @return a <code>boolean</code> value true if the buffer is readonly. The buffer indexes may
161: * be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be
162: * read only.
163: */
164: boolean isReadOnly();
165:
166: /**
167: *
168: * @return a <code>boolean</code> value true if the buffer contents may change
169: * via alternate paths than this buffer. If the contents of this buffer are to be used outside of the
170: * current context, then a copy must be made.
171: */
172: boolean isVolatile();
173:
174: /**
175: * The number of bytes from the getIndex to the putIndex
176: * @return an <code>int</code> == putIndex()-getIndex()
177: */
178: int length();
179:
180: /**
181: * Set the mark to the current getIndex.
182: */
183: void mark();
184:
185: /**
186: * Set the mark relative to the current getIndex
187: * @param offset an <code>int</code> value to add to the current getIndex to obtain the mark value.
188: */
189: void mark(int offset);
190:
191: /**
192: * The current index of the mark.
193: * @return an <code>int</code> index in the buffer or -1 if the mark is not set.
194: */
195: int markIndex();
196:
197: /**
198: * Get the byte at the current getIndex without incrementing the getIndex.
199: * @return The <code>byte</code> value from the current getIndex.
200: */
201: byte peek();
202:
203: /**
204: * Get the byte at a specific index in the buffer.
205: * @param index an <code>int</code> value
206: * @return a <code>byte</code> value
207: */
208: byte peek(int index);
209:
210: /**
211: *
212: * @param index an <code>int</code> value
213: * @param length an <code>int</code> value
214: * @return The <code>Buffer</code> value from the requested getIndex.
215: */
216: Buffer peek(int index, int length);
217:
218: /**
219: *
220: * @param index an <code>int</code> value
221: * @param b The byte array to peek into
222: * @param offset The offset into the array to start peeking
223: * @param length an <code>int</code> value
224: * @return The number of bytes actually peeked
225: */
226: int peek(int index, byte[] b, int offset, int length);
227:
228: /**
229: * Put the contents of the buffer at the specific index.
230: * @param index an <code>int</code> value
231: * @param src a <code>Buffer</code>. If the source buffer is not modified
232:
233: * @return The number of bytes actually poked
234: */
235: int poke(int index, Buffer src);
236:
237: /**
238: * Put a specific byte to a specific getIndex.
239: * @param index an <code>int</code> value
240: * @param b a <code>byte</code> value
241: */
242: void poke(int index, byte b);
243:
244: /**
245: * Put a specific byte to a specific getIndex.
246: * @param index an <code>int</code> value
247: * @param b a <code>byte array</code> value
248: * @return The number of bytes actually poked
249: */
250: int poke(int index, byte b[], int offset, int length);
251:
252: /**
253: * Write the bytes from the source buffer to the current getIndex.
254: * @param src The source <code>Buffer</code> it is not modified.
255: * @return The number of bytes actually poked
256: */
257: int put(Buffer src);
258:
259: /**
260: * Put a byte to the current getIndex and increment the getIndex.
261: * @param b a <code>byte</code> value
262: */
263: void put(byte b);
264:
265: /**
266: * Put a byte to the current getIndex and increment the getIndex.
267: * @param b a <code>byte</code> value
268: * @return The number of bytes actually poked
269: */
270: int put(byte[] b, int offset, int length);
271:
272: /**
273: * Put a byte to the current getIndex and increment the getIndex.
274: * @param b a <code>byte</code> value
275: * @return The number of bytes actually poked
276: */
277: int put(byte[] b);
278:
279: /**
280: * The index of the first element that should not be read.
281: * @return an <code>int</code> value >= getIndex()
282: */
283: int putIndex();
284:
285: /**
286: * Reset the current getIndex to the mark
287: */
288: void reset();
289:
290: /**
291: * Set the buffers start getIndex.
292: * @param newStart an <code>int</code> value
293: */
294: void setGetIndex(int newStart);
295:
296: /**
297: * Set a specific value for the mark.
298: * @param newMark an <code>int</code> value
299: */
300: void setMarkIndex(int newMark);
301:
302: /**
303: *
304: * @param newLimit an <code>int</code> value
305: */
306: void setPutIndex(int newLimit);
307:
308: /**
309: * Skip _content. The getIndex is updated by min(remaining(), n)
310: * @param n The number of bytes to skip
311: * @return the number of bytes skipped.
312: */
313: int skip(int n);
314:
315: /**
316: *
317: * @return a volitile <code>Buffer</code> from the postion to the putIndex.
318: */
319: Buffer slice();
320:
321: /**
322: *
323: *
324: * @return a volitile <code>Buffer</code> value from the mark to the putIndex
325: */
326: Buffer sliceFromMark();
327:
328: /**
329: *
330: *
331: * @param length an <code>int</code> value
332: * @return a valitile <code>Buffer</code> value from the mark of the length requested.
333: */
334: Buffer sliceFromMark(int length);
335:
336: /**
337: *
338: * @return a <code>String</code> value describing the state and contents of the buffer.
339: */
340: String toDetailString();
341:
342: /* ------------------------------------------------------------ */
343: /** Write the buffer's contents to the output stream
344: * @param out
345: */
346: void writeTo(OutputStream out) throws IOException;
347:
348: /* ------------------------------------------------------------ */
349: /** Read the buffer's contents from the input stream
350: * @param in input stream
351: * @param max maximum number of bytes that may be read
352: * @return actual number of bytes read or -1 for EOF
353: */
354: int readFrom(InputStream in, int max) throws IOException;
355:
356: /*
357: * Buffers implementing this interface should be compared with case insensitive equals
358: *
359: */
360: public interface CaseInsensitve {
361: }
362:
363: }
|