1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.io;
19
20/**
21 * Defines an interface for classes that are able to write big-endian typed data to some
22 * target. Typically, this data can be read in by a class which implements
23 * DataInput. Types that can be written include byte, 16-bit short, 32-bit int,
24 * 32-bit float, 64-bit long, 64-bit double, byte strings, and {@link DataInput
25 * MUTF-8} encoded strings.
26 *
27 * @see DataOutputStream
28 * @see RandomAccessFile
29 */
30public interface DataOutput {
31
32    /**
33     * Writes the entire contents of the byte array {@code buffer} to this
34     * stream.
35     *
36     * @param buffer
37     *            the buffer to write.
38     * @throws IOException
39     *             if an I/O error occurs while writing.
40     */
41    public abstract void write(byte[] buffer) throws IOException;
42
43    /**
44     * Writes {@code count} bytes from the byte array {@code buffer} starting at
45     * offset {@code index}.
46     *
47     * @param buffer
48     *            the buffer to write.
49     * @param offset
50     *            the index of the first byte in {@code buffer} to write.
51     * @param count
52     *            the number of bytes from the {@code buffer} to write.
53     * @throws IOException
54     *             if an I/O error occurs while writing.
55     */
56    public abstract void write(byte[] buffer, int offset, int count) throws IOException;
57
58    /**
59     * Writes the specified 8-bit byte.
60     *
61     * @param oneByte
62     *            the byte to write.
63     * @throws IOException
64     *             if an I/O error occurs while writing.
65     * @see DataInput#readByte()
66     */
67    public abstract void write(int oneByte) throws IOException;
68
69    /**
70     * Writes the specified boolean.
71     *
72     * @param val
73     *            the boolean value to write.
74     * @throws IOException
75     *             if an I/O error occurs while writing.
76     * @see DataInput#readBoolean()
77     */
78    public abstract void writeBoolean(boolean val) throws IOException;
79
80    /**
81     * Writes the specified 8-bit byte.
82     *
83     * @param val
84     *            the byte value to write.
85     * @throws IOException
86     *             if an I/O error occurs while writing.
87     * @see DataInput#readByte()
88     * @see DataInput#readUnsignedByte()
89     */
90    public abstract void writeByte(int val) throws IOException;
91
92    /**
93     * Writes the low order 8-bit bytes from the specified string.
94     *
95     * @param str
96     *            the string containing the bytes to write.
97     * @throws IOException
98     *             if an I/O error occurs while writing.
99     */
100    public abstract void writeBytes(String str) throws IOException;
101
102    /**
103     * Writes the specified 16-bit character in big-endian order. Only the two least significant
104     * bytes of the integer {@code oneByte} are written.
105     *
106     * @param val
107     *            the character to write.
108     * @throws IOException
109     *             if an I/O error occurs while writing.
110     * @see DataInput#readChar()
111     */
112    public abstract void writeChar(int val) throws IOException;
113
114    /**
115     * Writes the 16-bit characters contained in {@code str} in big-endian order.
116     *
117     * @param str
118     *            the string that contains the characters to write.
119     * @throws IOException
120     *             if an I/O error occurs while writing.
121     * @see DataInput#readChar()
122     */
123    public abstract void writeChars(String str) throws IOException;
124
125    /**
126     * Writes the specified 64-bit double in big-endian order. The resulting output is the eight
127     * bytes returned by {@link Double#doubleToLongBits(double)}.
128     *
129     * @param val
130     *            the double to write.
131     * @throws IOException
132     *             if an I/O error occurs while writing.
133     * @see DataInput#readDouble()
134     */
135    public abstract void writeDouble(double val) throws IOException;
136
137    /**
138     * Writes the specified 32-bit float in big-endian order. The resulting output is the four bytes
139     * returned by {@link Float#floatToIntBits(float)}.
140     *
141     * @param val
142     *            the float to write.
143     * @throws IOException
144     *             if an I/O error occurs while writing.
145     * @see DataInput#readFloat()
146     */
147    public abstract void writeFloat(float val) throws IOException;
148
149    /**
150     * Writes the specified 32-bit int in big-endian order.
151     *
152     * @param val
153     *            the int to write.
154     * @throws IOException
155     *             if an I/O error occurs while writing.
156     * @see DataInput#readInt()
157     */
158    public abstract void writeInt(int val) throws IOException;
159
160    /**
161     * Writes the specified 64-bit long in big-endian order.
162     *
163     * @param val
164     *            the long to write.
165     * @throws IOException
166     *             if an I/O error occurs while writing.
167     * @see DataInput#readLong()
168     */
169    public abstract void writeLong(long val) throws IOException;
170
171    /**
172     * Writes the specified 16-bit short in big-endian order. Only the lower two bytes of {@code
173     * val} are written.
174     *
175     * @param val
176     *            the short to write.
177     * @throws IOException
178     *             if an I/O error occurs while writing.
179     * @see DataInput#readShort()
180     * @see DataInput#readUnsignedShort()
181     */
182    public abstract void writeShort(int val) throws IOException;
183
184    /**
185     * Writes the specified string encoded in {@link DataInput modified UTF-8}.
186     *
187     * @param str
188     *            the string to write encoded in {@link DataInput modified UTF-8}.
189     * @throws IOException
190     *             if an I/O error occurs while writing.
191     * @see DataInput#readUTF()
192     */
193    public abstract void writeUTF(String str) throws IOException;
194}
195