libjava/java/io/DataOutput.java

   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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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
 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