Mercurial Hosting > luan
annotate src/org/eclipse/jetty/io/Buffer.java @ 1047:1accf965d51a
remove other Buffer implementations
author | Franklin Schmidt <fschmidt@gmail.com> |
---|---|
date | Mon, 07 Nov 2016 22:51:09 -0700 |
parents | a8c92b0a08ed |
children |
rev | line source |
---|---|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
1 // |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
2 // ======================================================================== |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
3 // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
4 // ------------------------------------------------------------------------ |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
5 // All rights reserved. This program and the accompanying materials |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
6 // are made available under the terms of the Eclipse Public License v1.0 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
7 // and Apache License v2.0 which accompanies this distribution. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
8 // |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
9 // The Eclipse Public License is available at |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
10 // http://www.eclipse.org/legal/epl-v10.html |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
11 // |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
12 // The Apache License v2.0 is available at |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
13 // http://www.opensource.org/licenses/apache2.0.php |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
14 // |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
15 // You may elect to redistribute this code under either of these licenses. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
16 // ======================================================================== |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
17 // |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
18 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
19 package org.eclipse.jetty.io; |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
20 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
21 import java.io.IOException; |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
22 import java.io.InputStream; |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
23 import java.io.OutputStream; |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
24 import java.nio.charset.Charset; |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
25 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
26 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
27 /** |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
28 * Byte Buffer interface. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
29 * |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
30 * This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
31 * pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
32 * |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
33 * This buffer interface is designed to be similar, but not dependent on the java.nio buffers, which may |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
34 * be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
35 * their valid _content before the position and a flip is required to access that data. |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
36 * |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
37 * For this buffer it is always true that: |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
38 * markValue <= getIndex <= putIndex <= capacity |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
39 * |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
40 * |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
41 * @version 1.0 |
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
42 */ |
1039
a7319f14ba1e
remove Buffer.isImmutable()
Franklin Schmidt <fschmidt@gmail.com>
parents:
1038
diff
changeset
|
43 public interface Buffer |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
44 { |
1010 | 45 public final static int |
46 READONLY=1, // indexes may be changed, but not content | |
47 READWRITE=2; // anything can be changed | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
48 |
1010 | 49 /** |
50 * Get the underlying array, if one exists. | |
51 * @return a <code>byte[]</code> backing this buffer or null if none exists. | |
52 */ | |
53 byte[] array(); | |
54 | |
55 /** | |
56 * Get the underlying buffer. If this buffer wraps a backing buffer. | |
57 * @return The root backing buffer or this if there is no backing buffer; | |
58 */ | |
59 Buffer buffer(); | |
60 | |
61 /** | |
62 * | |
63 * The capacity of the buffer. This is the maximum putIndex that may be set. | |
64 * @return an <code>int</code> value | |
65 */ | |
66 int capacity(); | |
67 | |
68 /** | |
69 * the space remaining in the buffer. | |
70 * @return capacity - putIndex | |
71 */ | |
72 int space(); | |
73 | |
74 /** | |
75 * Clear the buffer. getIndex=0, putIndex=0. | |
76 */ | |
77 void clear(); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
78 |
1010 | 79 /** |
80 * Compact the buffer by discarding bytes before the postion (or mark if set). | |
81 * Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of | |
82 * the buffer and the values adjusted accordingly. | |
83 */ | |
84 void compact(); | |
85 | |
86 /** | |
87 * Get the byte at the current getIndex and increment it. | |
88 * @return The <code>byte</code> value from the current getIndex. | |
89 */ | |
90 byte get(); | |
91 | |
92 /** | |
93 * Get bytes from the current postion and put them into the passed byte array. | |
94 * The getIndex is incremented by the number of bytes copied into the array. | |
95 * @param b The byte array to fill. | |
96 * @param offset Offset in the array. | |
97 * @param length The max number of bytes to read. | |
98 * @return The number of bytes actually read. | |
99 */ | |
100 int get(byte[] b, int offset, int length); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
101 |
1010 | 102 /** |
103 * | |
104 * @param length an <code>int</code> value | |
105 * @return a <code>Buffer</code> value | |
106 */ | |
107 Buffer get(int length); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
108 |
1010 | 109 /** |
110 * The index within the buffer that will next be read or written. | |
111 * @return an <code>int</code> value >=0 <= putIndex() | |
112 */ | |
113 int getIndex(); | |
114 | |
115 /** | |
116 * @return true of putIndex > getIndex | |
117 */ | |
1037
3c4c7cc7904f
rename Buffer.hasContent() to hasRemaining()
Franklin Schmidt <fschmidt@gmail.com>
parents:
1032
diff
changeset
|
118 boolean hasRemaining(); |
1010 | 119 |
120 /** | |
121 * | |
122 * @return a <code>boolean</code> value true if the buffer is readonly. The buffer indexes may | |
123 * be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be | |
124 * read only. | |
125 */ | |
126 boolean isReadOnly(); | |
127 | |
128 /** | |
129 * The number of bytes from the getIndex to the putIndex | |
130 * @return an <code>int</code> == putIndex()-getIndex() | |
131 */ | |
1038
b71ad168fe34
rename Buffer.length() to remaining()
Franklin Schmidt <fschmidt@gmail.com>
parents:
1037
diff
changeset
|
132 int remaining(); |
1010 | 133 |
134 /** | |
135 * Get the byte at the current getIndex without incrementing the getIndex. | |
136 * @return The <code>byte</code> value from the current getIndex. | |
137 */ | |
138 byte peek(); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
139 |
1010 | 140 /** |
141 * Get the byte at a specific index in the buffer. | |
142 * @param index an <code>int</code> value | |
143 * @return a <code>byte</code> value | |
144 */ | |
145 byte peek(int index); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
146 |
1032 | 147 String toString(int index, int length); |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
148 |
1010 | 149 /** |
150 * | |
151 * @param index an <code>int</code> value | |
152 * @param b The byte array to peek into | |
153 * @param offset The offset into the array to start peeking | |
154 * @param length an <code>int</code> value | |
155 * @return The number of bytes actually peeked | |
156 */ | |
157 int peek(int index, byte[] b, int offset, int length); | |
158 | |
159 /** | |
160 * Put the contents of the buffer at the specific index. | |
161 * @param index an <code>int</code> value | |
162 * @param src a <code>Buffer</code>. If the source buffer is not modified | |
163 | |
164 * @return The number of bytes actually poked | |
165 */ | |
166 int poke(int index, Buffer src); | |
167 | |
168 /** | |
169 * Put a specific byte to a specific getIndex. | |
170 * @param index an <code>int</code> value | |
171 * @param b a <code>byte</code> value | |
172 */ | |
173 void poke(int index, byte b); | |
174 | |
175 /** | |
176 * Put a specific byte to a specific getIndex. | |
177 * @param index an <code>int</code> value | |
178 * @param b a <code>byte array</code> value | |
179 * @return The number of bytes actually poked | |
180 */ | |
181 int poke(int index, byte b[], int offset, int length); | |
182 | |
183 /** | |
184 * Write the bytes from the source buffer to the current getIndex. | |
185 * @param src The source <code>Buffer</code> it is not modified. | |
186 * @return The number of bytes actually poked | |
187 */ | |
188 int put(Buffer src); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
189 |
1010 | 190 /** |
191 * Put a byte to the current getIndex and increment the getIndex. | |
192 * @param b a <code>byte</code> value | |
193 */ | |
194 void put(byte b); | |
195 | |
196 /** | |
197 * Put a byte to the current getIndex and increment the getIndex. | |
198 * @param b a <code>byte</code> value | |
199 * @return The number of bytes actually poked | |
200 */ | |
201 int put(byte[] b,int offset, int length); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
202 |
1010 | 203 /** |
204 * Put a byte to the current getIndex and increment the getIndex. | |
205 * @param b a <code>byte</code> value | |
206 * @return The number of bytes actually poked | |
207 */ | |
208 int put(byte[] b); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
209 |
1010 | 210 /** |
211 * The index of the first element that should not be read. | |
212 * @return an <code>int</code> value >= getIndex() | |
213 */ | |
214 int putIndex(); | |
215 | |
216 /** | |
217 * Set the buffers start getIndex. | |
218 * @param newStart an <code>int</code> value | |
219 */ | |
220 void setGetIndex(int newStart); | |
221 | |
222 /** | |
223 * | |
224 * @param newLimit an <code>int</code> value | |
225 */ | |
226 void setPutIndex(int newLimit); | |
227 | |
228 /** | |
229 * Skip _content. The getIndex is updated by min(remaining(), n) | |
230 * @param n The number of bytes to skip | |
231 * @return the number of bytes skipped. | |
232 */ | |
233 int skip(int n); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
234 |
1010 | 235 /** |
236 * | |
237 * @return a volitile <code>Buffer</code> from the postion to the putIndex. | |
238 */ | |
239 Buffer slice(); | |
240 | |
1044
dd71a59fcf72
remove buffer marking
Franklin Schmidt <fschmidt@gmail.com>
parents:
1043
diff
changeset
|
241 public Buffer sliceFrom(int index); |
dd71a59fcf72
remove buffer marking
Franklin Schmidt <fschmidt@gmail.com>
parents:
1043
diff
changeset
|
242 |
1010 | 243 /** |
244 * | |
245 * @return a <code>String</code> value describing the state and contents of the buffer. | |
246 */ | |
247 String toDetailString(); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
248 |
1010 | 249 /* ------------------------------------------------------------ */ |
250 /** Read the buffer's contents from the input stream | |
251 * @param in input stream | |
252 * @param max maximum number of bytes that may be read | |
253 * @return actual number of bytes read or -1 for EOF | |
254 */ | |
255 int readFrom(InputStream in, int max) throws IOException; | |
256 | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
257 |
1010 | 258 String toString(String charset); |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
259 |
1041
35e3c864d7a7
make View package local
Franklin Schmidt <fschmidt@gmail.com>
parents:
1040
diff
changeset
|
260 |
35e3c864d7a7
make View package local
Franklin Schmidt <fschmidt@gmail.com>
parents:
1040
diff
changeset
|
261 // like ByteBuffer |
35e3c864d7a7
make View package local
Franklin Schmidt <fschmidt@gmail.com>
parents:
1040
diff
changeset
|
262 Buffer duplicate(); |
1046 | 263 |
264 public byte[] asArray(); | |
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
265 } |