001 /* DataOutput.java -- Interface for writing data from a stream 002 Copyright (C) 1998, 1999, 2001, 2003, 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.io; 040 041 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 042 * "The Java Language Specification", ISBN 0-201-63451-1 043 * Status: Complete to version 1.1. 044 */ 045 046 /** 047 * This interface is implemented by classes that can wrte data to streams 048 * from Java primitive types. This data can subsequently be read back 049 * by classes implementing the <code>DataInput</code> interface. 050 * 051 * @author Aaron M. Renn (arenn@urbanophile.com) 052 * @author Tom Tromey (tromey@cygnus.com) 053 * 054 * @see DataInput 055 */ 056 public interface DataOutput 057 { 058 /** 059 * This method writes a Java boolean value to an output stream. If 060 * <code>value</code> is <code>true</code>, a byte with the value of 061 * 1 will be written, otherwise a byte with the value of 0 will be 062 * written. 063 * 064 * The value written can be read using the <code>readBoolean</code> 065 * method in <code>DataInput</code>. 066 * 067 * @param value The boolean value to write 068 * 069 * @exception IOException If an error occurs 070 * 071 * @see DataInput#readBoolean 072 */ 073 void writeBoolean(boolean value) throws IOException; 074 075 /** 076 * This method writes a Java byte value to an output stream. The 077 * byte to be written will be in the lowest 8 bits of the 078 * <code>int</code> value passed. 079 * 080 * The value written can be read using the <code>readByte</code> or 081 * <code>readUnsignedByte</code> methods in <code>DataInput</code>. 082 * 083 * @param value The int value to write 084 * 085 * @exception IOException If an error occurs 086 * 087 * @see DataInput#readByte 088 * @see DataInput#readUnsignedByte 089 */ 090 void writeByte(int value) throws IOException; 091 092 /** 093 * This method writes a Java char value to an output stream. The 094 * char to be written will be in the lowest 16 bits of the <code>int</code> 095 * value passed. These bytes will be written "big endian". That is, 096 * with the high byte written first in the following manner: 097 * <p> 098 * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br> 099 * byte1 = (byte)(value & 0x00FF);</code> 100 * <p> 101 * 102 * The value written can be read using the <code>readChar</code> 103 * method in <code>DataInput</code>. 104 * 105 * @param value The char value to write 106 * 107 * @exception IOException If an error occurs 108 * 109 * @see DataInput#readChar 110 */ 111 void writeChar(int value) throws IOException; 112 113 /** 114 * This method writes a Java short value to an output stream. The 115 * char to be written will be in the lowest 16 bits of the <code>int</code> 116 * value passed. These bytes will be written "big endian". That is, 117 * with the high byte written first in the following manner: 118 * <p> 119 * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br> 120 * byte1 = (byte)(value & 0x00FF);</code> 121 * <p> 122 * 123 * The value written can be read using the <code>readShort</code> and 124 * <code>readUnsignedShort</code> methods in <code>DataInput</code>. 125 * 126 * @param value The int value to write as a 16-bit value 127 * 128 * @exception IOException If an error occurs 129 * 130 * @see DataInput#readShort 131 * @see DataInput#readUnsignedShort 132 */ 133 void writeShort(int value) throws IOException; 134 135 /** 136 * This method writes a Java int value to an output stream. The 4 bytes 137 * of the passed value will be written "big endian". That is, with 138 * the high byte written first in the following manner: 139 * <p> 140 * <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br> 141 * byte1 = (byte)((value & 0x00FF0000) >> 16);<br> 142 * byte2 = (byte)((value & 0x0000FF00) >> 8);<br> 143 * byte3 = (byte)(value & 0x000000FF);</code> 144 * <p> 145 * 146 * The value written can be read using the <code>readInt</code> 147 * method in <code>DataInput</code>. 148 * 149 * @param value The int value to write 150 * 151 * @exception IOException If an error occurs 152 * 153 * @see DataInput#readInt 154 */ 155 void writeInt(int value) throws IOException; 156 157 /** 158 * This method writes a Java long value to an output stream. The 8 bytes 159 * of the passed value will be written "big endian". That is, with 160 * the high byte written first in the following manner: 161 * <p> 162 * <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br> 163 * byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br> 164 * byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br> 165 * byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br> 166 * byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br> 167 * byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br> 168 * byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br> 169 * byte7 = (byte)(value & 0x00000000000000FFL);</code> 170 * <p> 171 * 172 * The value written can be read using the <code>readLong</code> 173 * method in <code>DataInput</code>. 174 * 175 * @param value The long value to write 176 * 177 * @exception IOException If an error occurs 178 * 179 * @see DataInput#readLong 180 */ 181 void writeLong(long value) throws IOException; 182 183 /** 184 * This method writes a Java <code>float</code> value to the stream. This 185 * value is written by first calling the method 186 * <code>Float.floatToIntBits</code> 187 * to retrieve an <code>int</code> representing the floating point number, 188 * then writing this <code>int</code> value to the stream exactly the same 189 * as the <code>writeInt()</code> method does. 190 * 191 * The value written can be read using the <code>readFloat</code> 192 * method in <code>DataInput</code>. 193 * 194 * @param value The float value to write 195 * 196 * @exception IOException If an error occurs 197 * 198 * @see #writeInt 199 * @see DataInput#readFloat 200 * @see Float#floatToIntBits 201 */ 202 void writeFloat(float value) throws IOException; 203 204 /** 205 * This method writes a Java <code>double</code> value to the stream. This 206 * value is written by first calling the method 207 * <code>Double.doubleToLongBits</code> 208 * to retrieve an <code>long</code> representing the floating point number, 209 * then writing this <code>long</code> value to the stream exactly the same 210 * as the <code>writeLong()</code> method does. 211 * 212 * The value written can be read using the <code>readDouble</code> 213 * method in <code>DataInput</code>. 214 * 215 * @param value The double value to write 216 * 217 * @exception IOException If any other error occurs 218 * 219 * @see #writeLong 220 * @see DataInput#readDouble 221 * @see Double#doubleToLongBits 222 */ 223 void writeDouble(double value) throws IOException; 224 225 /** 226 * This method writes all the bytes in a <code>String</code> out to the 227 * stream. One byte is written for each character in the 228 * <code>String</code>. 229 * The high eight bits of each character are discarded, thus this 230 * method is inappropriate for completely representing Unicode characters. 231 * 232 * @param value The <code>String</code> to write 233 * 234 * @exception IOException If an error occurs 235 */ 236 void writeBytes(String value) throws IOException; 237 238 /** 239 * This method writes all the characters of a <code>String</code> to an 240 * output stream as an array of <code>char</code>'s. Each character 241 * is written using the method specified in the <code>writeChar</code> 242 * method. 243 * 244 * @param value The String to write 245 * 246 * @exception IOException If an error occurs 247 * 248 * @see #writeChar(int) 249 */ 250 void writeChars(String value) throws IOException; 251 252 /** 253 * This method writes a Java <code>String</code> to the stream in a modified 254 * UTF-8 format. First, two bytes are written to the stream indicating the 255 * number of bytes to follow. This is written in the form of a Java 256 * <code>short</code> value in the same manner used by the 257 * <code>writeShort</code> method. Note that this is the number of 258 * bytes in the 259 * encoded <code>String</code> not the <code>String</code> length. Next 260 * come the encoded characters. Each character in the <code>String</code> 261 * is encoded as either one, two or three bytes. For characters in the 262 * range of <code>\u0001</code> to <code>\u007F</code>, one byte is used. 263 * The character 264 * value goes into bits 0-7 and bit eight is 0. For characters in the range 265 * of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used. Bits 266 * 6-10 of the character value are encoded bits 0-4 of the first byte, with 267 * the high bytes having a value of "110". Bits 0-5 of the character value 268 * are stored in bits 0-5 of the second byte, with the high bits set to 269 * "10". This type of encoding is also done for the null character 270 * <code>\u0000</code>. This eliminates any C style NUL character values 271 * in the output. All remaining characters are stored as three bytes. 272 * Bits 12-15 of the character value are stored in bits 0-3 of the first 273 * byte. The high bits of the first bytes are set to "1110". Bits 6-11 274 * of the character value are stored in bits 0-5 of the second byte. The 275 * high bits of the second byte are set to "10". And bits 0-5 of the 276 * character value are stored in bits 0-5 of byte three, with the high bits 277 * of that byte set to "10". 278 * 279 * The value written can be read using the <code>readUTF</code> 280 * method in <code>DataInput</code>. 281 * 282 * @param value The <code>String</code> to write 283 * 284 * @exception IOException If an error occurs 285 * 286 * @see DataInput#readUTF 287 */ 288 void writeUTF(String value) throws IOException; 289 290 /** 291 * This method writes an 8-bit value (passed into the method as a Java 292 * <code>int</code>) to an output stream. The low 8 bits of the 293 * passed value are written. 294 * 295 * @param value The <code>byte</code> to write to the output stream 296 * 297 * @exception IOException If an error occurs 298 */ 299 void write(int value) throws IOException; 300 301 /** 302 * This method writes the raw byte array passed in to the output stream. 303 * 304 * @param buf The byte array to write 305 * 306 * @exception IOException If an error occurs 307 */ 308 void write(byte[] buf) throws IOException; 309 310 /** 311 * This method writes raw bytes from the passed array <code>buf</code> 312 * starting 313 * <code>offset</code> bytes into the buffer. The number of bytes 314 * written will be exactly <code>len</code>. 315 * 316 * @param buf The buffer from which to write the data 317 * @param offset The offset into the buffer to start writing data from 318 * @param len The number of bytes to write from the buffer to the output 319 * stream 320 * 321 * @exception IOException If any other error occurs 322 */ 323 void write(byte[] buf, int offset, int len) throws IOException; 324 325 } // interface DataOutput 326