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 1.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 */ write(int b)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 */ write(byte b[])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 */ write(byte b[], int off, int len)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 */ writeBoolean(boolean v)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 */ writeByte(int v)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 */ writeShort(int v)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 */ writeChar(int v)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 */ writeInt(int v)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 */ writeLong(long v)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 */ writeFloat(float v)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 */ writeDouble(double v)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 */ writeBytes(String s)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 */ writeChars(String s)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>\u0001</code> through 316 * <code>\u007f</code>, it is represented 317 * by one byte: 318 * <pre>(byte)c </pre> <p> 319 * If a character <code>c</code> is <code>\u0000</code> 320 * or is in the range <code>\u0080</code> 321 * through <code>\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>\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 */ writeUTF(String s)353 void writeUTF(String s) throws IOException; 354 } 355