View Javadoc

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 }