001: /*
002: * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.io;
027:
028: /**
029: * The <code>DataOutput</code> interface provides
030: * for converting data from any of the Java
031: * primitive types to a series of bytes and
032: * writing these bytes to a binary stream.
033: * There is also a facility for converting
034: * a <code>String</code> into
035: * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
036: * format and writing the resulting series
037: * of bytes.
038: * <p>
039: * For all the methods in this interface that
040: * write bytes, it is generally true that if
041: * a byte cannot be written for any reason,
042: * an <code>IOException</code> is thrown.
043: *
044: * @author Frank Yellin
045: * @version 1.29, 05/05/07
046: * @see java.io.DataInput
047: * @see java.io.DataOutputStream
048: * @since JDK1.0
049: */
050: public interface DataOutput {
051: /**
052: * Writes to the output stream the eight
053: * low-order bits of the argument <code>b</code>.
054: * The 24 high-order bits of <code>b</code>
055: * are ignored.
056: *
057: * @param b the byte to be written.
058: * @throws IOException if an I/O error occurs.
059: */
060: void write(int b) throws IOException;
061:
062: /**
063: * Writes to the output stream all the bytes in array <code>b</code>.
064: * If <code>b</code> is <code>null</code>,
065: * a <code>NullPointerException</code> is thrown.
066: * If <code>b.length</code> is zero, then
067: * no bytes are written. Otherwise, the byte
068: * <code>b[0]</code> is written first, then
069: * <code>b[1]</code>, and so on; the last byte
070: * written is <code>b[b.length-1]</code>.
071: *
072: * @param b the data.
073: * @throws IOException if an I/O error occurs.
074: */
075: void write(byte b[]) throws IOException;
076:
077: /**
078: * Writes <code>len</code> bytes from array
079: * <code>b</code>, in order, to
080: * the output stream. If <code>b</code>
081: * is <code>null</code>, a <code>NullPointerException</code>
082: * is thrown. If <code>off</code> is negative,
083: * or <code>len</code> is negative, or <code>off+len</code>
084: * is greater than the length of the array
085: * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
086: * is thrown. If <code>len</code> is zero,
087: * then no bytes are written. Otherwise, the
088: * byte <code>b[off]</code> is written first,
089: * then <code>b[off+1]</code>, and so on; the
090: * last byte written is <code>b[off+len-1]</code>.
091: *
092: * @param b the data.
093: * @param off the start offset in the data.
094: * @param len the number of bytes to write.
095: * @throws IOException if an I/O error occurs.
096: */
097: void write(byte b[], int off, int len) throws IOException;
098:
099: /**
100: * Writes a <code>boolean</code> value to this output stream.
101: * If the argument <code>v</code>
102: * is <code>true</code>, the value <code>(byte)1</code>
103: * is written; if <code>v</code> is <code>false</code>,
104: * the value <code>(byte)0</code> is written.
105: * The byte written by this method may
106: * be read by the <code>readBoolean</code>
107: * method of interface <code>DataInput</code>,
108: * which will then return a <code>boolean</code>
109: * equal to <code>v</code>.
110: *
111: * @param v the boolean to be written.
112: * @throws IOException if an I/O error occurs.
113: */
114: void writeBoolean(boolean v) throws IOException;
115:
116: /**
117: * Writes to the output stream the eight low-
118: * order bits of the argument <code>v</code>.
119: * The 24 high-order bits of <code>v</code>
120: * are ignored. (This means that <code>writeByte</code>
121: * does exactly the same thing as <code>write</code>
122: * for an integer argument.) The byte written
123: * by this method may be read by the <code>readByte</code>
124: * method of interface <code>DataInput</code>,
125: * which will then return a <code>byte</code>
126: * equal to <code>(byte)v</code>.
127: *
128: * @param v the byte value to be written.
129: * @throws IOException if an I/O error occurs.
130: */
131: void writeByte(int v) throws IOException;
132:
133: /**
134: * Writes two bytes to the output
135: * stream to represent the value of the argument.
136: * The byte values to be written, in the order
137: * shown, are: <p>
138: * <pre><code>
139: * (byte)(0xff & (v >> 8))
140: * (byte)(0xff & v)
141: * </code> </pre> <p>
142: * The bytes written by this method may be
143: * read by the <code>readShort</code> method
144: * of interface <code>DataInput</code> , which
145: * will then return a <code>short</code> equal
146: * to <code>(short)v</code>.
147: *
148: * @param v the <code>short</code> value to be written.
149: * @throws IOException if an I/O error occurs.
150: */
151: void writeShort(int v) throws IOException;
152:
153: /**
154: * Writes a <code>char</code> value, which
155: * is comprised of two bytes, to the
156: * output stream.
157: * The byte values to be written, in the order
158: * shown, are:
159: * <p><pre><code>
160: * (byte)(0xff & (v >> 8))
161: * (byte)(0xff & v)
162: * </code></pre><p>
163: * The bytes written by this method may be
164: * read by the <code>readChar</code> method
165: * of interface <code>DataInput</code> , which
166: * will then return a <code>char</code> equal
167: * to <code>(char)v</code>.
168: *
169: * @param v the <code>char</code> value to be written.
170: * @throws IOException if an I/O error occurs.
171: */
172: void writeChar(int v) throws IOException;
173:
174: /**
175: * Writes an <code>int</code> value, which is
176: * comprised of four bytes, to the output stream.
177: * The byte values to be written, in the order
178: * shown, are:
179: * <p><pre><code>
180: * (byte)(0xff & (v >> 24))
181: * (byte)(0xff & (v >> 16))
182: * (byte)(0xff & (v >>    8))
183: * (byte)(0xff & v)
184: * </code></pre><p>
185: * The bytes written by this method may be read
186: * by the <code>readInt</code> method of interface
187: * <code>DataInput</code> , which will then
188: * return an <code>int</code> equal to <code>v</code>.
189: *
190: * @param v the <code>int</code> value to be written.
191: * @throws IOException if an I/O error occurs.
192: */
193: void writeInt(int v) throws IOException;
194:
195: /**
196: * Writes a <code>long</code> value, which is
197: * comprised of eight bytes, to the output stream.
198: * The byte values to be written, in the order
199: * shown, are:
200: * <p><pre><code>
201: * (byte)(0xff & (v >> 56))
202: * (byte)(0xff & (v >> 48))
203: * (byte)(0xff & (v >> 40))
204: * (byte)(0xff & (v >> 32))
205: * (byte)(0xff & (v >> 24))
206: * (byte)(0xff & (v >> 16))
207: * (byte)(0xff & (v >> 8))
208: * (byte)(0xff & v)
209: * </code></pre><p>
210: * The bytes written by this method may be
211: * read by the <code>readLong</code> method
212: * of interface <code>DataInput</code> , which
213: * will then return a <code>long</code> equal
214: * to <code>v</code>.
215: *
216: * @param v the <code>long</code> value to be written.
217: * @throws IOException if an I/O error occurs.
218: */
219: void writeLong(long v) throws IOException;
220:
221: /**
222: * Writes a <code>float</code> value,
223: * which is comprised of four bytes, to the output stream.
224: * It does this as if it first converts this
225: * <code>float</code> value to an <code>int</code>
226: * in exactly the manner of the <code>Float.floatToIntBits</code>
227: * method and then writes the <code>int</code>
228: * value in exactly the manner of the <code>writeInt</code>
229: * method. The bytes written by this method
230: * may be read by the <code>readFloat</code>
231: * method of interface <code>DataInput</code>,
232: * which will then return a <code>float</code>
233: * equal to <code>v</code>.
234: *
235: * @param v the <code>float</code> value to be written.
236: * @throws IOException if an I/O error occurs.
237: */
238: void writeFloat(float v) throws IOException;
239:
240: /**
241: * Writes a <code>double</code> value,
242: * which is comprised of eight bytes, to the output stream.
243: * It does this as if it first converts this
244: * <code>double</code> value to a <code>long</code>
245: * in exactly the manner of the <code>Double.doubleToLongBits</code>
246: * method and then writes the <code>long</code>
247: * value in exactly the manner of the <code>writeLong</code>
248: * method. The bytes written by this method
249: * may be read by the <code>readDouble</code>
250: * method of interface <code>DataInput</code>,
251: * which will then return a <code>double</code>
252: * equal to <code>v</code>.
253: *
254: * @param v the <code>double</code> value to be written.
255: * @throws IOException if an I/O error occurs.
256: */
257: void writeDouble(double v) throws IOException;
258:
259: /**
260: * Writes a string to the output stream.
261: * For every character in the string
262: * <code>s</code>, taken in order, one byte
263: * is written to the output stream. If
264: * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>
265: * is thrown.<p> If <code>s.length</code>
266: * is zero, then no bytes are written. Otherwise,
267: * the character <code>s[0]</code> is written
268: * first, then <code>s[1]</code>, and so on;
269: * the last character written is <code>s[s.length-1]</code>.
270: * For each character, one byte is written,
271: * the low-order byte, in exactly the manner
272: * of the <code>writeByte</code> method . The
273: * high-order eight bits of each character
274: * in the string are ignored.
275: *
276: * @param s the string of bytes to be written.
277: * @throws IOException if an I/O error occurs.
278: */
279: void writeBytes(String s) throws IOException;
280:
281: /**
282: * Writes every character in the string <code>s</code>,
283: * to the output stream, in order,
284: * two bytes per character. If <code>s</code>
285: * is <code>null</code>, a <code>NullPointerException</code>
286: * is thrown. If <code>s.length</code>
287: * is zero, then no characters are written.
288: * Otherwise, the character <code>s[0]</code>
289: * is written first, then <code>s[1]</code>,
290: * and so on; the last character written is
291: * <code>s[s.length-1]</code>. For each character,
292: * two bytes are actually written, high-order
293: * byte first, in exactly the manner of the
294: * <code>writeChar</code> method.
295: *
296: * @param s the string value to be written.
297: * @throws IOException if an I/O error occurs.
298: */
299: void writeChars(String s) throws IOException;
300:
301: /**
302: * Writes two bytes of length information
303: * to the output stream, followed
304: * by the
305: * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
306: * representation
307: * of every character in the string <code>s</code>.
308: * If <code>s</code> is <code>null</code>,
309: * a <code>NullPointerException</code> is thrown.
310: * Each character in the string <code>s</code>
311: * is converted to a group of one, two, or
312: * three bytes, depending on the value of the
313: * character.<p>
314: * If a character <code>c</code>
315: * is in the range <code>\u0001</code> through
316: * <code>\u007f</code>, it is represented
317: * by one byte:<p>
318: * <pre>(byte)c </pre> <p>
319: * If a character <code>c</code> is <code>\u0000</code>
320: * or is in the range <code>\u0080</code>
321: * through <code>\u07ff</code>, then it is
322: * represented by two bytes, to be written
323: * in the order shown:<p> <pre><code>
324: * (byte)(0xc0 | (0x1f & (c >> 6)))
325: * (byte)(0x80 | (0x3f & c))
326: * </code></pre> <p> If a character
327: * <code>c</code> is in the range <code>\u0800</code>
328: * through <code>uffff</code>, then it is
329: * represented by three bytes, to be written
330: * in the order shown:<p> <pre><code>
331: * (byte)(0xe0 | (0x0f & (c >> 12)))
332: * (byte)(0x80 | (0x3f & (c >> 6)))
333: * (byte)(0x80 | (0x3f & c))
334: * </code></pre> <p> First,
335: * the total number of bytes needed to represent
336: * all the characters of <code>s</code> is
337: * calculated. If this number is larger than
338: * <code>65535</code>, then a <code>UTFDataFormatException</code>
339: * is thrown. Otherwise, this length is written
340: * to the output stream in exactly the manner
341: * of the <code>writeShort</code> method;
342: * after this, the one-, two-, or three-byte
343: * representation of each character in the
344: * string <code>s</code> is written.<p> The
345: * bytes written by this method may be read
346: * by the <code>readUTF</code> method of interface
347: * <code>DataInput</code> , which will then
348: * return a <code>String</code> equal to <code>s</code>.
349: *
350: * @param s the string value to be written.
351: * @throws IOException if an I/O error occurs.
352: */
353: void writeUTF(String s) throws IOException;
354: }
|
