| Frames | No Frames |
1: /* DataOutput.java -- Interface for writing data from a stream 2: Copyright (C) 1998, 1999, 2001, 2003, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.io; 40: 41: /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 42: * "The Java Language Specification", ISBN 0-201-63451-1 43: * Status: Complete to version 1.1. 44: */ 45: 46: /** 47: * This interface is implemented by classes that can wrte data to streams 48: * from Java primitive types. This data can subsequently be read back 49: * by classes implementing the <code>DataInput</code> interface. 50: * 51: * @author Aaron M. Renn (arenn@urbanophile.com) 52: * @author Tom Tromey (tromey@cygnus.com) 53: * 54: * @see DataInput 55: */ 56: public interface DataOutput 57: { 58: /** 59: * This method writes a Java boolean value to an output stream. If 60: * <code>value</code> is <code>true</code>, a byte with the value of 61: * 1 will be written, otherwise a byte with the value of 0 will be 62: * written. 63: * 64: * The value written can be read using the <code>readBoolean</code> 65: * method in <code>DataInput</code>. 66: * 67: * @param value The boolean value to write 68: * 69: * @exception IOException If an error occurs 70: * 71: * @see DataInput#readBoolean 72: */ 73: void writeBoolean(boolean value) throws IOException; 74: 75: /** 76: * This method writes a Java byte value to an output stream. The 77: * byte to be written will be in the lowest 8 bits of the 78: * <code>int</code> value passed. 79: * 80: * The value written can be read using the <code>readByte</code> or 81: * <code>readUnsignedByte</code> methods in <code>DataInput</code>. 82: * 83: * @param value The int value to write 84: * 85: * @exception IOException If an error occurs 86: * 87: * @see DataInput#readByte 88: * @see DataInput#readUnsignedByte 89: */ 90: void writeByte(int value) throws IOException; 91: 92: /** 93: * This method writes a Java char value to an output stream. The 94: * char to be written will be in the lowest 16 bits of the <code>int</code> 95: * value passed. These bytes will be written "big endian". That is, 96: * with the high byte written first in the following manner: 97: * <p> 98: * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br> 99: * 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