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 18 package 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 */ 30 public 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 */ write(byte[] buffer)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 */ write(byte[] buffer, int offset, int count)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 */ write(int oneByte)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 */ writeBoolean(boolean val)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 */ writeByte(int val)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 */ writeBytes(String str)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 */ writeChar(int val)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 */ writeChars(String str)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 */ writeDouble(double val)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 */ writeFloat(float val)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 */ writeInt(int val)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 */ writeLong(long val)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 */ writeShort(int val)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 */ writeUTF(String str)193 public abstract void writeUTF(String str) throws IOException; 194 } 195