https://openjdk.java.net/ 
/*
 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.io;


The DataOutput interface provides
for converting data from any of the Java
primitive types to a series of bytes and
writing these bytes to a binary stream.
There is  also a facility for converting
a String into
modified UTF-8
format and writing the resulting series
of bytes.


For all the methods in this interface that
write bytes, it is generally true that if
a byte cannot be written for any reason,
an IOException is thrown.

Author: Frank Yellin
See Also:
Since:  1.0
/**
 * The <code>DataOutput</code> interface provides
 * for converting data from any of the Java
 * primitive types to a series of bytes and
 * writing these bytes to a binary stream.
 * There is  also a facility for converting
 * a <code>String</code> into
 * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
 * format and writing the resulting series
 * of bytes.
 * <p>
 * For all the methods in this interface that
 * write bytes, it is generally true that if
 * a byte cannot be written for any reason,
 * an <code>IOException</code> is thrown.
 *
 * @author  Frank Yellin
 * @see     java.io.DataInput
 * @see     java.io.DataOutputStream
 * @since   1.0
 */
public
interface DataOutput {
    
Writes to the output stream the eight
low-order bits of the argument b.
The 24 high-order  bits of b
are ignored.

Params:
  • b –   the byte to be written.
Throws:
/**
     * Writes to the output stream the eight
     * low-order bits of the argument <code>b</code>.
     * The 24 high-order  bits of <code>b</code>
     * are ignored.
     *
     * @param      b   the byte to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void write(int b) throws IOException;

    
Writes to the output stream all the bytes in array b.
If b is null,
a NullPointerException is thrown.
If b.length is zero, then
no bytes are written. Otherwise, the byte
b[0] is written first, then
b[1], and so on; the last byte
written is b[b.length-1].

Params:
  • b –   the data.
Throws:
/**
     * Writes to the output stream all the bytes in array <code>b</code>.
     * If <code>b</code> is <code>null</code>,
     * a <code>NullPointerException</code> is thrown.
     * If <code>b.length</code> is zero, then
     * no bytes are written. Otherwise, the byte
     * <code>b[0]</code> is written first, then
     * <code>b[1]</code>, and so on; the last byte
     * written is <code>b[b.length-1]</code>.
     *
     * @param      b   the data.
     * @throws     IOException  if an I/O error occurs.
     */
    void write(byte b[]) throws IOException;

    
Writes len bytes from array
b, in order,  to
the output stream.  If b
is null, a NullPointerException
is thrown.  If off is negative,
or len is negative, or off+len
is greater than the length of the array
b, then an IndexOutOfBoundsException
is thrown.  If len is zero,
then no bytes are written. Otherwise, the
byte b[off] is written first,
then b[off+1], and so on; the
last byte written is b[off+len-1].

Params:
  • b –     the data.
  • off –   the start offset in the data.
  • len –   the number of bytes to write.
Throws:
/**
     * Writes <code>len</code> bytes from array
     * <code>b</code>, in order,  to
     * the output stream.  If <code>b</code>
     * is <code>null</code>, a <code>NullPointerException</code>
     * is thrown.  If <code>off</code> is negative,
     * or <code>len</code> is negative, or <code>off+len</code>
     * is greater than the length of the array
     * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
     * is thrown.  If <code>len</code> is zero,
     * then no bytes are written. Otherwise, the
     * byte <code>b[off]</code> is written first,
     * then <code>b[off+1]</code>, and so on; the
     * last byte written is <code>b[off+len-1]</code>.
     *
     * @param      b     the data.
     * @param      off   the start offset in the data.
     * @param      len   the number of bytes to write.
     * @throws     IOException  if an I/O error occurs.
     */
    void write(byte b[], int off, int len) throws IOException;

    
Writes a boolean value to this output stream.
If the argument v
is true, the value (byte)1
is written; if v is false,
the  value (byte)0 is written.
The byte written by this method may
be read by the readBoolean
method of interface DataInput,
which will then return a boolean
equal to v.

Params:
  • v –   the boolean to be written.
Throws:
/**
     * Writes a <code>boolean</code> value to this output stream.
     * If the argument <code>v</code>
     * is <code>true</code>, the value <code>(byte)1</code>
     * is written; if <code>v</code> is <code>false</code>,
     * the  value <code>(byte)0</code> is written.
     * The byte written by this method may
     * be read by the <code>readBoolean</code>
     * method of interface <code>DataInput</code>,
     * which will then return a <code>boolean</code>
     * equal to <code>v</code>.
     *
     * @param      v   the boolean to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeBoolean(boolean v) throws IOException;

    
Writes to the output stream the eight low-
order bits of the argument v.
The 24 high-order bits of v
are ignored. (This means  that writeByte
does exactly the same thing as write
for an integer argument.) The byte written
by this method may be read by the readByte
method of interface DataInput,
which will then return a byte
equal to (byte)v.

Params:
  • v –   the byte value to be written.
Throws:
/**
     * Writes to the output stream the eight low-
     * order bits of the argument <code>v</code>.
     * The 24 high-order bits of <code>v</code>
     * are ignored. (This means  that <code>writeByte</code>
     * does exactly the same thing as <code>write</code>
     * for an integer argument.) The byte written
     * by this method may be read by the <code>readByte</code>
     * method of interface <code>DataInput</code>,
     * which will then return a <code>byte</code>
     * equal to <code>(byte)v</code>.
     *
     * @param      v   the byte value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeByte(int v) throws IOException;

    
Writes two bytes to the output
stream to represent the value of the argument.
The byte values to be written, in the  order
shown, are:


(byte)(0xff & (v >> 8))
(byte)(0xff & v)

 

The bytes written by this method may be
read by the readShort method
of interface DataInput , which
will then return a short equal
to (short)v.

Params:
  • v –   the short value to be written.
Throws:
/**
     * Writes two bytes to the output
     * stream to represent the value of the argument.
     * The byte values to be written, in the  order
     * shown, are:
     * <pre>{@code
     * (byte)(0xff & (v >> 8))
     * (byte)(0xff & v)
     * }</pre> <p>
     * The bytes written by this method may be
     * read by the <code>readShort</code> method
     * of interface <code>DataInput</code> , which
     * will then return a <code>short</code> equal
     * to <code>(short)v</code>.
     *
     * @param      v   the <code>short</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeShort(int v) throws IOException;

    
Writes a char value, which
is comprised of two bytes, to the
output stream.
The byte values to be written, in the  order
shown, are:


(byte)(0xff & (v >> 8))
(byte)(0xff & v)


The bytes written by this method may be
read by the readChar method
of interface DataInput , which
will then return a char equal
to (char)v.

Params:
  • v –   the char value to be written.
Throws:
/**
     * Writes a <code>char</code> value, which
     * is comprised of two bytes, to the
     * output stream.
     * The byte values to be written, in the  order
     * shown, are:
     * <pre>{@code
     * (byte)(0xff & (v >> 8))
     * (byte)(0xff & v)
     * }</pre><p>
     * The bytes written by this method may be
     * read by the <code>readChar</code> method
     * of interface <code>DataInput</code> , which
     * will then return a <code>char</code> equal
     * to <code>(char)v</code>.
     *
     * @param      v   the <code>char</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeChar(int v) throws IOException;

    
Writes an int value, which is
comprised of four bytes, to the output stream.
The byte values to be written, in the  order
shown, are:


(byte)(0xff & (v >> 24))
(byte)(0xff & (v >> 16))
(byte)(0xff & (v >>  8))
(byte)(0xff & v)


The bytes written by this method may be read
by the readInt method of interface
DataInput , which will then
return an int equal to v.

Params:
  • v –   the int value to be written.
Throws:
/**
     * Writes an <code>int</code> value, which is
     * comprised of four bytes, to the output stream.
     * The byte values to be written, in the  order
     * shown, are:
     * <pre>{@code
     * (byte)(0xff & (v >> 24))
     * (byte)(0xff & (v >> 16))
     * (byte)(0xff & (v >>  8))
     * (byte)(0xff & v)
     * }</pre><p>
     * The bytes written by this method may be read
     * by the <code>readInt</code> method of interface
     * <code>DataInput</code> , which will then
     * return an <code>int</code> equal to <code>v</code>.
     *
     * @param      v   the <code>int</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeInt(int v) throws IOException;

    
Writes a long value, which is
comprised of eight bytes, to the output stream.
The byte values to be written, in the  order
shown, are:


(byte)(0xff & (v >> 56))
(byte)(0xff & (v >> 48))
(byte)(0xff & (v >> 40))
(byte)(0xff & (v >> 32))
(byte)(0xff & (v >> 24))
(byte)(0xff & (v >> 16))
(byte)(0xff & (v >>  8))
(byte)(0xff & v)


The bytes written by this method may be
read by the readLong method
of interface DataInput , which
will then return a long equal
to v.

Params:
  • v –   the long value to be written.
Throws:
/**
     * Writes a <code>long</code> value, which is
     * comprised of eight bytes, to the output stream.
     * The byte values to be written, in the  order
     * shown, are:
     * <pre>{@code
     * (byte)(0xff & (v >> 56))
     * (byte)(0xff & (v >> 48))
     * (byte)(0xff & (v >> 40))
     * (byte)(0xff & (v >> 32))
     * (byte)(0xff & (v >> 24))
     * (byte)(0xff & (v >> 16))
     * (byte)(0xff & (v >>  8))
     * (byte)(0xff & v)
     * }</pre><p>
     * The bytes written by this method may be
     * read by the <code>readLong</code> method
     * of interface <code>DataInput</code> , which
     * will then return a <code>long</code> equal
     * to <code>v</code>.
     *
     * @param      v   the <code>long</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeLong(long v) throws IOException;

    
Writes a float value,
which is comprised of four bytes, to the output stream.
It does this as if it first converts this
float value to an int
in exactly the manner of the Float.floatToIntBits
method  and then writes the int
value in exactly the manner of the  writeInt
method.  The bytes written by this method
may be read by the readFloat
method of interface DataInput,
which will then return a float
equal to v.

Params:
  • v –   the float value to be written.
Throws:
/**
     * Writes a <code>float</code> value,
     * which is comprised of four bytes, to the output stream.
     * It does this as if it first converts this
     * <code>float</code> value to an <code>int</code>
     * in exactly the manner of the <code>Float.floatToIntBits</code>
     * method  and then writes the <code>int</code>
     * value in exactly the manner of the  <code>writeInt</code>
     * method.  The bytes written by this method
     * may be read by the <code>readFloat</code>
     * method of interface <code>DataInput</code>,
     * which will then return a <code>float</code>
     * equal to <code>v</code>.
     *
     * @param      v   the <code>float</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeFloat(float v) throws IOException;

    
Writes a double value,
which is comprised of eight bytes, to the output stream.
It does this as if it first converts this
double value to a long
in exactly the manner of the Double.doubleToLongBits
method  and then writes the long
value in exactly the manner of the  writeLong
method. The bytes written by this method
may be read by the readDouble
method of interface DataInput,
which will then return a double
equal to v.

Params:
  • v –   the double value to be written.
Throws:
/**
     * Writes a <code>double</code> value,
     * which is comprised of eight bytes, to the output stream.
     * It does this as if it first converts this
     * <code>double</code> value to a <code>long</code>
     * in exactly the manner of the <code>Double.doubleToLongBits</code>
     * method  and then writes the <code>long</code>
     * value in exactly the manner of the  <code>writeLong</code>
     * method. The bytes written by this method
     * may be read by the <code>readDouble</code>
     * method of interface <code>DataInput</code>,
     * which will then return a <code>double</code>
     * equal to <code>v</code>.
     *
     * @param      v   the <code>double</code> value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeDouble(double v) throws IOException;

    
Writes a string to the output stream.
For every character in the string
s,  taken in order, one byte
is written to the output stream.  If
s is null, a NullPointerException
is thrown.
  If s.length
is zero, then no bytes are written. Otherwise,
the character s[0] is written
first, then s[1], and so on;
the last character written is s[s.length-1].
For each character, one byte is written,
the low-order byte, in exactly the manner
of the writeByte method . The
high-order eight bits of each character
in the string are ignored.

Params:
  • s –   the string of bytes to be written.
Throws:
/**
     * Writes a string to the output stream.
     * For every character in the string
     * <code>s</code>,  taken in order, one byte
     * is written to the output stream.  If
     * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>
     * is thrown.<p>  If <code>s.length</code>
     * is zero, then no bytes are written. Otherwise,
     * the character <code>s[0]</code> is written
     * first, then <code>s[1]</code>, and so on;
     * the last character written is <code>s[s.length-1]</code>.
     * For each character, one byte is written,
     * the low-order byte, in exactly the manner
     * of the <code>writeByte</code> method . The
     * high-order eight bits of each character
     * in the string are ignored.
     *
     * @param      s   the string of bytes to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeBytes(String s) throws IOException;

    
Writes every character in the string s,
to the output stream, in order,
two bytes per character. If s
is null, a NullPointerException
is thrown.  If s.length
is zero, then no characters are written.
Otherwise, the character s[0]
is written first, then s[1],
and so on; the last character written is
s[s.length-1]. For each character,
two bytes are actually written, high-order
byte first, in exactly the manner of the
writeChar method.

Params:
  • s –   the string value to be written.
Throws:
/**
     * Writes every character in the string <code>s</code>,
     * to the output stream, in order,
     * two bytes per character. If <code>s</code>
     * is <code>null</code>, a <code>NullPointerException</code>
     * is thrown.  If <code>s.length</code>
     * is zero, then no characters are written.
     * Otherwise, the character <code>s[0]</code>
     * is written first, then <code>s[1]</code>,
     * and so on; the last character written is
     * <code>s[s.length-1]</code>. For each character,
     * two bytes are actually written, high-order
     * byte first, in exactly the manner of the
     * <code>writeChar</code> method.
     *
     * @param      s   the string value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeChars(String s) throws IOException;

    
Writes two bytes of length information
to the output stream, followed
by the
modified UTF-8
representation
of  every character in the string s.
If s is null,
a NullPointerException is thrown.
Each character in the string s
is converted to a group of one, two, or
three bytes, depending on the value of the
character.

If a character c
is in the range \u0001 through
\u007f, it is represented
by one byte:

(byte)c 
  

If a character c is \u0000
or is in the range \u0080
through \u07ff, then it is
represented by two bytes, to be written
in the order shown: 

(byte)(0xc0 | (0x1f & (c >> 6)))
(byte)(0x80 | (0x3f & c))

 
 If a character
c is in the range \u0800
through uffff, then it is
represented by three bytes, to be written
in the order shown: 

(byte)(0xe0 | (0x0f & (c >> 12)))
(byte)(0x80 | (0x3f & (c >>  6)))
(byte)(0x80 | (0x3f & c))

  
 First,
the total number of bytes needed to represent
all the characters of s is
calculated. If this number is larger than
65535, then a UTFDataFormatException
is thrown. Otherwise, this length is written
to the output stream in exactly the manner
of the writeShort method;
after this, the one-, two-, or three-byte
representation of each character in the
string s is written.
  The
bytes written by this method may be read
by the readUTF method of interface
DataInput , which will then
return a String equal to s.

Params:
  • s –   the string value to be written.
Throws:
/**
     * Writes two bytes of length information
     * to the output stream, followed
     * by the
     * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
     * representation
     * of  every character in the string <code>s</code>.
     * If <code>s</code> is <code>null</code>,
     * a <code>NullPointerException</code> is thrown.
     * Each character in the string <code>s</code>
     * is converted to a group of one, two, or
     * three bytes, depending on the value of the
     * character.<p>
     * If a character <code>c</code>
     * is in the range <code>&#92;u0001</code> through
     * <code>&#92;u007f</code>, it is represented
     * by one byte:
     * <pre>(byte)c </pre>  <p>
     * If a character <code>c</code> is <code>&#92;u0000</code>
     * or is in the range <code>&#92;u0080</code>
     * through <code>&#92;u07ff</code>, then it is
     * represented by two bytes, to be written
     * in the order shown: <pre>{@code
     * (byte)(0xc0 | (0x1f & (c >> 6)))
     * (byte)(0x80 | (0x3f & c))
     * }</pre> <p> If a character
     * <code>c</code> is in the range <code>&#92;u0800</code>
     * through <code>uffff</code>, then it is
     * represented by three bytes, to be written
     * in the order shown: <pre>{@code
     * (byte)(0xe0 | (0x0f & (c >> 12)))
     * (byte)(0x80 | (0x3f & (c >>  6)))
     * (byte)(0x80 | (0x3f & c))
     * }</pre>  <p> First,
     * the total number of bytes needed to represent
     * all the characters of <code>s</code> is
     * calculated. If this number is larger than
     * <code>65535</code>, then a <code>UTFDataFormatException</code>
     * is thrown. Otherwise, this length is written
     * to the output stream in exactly the manner
     * of the <code>writeShort</code> method;
     * after this, the one-, two-, or three-byte
     * representation of each character in the
     * string <code>s</code> is written.<p>  The
     * bytes written by this method may be read
     * by the <code>readUTF</code> method of interface
     * <code>DataInput</code> , which will then
     * return a <code>String</code> equal to <code>s</code>.
     *
     * @param      s   the string value to be written.
     * @throws     IOException  if an I/O error occurs.
     */
    void writeUTF(String s) throws IOException;
}