View Javadoc
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       */
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       */
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       */
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      */
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:
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      */
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      */
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      */
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      */
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>&#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      */
353     void writeUTF(String s) throws IOException;
354 }