001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.io;
028:
029: /**
030: * The <code>DataOutput</code> interface provides
031: * for converting data from any of the Java
032: * primitive types to a series of bytes and
033: * writing these bytes to a binary stream.
034: * There is also a facility for converting
035: * a <code>String</code> into Java modified
036: * UTF-8 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: * @version 12/17/01 (CLDC 1.1)
045: * @see java.io.DataInput
046: * @see java.io.DataOutputStream
047: * @since JDK1.0, CLDC 1.0
048: */
049: public interface DataOutput {
050:
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: * @exception 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: * @exception 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: * @exception 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: * @exception 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: * @exception 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: * @exception 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: * @exception 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: * @exception IOException if an I/O error occurs.
192: */
193: void writeInt(int v) throws IOException;
194:
195: /**
196: * Writes an <code>long</code> value, which is
197: * comprised of four 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: * @exception 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: * @exception IOException if an I/O error occurs.
237: * @since CLDC 1.1
238: */
239: void writeFloat(float v) throws IOException;
240:
241: /**
242: * Writes a <code>double</code> value,
243: * which is comprised of eight bytes, to the output stream.
244: * It does this as if it first converts this
245: * <code>double</code> value to a <code>long</code>
246: * in exactly the manner of the <code>Double.doubleToLongBits</code>
247: * method and then writes the <code>long</code>
248: * value in exactly the manner of the <code>writeLong</code>
249: * method. The bytes written by this method
250: * may be read by the <code>readDouble</code>
251: * method of interface <code>DataInput</code>,
252: * which will then return a <code>double</code>
253: * equal to <code>v</code>.
254: *
255: * @param v the <code>double</code> value to be written.
256: * @exception IOException if an I/O error occurs.
257: * @since CLDC 1.1
258: */
259: void writeDouble(double v) throws IOException;
260:
261: /**
262: * Writes every character in the string <code>s</code>,
263: * to the output stream, in order,
264: * two bytes per character. If <code>s</code>
265: * is <code>null</code>, a <code>NullPointerException</code>
266: * is thrown. If <code>s.length</code>
267: * is zero, then no characters are written.
268: * Otherwise, the character <code>s[0]</code>
269: * is written first, then <code>s[1]</code>,
270: * and so on; the last character written is
271: * <code>s[s.length-1]</code>. For each character,
272: * two bytes are actually written, high-order
273: * byte first, in exactly the manner of the
274: * <code>writeChar</code> method.
275: *
276: * @param s the string value to be written.
277: * @exception IOException if an I/O error occurs.
278: */
279: void writeChars(String s) throws IOException;
280:
281: /**
282: * Writes two bytes of length information
283: * to the output stream, followed
284: * by the Java modified UTF representation
285: * of every character in the string <code>s</code>.
286: * If <code>s</code> is <code>null</code>,
287: * a <code>NullPointerException</code> is thrown.
288: * Each character in the string <code>s</code>
289: * is converted to a group of one, two, or
290: * three bytes, depending on the value of the
291: * character.<p>
292: * If a character <code>c</code>
293: * is in the range <code>\u0001</code> through
294: * <code>\u007f</code>, it is represented
295: * by one byte:<p>
296: * <pre>(byte)c </pre> <p>
297: * If a character <code>c</code> is <code>\u0000</code>
298: * or is in the range <code>\u0080</code>
299: * through <code>\u07ff</code>, then it is
300: * represented by two bytes, to be written
301: * in the order shown:<p> <pre><code>
302: * (byte)(0xc0 | (0x1f & (c >> 6)))
303: * (byte)(0x80 | (0x3f & c))
304: * </code></pre> <p> If a character
305: * <code>c</code> is in the range <code>\u0800</code>
306: * through <code>uffff</code>, then it is
307: * represented by three bytes, to be written
308: * in the order shown:<p> <pre><code>
309: * (byte)(0xe0 | (0x0f & (c >> 12)))
310: * (byte)(0x80 | (0x3f & (c >> 6)))
311: * (byte)(0x80 | (0x3f & c))
312: * </code></pre> <p> First,
313: * the total number of bytes needed to represent
314: * all the characters of <code>s</code> is
315: * calculated. If this number is larger than
316: * <code>65535</code>, then a <code>UTFDataFormatError</code>
317: * is thrown. Otherwise, this length is written
318: * to the output stream in exactly the manner
319: * of the <code>writeShort</code> method;
320: * after this, the one-, two-, or three-byte
321: * representation of each character in the
322: * string <code>s</code> is written.<p> The
323: * bytes written by this method may be read
324: * by the <code>readUTF</code> method of interface
325: * <code>DataInput</code>, which will then
326: * return a <code>String</code> equal to <code>s</code>.
327: *
328: * @param s the string value to be written.
329: * @exception IOException if an I/O error occurs.
330: */
331: void writeUTF(String s) throws IOException;
332:
333: }
|