1 /*
2  * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.io;
27 
28 /**
29  * The <code>DataOutput</code> interface provides
30  * for converting data from any of the Java
31  * primitive types to a series of bytes and
32  * writing these bytes to a binary stream.
33  * There is  also a facility for converting
34  * a <code>String</code> into
35  * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
36  * format and writing the resulting series
37  * of bytes.
38  * <p>
39  * For all the methods in this interface that
40  * write bytes, it is generally true that if
41  * a byte cannot be written for any reason,
42  * an <code>IOException</code> is thrown.
43  *
44  * @author  Frank Yellin
45  * @see     java.io.DataInput
46  * @see     java.io.DataOutputStream
47  * @since   JDK1.0
48  */
49 public
50 interface DataOutput {
51     /**
52      * Writes to the output stream the eight
53      * low-order bits of the argument <code>b</code>.
54      * The 24 high-order  bits of <code>b</code>
55      * are ignored.
56      *
57      * @param      b   the byte to be written.
58      * @throws     IOException  if an I/O error occurs.
59      */
write(int b)60     void write(int b) throws IOException;
61 
62     /**
63      * Writes to the output stream all the bytes in array <code>b</code>.
64      * If <code>b</code> is <code>null</code>,
65      * a <code>NullPointerException</code> is thrown.
66      * If <code>b.length</code> is zero, then
67      * no bytes are written. Otherwise, the byte
68      * <code>b[0]</code> is written first, then
69      * <code>b[1]</code>, and so on; the last byte
70      * written is <code>b[b.length-1]</code>.
71      *
72      * @param      b   the data.
73      * @throws     IOException  if an I/O error occurs.
74      */
write(byte b[])75     void write(byte b[]) throws IOException;
76 
77     /**
78      * Writes <code>len</code> bytes from array
79      * <code>b</code>, in order,  to
80      * the output stream.  If <code>b</code>
81      * is <code>null</code>, a <code>NullPointerException</code>
82      * is thrown.  If <code>off</code> is negative,
83      * or <code>len</code> is negative, or <code>off+len</code>
84      * is greater than the length of the array
85      * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
86      * is thrown.  If <code>len</code> is zero,
87      * then no bytes are written. Otherwise, the
88      * byte <code>b[off]</code> is written first,
89      * then <code>b[off+1]</code>, and so on; the
90      * last byte written is <code>b[off+len-1]</code>.
91      *
92      * @param      b     the data.
93      * @param      off   the start offset in the data.
94      * @param      len   the number of bytes to write.
95      * @throws     IOException  if an I/O error occurs.
96      */
write(byte b[], int off, int len)97     void write(byte b[], int off, int len) throws IOException;
98 
99     /**
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      */
writeBoolean(boolean v)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      */
writeByte(int v)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:
138      * <pre>{@code
139      * (byte)(0xff & (v >> 8))
140      * (byte)(0xff & v)
141      * }</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      */
writeShort(int v)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      * <pre>{@code
160      * (byte)(0xff & (v >> 8))
161      * (byte)(0xff & v)
162      * }</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      */
writeChar(int v)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      * <pre>{@code
180      * (byte)(0xff & (v >> 24))
181      * (byte)(0xff & (v >> 16))
182      * (byte)(0xff & (v >>  8))
183      * (byte)(0xff & v)
184      * }</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      */
writeInt(int v)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      * <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      * }</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      */
writeLong(long v)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      */
writeFloat(float v)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      */
writeDouble(double v)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      */
writeBytes(String s)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      */
writeChars(String s)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>&#92;u0001</code> through
316      * <code>&#92;u007f</code>, it is represented
317      * by one byte:
318      * <pre>(byte)c </pre>  <p>
319      * If a character <code>c</code> is <code>&#92;u0000</code>
320      * or is in the range <code>&#92;u0080</code>
321      * through <code>&#92;u07ff</code>, then it is
322      * represented by two bytes, to be written
323      * in the order shown: <pre>{@code
324      * (byte)(0xc0 | (0x1f & (c >> 6)))
325      * (byte)(0x80 | (0x3f & c))
326      * }</pre> <p> If a character
327      * <code>c</code> is in the range <code>&#92;u0800</code>
328      * through <code>uffff</code>, then it is
329      * represented by three bytes, to be written
330      * in the order shown: <pre>{@code
331      * (byte)(0xe0 | (0x0f & (c >> 12)))
332      * (byte)(0x80 | (0x3f & (c >>  6)))
333      * (byte)(0x80 | (0x3f & c))
334      * }</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      */
writeUTF(String s)353     void writeUTF(String s) throws IOException;
354 }
355