1 |
/* DataOutput.java -- Interface for writing data from a stream |
/* DataOutput.java -- Interface for writing data from a stream |
2 |
Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. |
Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
45 |
|
|
46 |
/** |
/** |
47 |
* This interface is implemented by classes that can wrte data to streams |
* This interface is implemented by classes that can wrte data to streams |
48 |
* from Java primitive types. |
* from Java primitive types. This data can subsequently be read back |
49 |
|
* by classes implementing the <code>DataInput</code> interface. |
50 |
* |
* |
51 |
* @author Aaron M. Renn (arenn@urbanophile.com) |
* @author Aaron M. Renn (arenn@urbanophile.com) |
52 |
* @author Tom Tromey <tromey@cygnus.com> |
* @author Tom Tromey <tromey@cygnus.com> |
53 |
|
* |
54 |
|
* @see DataInput |
55 |
*/ |
*/ |
56 |
public interface DataOutput |
public interface DataOutput |
57 |
{ |
{ |
|
|
|
58 |
/** |
/** |
59 |
* This method writes a Java boolean value to an output stream |
* This method writes a Java boolean value to an output stream. If |
60 |
|
* <code>value</code> is <code>true</code>, a byte with the value of |
61 |
|
* 1 will be written, otherwise a byte with the value of 0 will be |
62 |
|
* written. |
63 |
|
* |
64 |
|
* The value written can be read using the <code>readBoolean</code> |
65 |
|
* method in <code>DataInput</code>. |
66 |
* |
* |
67 |
* @param value The boolean value to write |
* @param value The boolean value to write |
68 |
* |
* |
69 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
70 |
|
* |
71 |
|
* @see DataInput#readBoolean |
72 |
*/ |
*/ |
73 |
void writeBoolean(boolean value) throws IOException; |
void writeBoolean(boolean value) throws IOException; |
74 |
|
|
75 |
/** |
/** |
76 |
* This method writes a Java byte value to an output stream |
* This method writes a Java byte value to an output stream. The |
77 |
|
* byte to be written will be in the lowest 8 bits of the |
78 |
|
* <code>int</code> value passed. |
79 |
|
* |
80 |
|
* The value written can be read using the <code>readByte</code> or |
81 |
|
* <code>readUnsignedByte</code> methods in <code>DataInput</code>. |
82 |
* |
* |
83 |
* @param value The int value to write |
* @param value The int value to write |
84 |
* |
* |
85 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
86 |
|
* |
87 |
|
* @see DataInput#readByte |
88 |
|
* @see DataInput#readUnsignedByte |
89 |
*/ |
*/ |
90 |
void writeByte(int value) throws IOException; |
void writeByte(int value) throws IOException; |
91 |
|
|
92 |
/** |
/** |
93 |
* This method writes a Java char value to an output stream |
* This method writes a Java char value to an output stream. The |
94 |
|
* char to be written will be in the lowest 16 bits of the <code>int</code> |
95 |
|
* value passed. These bytes will be written "big endian". That is, |
96 |
|
* with the high byte written first in the following manner: |
97 |
|
* <p> |
98 |
|
* <code>byte0 = (byte)((value & 0xFF00) >> 8);<br> |
99 |
|
* byte1 = (byte)(value & 0x00FF);</code> |
100 |
|
* <p> |
101 |
|
* |
102 |
|
* The value written can be read using the <code>readChar</code> |
103 |
|
* method in <code>DataInput</code>. |
104 |
* |
* |
105 |
* @param value The char value to write |
* @param value The char value to write |
106 |
* |
* |
107 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
108 |
|
* |
109 |
|
* @see DataInput#readChar |
110 |
*/ |
*/ |
111 |
void writeChar(int value) throws IOException; |
void writeChar(int value) throws IOException; |
112 |
|
|
113 |
/** |
/** |
114 |
* This method writes a Java int value to an output stream as a 16 bit value |
* This method writes a Java char value to an output stream. The |
115 |
|
* char to be written will be in the lowest 16 bits of the <code>int</code> |
116 |
|
* value passed. These bytes will be written "big endian". That is, |
117 |
|
* with the high byte written first in the following manner: |
118 |
|
* <p> |
119 |
|
* <code>byte0 = (byte)((value & 0xFF00) >> 8);<br> |
120 |
|
* byte1 = (byte)(value & 0x00FF);</code> |
121 |
|
* <p> |
122 |
|
* |
123 |
|
* The value written can be read using the <code>readShort</code> and |
124 |
|
* <code>readUnsignedShort</code> methods in <code>DataInput</code>. |
125 |
* |
* |
126 |
* @param value The int value to write as a 16-bit value |
* @param value The int value to write as a 16-bit value |
127 |
* |
* |
128 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
129 |
|
* |
130 |
|
* @see DataInput#readShort |
131 |
|
* @see DataInput#readUnsignedShort |
132 |
*/ |
*/ |
133 |
void writeShort(int value) throws IOException; |
void writeShort(int value) throws IOException; |
134 |
|
|
135 |
/** |
/** |
136 |
* This method writes a Java int value to an output stream |
* This method writes a Java int value to an output stream. The 4 bytes |
137 |
|
* of the passed value will be written "big endian". That is, with |
138 |
|
* the high byte written first in the following manner: |
139 |
|
* <p> |
140 |
|
* <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br> |
141 |
|
* byte1 = (byte)((value & 0x00FF0000) >> 16);<br> |
142 |
|
* byte2 = (byte)((value & 0x0000FF00) >> 8);<br> |
143 |
|
* byte3 = (byte)(value & 0x000000FF);</code> |
144 |
|
* <p> |
145 |
|
* |
146 |
|
* The value written can be read using the <code>readInt</code> |
147 |
|
* method in <code>DataInput</code>. |
148 |
* |
* |
149 |
* @param value The int value to write |
* @param value The int value to write |
150 |
* |
* |
151 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
152 |
|
* |
153 |
|
* @see DataInput#readInt |
154 |
*/ |
*/ |
155 |
void writeInt(int value) throws IOException; |
void writeInt(int value) throws IOException; |
156 |
|
|
157 |
/** |
/** |
158 |
* This method writes a Java long value to an output stream |
* This method writes a Java long value to an output stream. The 8 bytes |
159 |
|
* of the passed value will be written "big endian". That is, with |
160 |
|
* the high byte written first in the following manner: |
161 |
|
* <p> |
162 |
|
* <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br> |
163 |
|
* byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br> |
164 |
|
* byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br> |
165 |
|
* byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br> |
166 |
|
* byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br> |
167 |
|
* byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br> |
168 |
|
* byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br> |
169 |
|
* byte7 = (byte)(value & 0x00000000000000FFL);</code> |
170 |
|
* <p> |
171 |
|
* |
172 |
|
* The value written can be read using the <code>readLong</code> |
173 |
|
* method in <code>DataInput</code>. |
174 |
* |
* |
175 |
* @param value The long value to write |
* @param value The long value to write |
176 |
* |
* |
177 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
178 |
|
* |
179 |
|
* @see DataInput#readLong |
180 |
*/ |
*/ |
181 |
void writeLong(long value) throws IOException; |
void writeLong(long value) throws IOException; |
182 |
|
|
183 |
/** |
/** |
184 |
* This method writes a Java float value to an output stream |
* This method writes a Java <code>float</code> value to the stream. This |
185 |
|
* value is written by first calling the method |
186 |
|
* <code>Float.floatToIntBits</code> |
187 |
|
* to retrieve an <code>int</code> representing the floating point number, |
188 |
|
* then writing this <code>int</code> value to the stream exactly the same |
189 |
|
* as the <code>writeInt()</code> method does. |
190 |
|
* |
191 |
|
* The value written can be read using the <code>readFloat</code> |
192 |
|
* method in <code>DataInput</code>. |
193 |
* |
* |
194 |
* @param value The float value to write |
* @param value The float value to write |
195 |
* |
* |
196 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
197 |
|
* |
198 |
|
* @see writeInt |
199 |
|
* @see DataInput#readFloat |
200 |
|
* @see Float#floatToIntBits |
201 |
*/ |
*/ |
202 |
void writeFloat(float value) throws IOException; |
void writeFloat(float value) throws IOException; |
203 |
|
|
204 |
/** |
/** |
205 |
* This method writes a Java double value to an output stream |
* This method writes a Java <code>double</code> value to the stream. This |
206 |
|
* value is written by first calling the method |
207 |
|
* <code>Double.doubleToLongBits</code> |
208 |
|
* to retrieve an <code>long</code> representing the floating point number, |
209 |
|
* then writing this <code>long</code> value to the stream exactly the same |
210 |
|
* as the <code>writeLong()</code> method does. |
211 |
|
* |
212 |
|
* The value written can be read using the <code>readDouble</code> |
213 |
|
* method in <code>DataInput</code>. |
214 |
* |
* |
215 |
* @param value The double value to write |
* @param value The double value to write |
216 |
* |
* |
217 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
218 |
|
* |
219 |
|
* @see writeLong |
220 |
|
* @see DataInput#readDouble |
221 |
|
* @see Double#doubleToLongBits |
222 |
*/ |
*/ |
223 |
void writeDouble(double value) throws IOException; |
void writeDouble(double value) throws IOException; |
224 |
|
|
225 |
/** |
/** |
226 |
* This method writes a String to an output stream as an array of bytes |
* This method writes all the bytes in a <code>String</code> out to the |
227 |
|
* stream. One byte is written for each character in the |
228 |
|
* <code>String</code>. |
229 |
|
* The high eight bits of each character are discarded, thus this |
230 |
|
* method is inappropriate for completely representing Unicode characters. |
231 |
* |
* |
232 |
* @param value The String to write |
* @param value The <code>String</code> to write |
233 |
* |
* |
234 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
235 |
*/ |
*/ |
236 |
void writeBytes(String value) throws IOException; |
void writeBytes(String value) throws IOException; |
237 |
|
|
238 |
/** |
/** |
239 |
* This method writes a String to an output stream as an array of char's |
* This method writes all the bytes of a <code>String</code> to an |
240 |
|
* output stream as an array of <code>char</code>'s. Each character |
241 |
|
* is written using the method specified in the <code>writeChar</code> |
242 |
|
* method. |
243 |
* |
* |
244 |
* @param value The String to write |
* @param value The String to write |
245 |
* |
* |
246 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
247 |
|
* |
248 |
|
* @see writeChar |
249 |
*/ |
*/ |
250 |
void writeChars(String value) throws IOException; |
void writeChars(String value) throws IOException; |
251 |
|
|
252 |
/** |
/** |
253 |
* This method writes a String to an output stream encoded in |
* This method writes a Java <code>String</code> to the stream in a modified |
254 |
* UTF-8 format. |
* UTF-8 format. First, two bytes are written to the stream indicating the |
255 |
|
* number of bytes to follow. This is written in the form of a Java |
256 |
|
* <code>short</code> value in the same manner used by the |
257 |
|
* <code>writeShort</code> method. Note that this is the number of |
258 |
|
* bytes in the |
259 |
|
* encoded <code>String</code> not the <code>String</code> length. Next |
260 |
|
* come the encoded characters. Each character in the <code>String</code> |
261 |
|
* is encoded as either one, two or three bytes. For characters in the |
262 |
|
* range of <code>\u0001</code> to <code>\u007F</code>, one byte is used. |
263 |
|
* The character |
264 |
|
* value goes into bits 0-7 and bit eight is 0. For characters in the range |
265 |
|
* of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used. Bits |
266 |
|
* 6-10 of the character value are encoded bits 0-4 of the first byte, with |
267 |
|
* the high bytes having a value of "110". Bits 0-5 of the character value |
268 |
|
* are stored in bits 0-5 of the second byte, with the high bits set to |
269 |
|
* "10". This type of encoding is also done for the null character |
270 |
|
* <code>\u0000</code>. This eliminates any C style NUL character values |
271 |
|
* in the output. All remaining characters are stored as three bytes. |
272 |
|
* Bits 12-15 of the character value are stored in bits 0-3 of the first |
273 |
|
* byte. The high bits of the first bytes are set to "1110". Bits 6-11 |
274 |
|
* of the character value are stored in bits 0-5 of the second byte. The |
275 |
|
* high bits of the second byte are set to "10". And bits 0-5 of the |
276 |
|
* character value are stored in bits 0-5 of byte three, with the high bits |
277 |
|
* of that byte set to "10". |
278 |
* |
* |
279 |
* @param value The String to write |
* The value written can be read using the <code>readUTF</code> |
280 |
|
* method in <code>DataInput</code>. |
281 |
|
* |
282 |
|
* @param value The <code>String</code> to write |
283 |
* |
* |
284 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
285 |
|
* |
286 |
|
* @see DataInput#readUTF |
287 |
*/ |
*/ |
288 |
void writeUTF(String value) throws IOException; |
void writeUTF(String value) throws IOException; |
289 |
|
|
290 |
/** |
/** |
291 |
* This method writes an 8-bit value (passed into the method as a Java |
* This method writes an 8-bit value (passed into the method as a Java |
292 |
* int) to an output stream. |
* <code>int</code>) to an output stream. The low 8 bits of the |
293 |
|
* passed value are written. |
294 |
* |
* |
295 |
* @param value The byte to write to the output stream |
* @param value The <code>byte</code> to write to the output stream |
296 |
* |
* |
297 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
298 |
*/ |
*/ |
311 |
* This method writes raw bytes from the passed array <code>buf</code> |
* This method writes raw bytes from the passed array <code>buf</code> |
312 |
* starting |
* starting |
313 |
* <code>offset</code> bytes into the buffer. The number of bytes |
* <code>offset</code> bytes into the buffer. The number of bytes |
314 |
* written will be * exactly <code>len</code>. |
* written will be exactly <code>len</code>. |
315 |
* |
* |
316 |
* @param buf The buffer from which to write the data |
* @param buf The buffer from which to write the data |
317 |
* @param offset The offset into the buffer to start writing data from |
* @param offset The offset into the buffer to start writing data from |