/*
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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: - IOException – if an I/O error occurs.
/**
* 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>\u0001</code> through
* <code>\u007f</code>, it is represented
* by one byte:
* <pre>(byte)c </pre> <p>
* If a character <code>c</code> is <code>\u0000</code>
* or is in the range <code>\u0080</code>
* through <code>\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>\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;
}