home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / io / DataOutput.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  13.4 KB  |  355 lines
  1. /*
  2.  * @(#)DataOutput.java    1.9 98/03/18
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17. /**
  18.  * The <code>DataOutput</code> interface provides
  19.  * for converting data from any of the Java
  20.  * primitive types to a series of bytes and
  21.  * writing these bytes to a binary stream. 
  22.  * There is  also a facility for converting
  23.  * a <code>String</code> into Java modified
  24.  * UTF-8 format and writing the resulting series
  25.  * of bytes.
  26.  * <p>
  27.  * For all the methods in this interface that
  28.  * write bytes, it is generally true that if
  29.  * a byte cannot be written for any reason,
  30.  * an <code>IOException</code> is thrown.
  31.  *
  32.  * @author  Frank Yellin
  33.  * @version 1.9, 03/18/98
  34.  * @see     java.io.DataInput  
  35.  * @see     java.io.DataOutputStream
  36.  * @since   JDK1.0
  37.  */
  38. public
  39. interface DataOutput {
  40.     /**
  41.      * Writes to the output stream the eight
  42.      * low-order bits of the argument <code>b</code>.
  43.      * The 24 high-order  bits of <code>b</code>
  44.      * are ignored. 
  45.      *
  46.      * @param      b   the byte to be written.
  47.      * @exception  IOException  if an I/O error occurs.
  48.      * @since      JDK1.0
  49.      */
  50.     void write(int b) throws IOException;
  51.  
  52.     /**
  53.      * Writes to the output stream all the bytes in array <code>b</code>.
  54.      * If <code>b</code> is <code>null</code>,
  55.      * a <code>NullPointerException</code> is thrown.
  56.      * If <code>b.length</code> is zero, then 
  57.      * no bytes are written. Otherwise, the byte
  58.      * <code>b[0]</code> is written first, then
  59.      * <code>b[1]</code>, and so on; the last byte
  60.      * written is <code>b[b.length-1]</code>.
  61.      *
  62.      * @param      b   the data.
  63.      * @exception  IOException  if an I/O error occurs.
  64.      * @since      JDK1.0
  65.      */
  66.     void write(byte b[]) throws IOException;
  67.  
  68.     /**
  69.      * Writes <code>len</code> bytes from array
  70.      * <code>b</code>, in order,  to
  71.      * the output stream.  If <code>b</code>
  72.      * is <code>null</code>, a <code>NullPointerException</code>
  73.      * is thrown.  If <code>off</code> is negative,
  74.      * or <code>len</code> is negative, or <code>off+len</code>
  75.      * is greater than the length of the array 
  76.      * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
  77.      * is thrown.  If <code>len</code> is zero,
  78.      * then no bytes are written. Otherwise, the
  79.      * byte <code>b[off]</code> is written first,
  80.      * then <code>b[off+1]</code>, and so on; the
  81.      * last byte written is <code>b[off+len-1]</code>.
  82.      *
  83.      * @param      b     the data.
  84.      * @param      off   the start offset in the data.
  85.      * @param      len   the number of bytes to write.
  86.      * @exception  IOException  if an I/O error occurs.
  87.      * @since      JDK1.0
  88.      */
  89.     void write(byte b[], int off, int len) throws IOException;
  90.  
  91.     /**
  92.      * Writes a <code>boolean</code> value to this output stream. 
  93.      * If the argument <code>v</code> 
  94.      * is <code>true</code>, the value <code>(byte)1</code>
  95.      * is written; if <code>v</code> is <code>false</code>,
  96.      * the  value <code>(byte)0</code> is written.
  97.      * The byte written by this method may 
  98.      * be read by the <code>readBoolean</code> 
  99.      * method of interface <code>DataInput</code>,
  100.      * which will then return a <code>boolean</code>
  101.      * equal to <code>v</code>.
  102.      *
  103.      * @param      v   the boolean to be written.
  104.      * @exception  IOException  if an I/O error occurs.
  105.      * @since      JDK1.0
  106.      */
  107.     void writeBoolean(boolean v) throws IOException;
  108.  
  109.     /**
  110.      * Writes to the output stream the eight low-
  111.      * order bits of the argument <code>v</code>.
  112.      * The 24 high-order bits of <code>v</code>
  113.      * are ignored. (This means  that <code>writeByte</code>
  114.      * does exactly the same thing as <code>write</code>
  115.      * for an integer argument.) The byte written
  116.      * by this method may be read by the <code>readByte</code>
  117.      * method of interface <code>DataInput</code>,
  118.      * which will then return a <code>byte</code>
  119.      * equal to <code>(byte)v</code>.
  120.      *
  121.      * @param      v   the byte value to be written.
  122.      * @exception  IOException  if an I/O error occurs.
  123.      * @since      JDK1.0
  124.      */
  125.     void writeByte(int v) throws IOException;
  126.  
  127.     /**
  128.      * Writes two bytes to the output
  129.      * stream to represent the value of the argument.
  130.      * The byte values to be written, in the  order
  131.      * shown, are: <p>
  132.      * <pre><code> 
  133.      * (byte)(0xff & (v >> 8)) 
  134.      * (byte)(0xff & v) 
  135.      * </code> </pre> <p>
  136.      * The bytes written by this method may be 
  137.      * read by the <code>readShort</code> method
  138.      * of interface <code>DataInput</code> , which
  139.      * will then return a <code>short</code> equal
  140.      * to <code>(short)v</code>.
  141.      *
  142.      * @param      v   the <code>short</code> value to be written.
  143.      * @exception  IOException  if an I/O error occurs.
  144.      * @since      JDK1.0
  145.      */
  146.     void writeShort(int v) throws IOException;
  147.  
  148.     /**
  149.      * Writes a <code>char</code> value, wich 
  150.      * is comprised of two bytes, to the
  151.      * output stream.
  152.      * The byte values to be written, in the  order
  153.      * shown, are: 
  154.      * <p><pre><code> 
  155.      * (byte)(0xff & (v >> 8)) 
  156.      * (byte)(0xff & v) 
  157.      * </code></pre><p>
  158.      * The bytes written by this method may be 
  159.      * read by the <code>readChar</code> method
  160.      * of interface <code>DataInput</code> , which
  161.      * will then return a <code>char</code> equal
  162.      * to <code>(char)v</code>.
  163.      *
  164.      * @param      v   the <code>char</code> value to be written.
  165.      * @exception  IOException  if an I/O error occurs.
  166.      * @since      JDK1.0
  167.      */
  168.     void writeChar(int v) throws IOException;
  169.  
  170.     /**
  171.      * Writes an <code>int</code> value, which is
  172.      * comprised of four bytes, to the output stream.
  173.      * The byte values to be written, in the  order
  174.      * shown, are: 
  175.      * <p><pre><code> 
  176.      * (byte)(0xff & (v >> 24))
  177.      * (byte)(0xff & (v >> 16))
  178.      * (byte)(0xff & (v >>    8))
  179.      * (byte)(0xff & v)
  180.      * </code></pre><p>
  181.      * The bytes written by this method may be read
  182.      * by the <code>readInt</code> method of interface
  183.      * <code>DataInput</code> , which will then
  184.      * return an <code>int</code> equal to <code>v</code>.
  185.      *
  186.      * @param      v   the <code>int</code> value to be written.
  187.      * @exception  IOException  if an I/O error occurs.
  188.      * @since      JDK1.0
  189.      */
  190.     void writeInt(int v) throws IOException;
  191.  
  192.     /**
  193.      * Writes an <code>long</code> value, which is
  194.      * comprised of four bytes, to the output stream.
  195.      * The byte values to be written, in the  order
  196.      * shown, are: 
  197.      * <p><pre><code> 
  198.      * (byte)(0xff & (v >> 48))
  199.      * (byte)(0xff & (v >> 40))
  200.      * (byte)(0xff & (v >> 32))
  201.      * (byte)(0xff & (v >> 24))
  202.      * (byte)(0xff & (v >> 16))
  203.      * (byte)(0xff & (v >>  8))
  204.      * (byte)(0xff & v)
  205.      * </code></pre><p>
  206.      * The bytes written by this method may be 
  207.      * read by the <code>readLong</code> method
  208.      * of interface <code>DataInput</code> , which
  209.      * will then return a <code>long</code> equal
  210.      * to <code>v</code>.  
  211.      *
  212.      * @param      v   the <code>long</code> value to be written.
  213.      * @exception  IOException  if an I/O error occurs.
  214.      * @since      JDK1.0
  215.      */
  216.     void writeLong(long v) throws IOException;
  217.  
  218.     /**
  219.      * Writes a <code>float</code> value,
  220.      * which is comprised of four bytes, to the output stream. 
  221.      * It does this as if it first converts this
  222.      * <code>float</code> value to an <code>int</code>
  223.      * in exactly the manner of the <code>Float.floatToIntBits</code>
  224.      * method  and then writes the <code>int</code>
  225.      * value in exactly the manner of the  <code>writeInt</code>
  226.      * method.  The bytes written by this method
  227.      * may be read by the <code>readFloat</code>
  228.      * method of interface <code>DataInput</code>,
  229.      * which will then return a <code>float</code>
  230.      * equal to <code>v</code>.
  231.      *
  232.      * @param      v   the <code>float</code> value to be written.
  233.      * @exception  IOException  if an I/O error occurs.
  234.      * @since      JDK1.0
  235.      */
  236.     void writeFloat(float v) throws IOException;
  237.  
  238.     /**
  239.      * Writes a <code>double</code> value,
  240.      * which is comprised of eight bytes, to the output stream. 
  241.      * It does this as if it first converts this
  242.      * <code>double</code> value to a <code>long</code>
  243.      * in exactly the manner of the <code>Double.doubleToLongBits</code>
  244.      * method  and then writes the <code>long</code>
  245.      * value in exactly the manner of the  <code>writeLong</code>
  246.      * method. The bytes written by this method
  247.      * may be read by the <code>readDouble</code>
  248.      * method of interface <code>DataInput</code>,
  249.      * which will then return a <code>double</code>
  250.      * equal to <code>v</code>.
  251.      *
  252.      * @param      v   the <code>double</code> value to be written.
  253.      * @exception  IOException  if an I/O error occurs.
  254.      * @since      JDK1.0
  255.      */
  256.     void writeDouble(double v) throws IOException;
  257.  
  258.     /**
  259.      * Writes a string to the output stream.
  260.      * For every character in the string
  261.      * <code>s</code>,  taken in order, one byte
  262.      * is written to the output stream.  If 
  263.      * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>
  264.      * is thrown.<p>  If <code>s.length</code> 
  265.      * is zero, then no bytes are written. Otherwise,
  266.      * the character <code>s[0]</code> is written
  267.      * first, then <code>s[1]</code>, and so on;
  268.      * the last character written is <code>s[s.length-1]</code>.
  269.      * For each character, one byte is written,
  270.      * the low-order byte, in exactly the manner
  271.      * of the <code>writeByte</code> method . The
  272.      * high-order eight bits of each character 
  273.      * in the string are ignored.
  274.      *
  275.      * @param      s   the string of bytes to be written.
  276.      * @exception  IOException  if an I/O error occurs.
  277.      * @since      JDK1.0
  278.      */
  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.      * @exception  IOException  if an I/O error occurs.
  298.      * @since      JDK1.0
  299.      */
  300.     void writeChars(String s) throws IOException;
  301.  
  302.     /**
  303.      * Writes two bytes of length information 
  304.      * to the output stream, followed
  305.      * by the Java modified UTF representation 
  306.      * of  every character in the string <code>s</code>.
  307.      * If <code>s</code> is <code>null</code>,
  308.      * a <code>NullPointerException</code> is thrown.
  309.      * Each character in the string <code>s</code>
  310.      * is converted to a group of one, two, or 
  311.      * three bytes, depending on the value of the
  312.      * character.<p>  
  313.      * If a character <code>c</code>
  314.      * is in the range <code>\u0001</code> through
  315.      * <code>\u007f</code>, it is represented
  316.      * by one byte:<p> 
  317.      * <pre>(byte)c </pre>  <p>
  318.      * If a character <code>c</code> is <code>\u0000</code>
  319.      * or is in the range <code>\u0080</code>
  320.      * through <code>\u07ff</code>, then it is
  321.      * represented by two bytes, to be written 
  322.      * in the order shown:<p> <pre><code> 
  323.      * (byte)(0xc0 | (0x1f & (c >> 6))) 
  324.      * (byte)(0x80 | (0x3f & c)) 
  325.      *  </code></pre>  <p> If a character 
  326.      * <code>c</code> is in the range <code>\u0800</code>
  327.      * through <code>uffff</code>, then it is
  328.      * represented by three bytes, to be written
  329.      * in the order shown:<p> <pre><code> 
  330.      * (byte)(0xc0 | (0x0f & (c >> 12))) 
  331.      * (byte)(0x80 | (0x3f & (c >>  6)))
  332.      * (byte)(0x80 | (0x3f & c)) 
  333.      *  </code></pre>  <p> First,
  334.      * the total number of bytes needed to represent
  335.      * all the characters of <code>s</code> is 
  336.      * calculated. If this number is larger than
  337.      * <code>65535</code>, then a <code>UTFDataFormatError</code>
  338.      * is thrown. Otherwise, this length is written
  339.      * to the output stream in exactly the manner
  340.      * of the <code>writeShort</code> method;
  341.      * after this, the one-, two-, or three-byte
  342.      * representation of each character in the 
  343.      * string <code>s</code> is written.<p>  The
  344.      * bytes written by this method may be read
  345.      * by the <code>readUTF</code> method of interface
  346.      * <code>DataInput</code> , which will then
  347.      * return a <code>String</code> equal to <code>s</code>.
  348.      *
  349.      * @param      str   the string value to be written.
  350.      * @exception  IOException  if an I/O error occurs.
  351.      * @since   JDK1.0
  352.      */
  353.     void writeUTF(String str) throws IOException;
  354. }
  355.