rt/emul/compact/src/main/java/java/io/DataOutput.java
changeset 772 d382dacfd73f
parent 601 5198affdb915
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/rt/emul/compact/src/main/java/java/io/DataOutput.java	Tue Feb 26 16:54:16 2013 +0100
     1.3 @@ -0,0 +1,354 @@
     1.4 +/*
     1.5 + * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
     1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
     1.7 + *
     1.8 + * This code is free software; you can redistribute it and/or modify it
     1.9 + * under the terms of the GNU General Public License version 2 only, as
    1.10 + * published by the Free Software Foundation.  Oracle designates this
    1.11 + * particular file as subject to the "Classpath" exception as provided
    1.12 + * by Oracle in the LICENSE file that accompanied this code.
    1.13 + *
    1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
    1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    1.16 + * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    1.17 + * version 2 for more details (a copy is included in the LICENSE file that
    1.18 + * accompanied this code).
    1.19 + *
    1.20 + * You should have received a copy of the GNU General Public License version
    1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
    1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
    1.23 + *
    1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
    1.25 + * or visit www.oracle.com if you need additional information or have any
    1.26 + * questions.
    1.27 + */
    1.28 +
    1.29 +package java.io;
    1.30 +
    1.31 +/**
    1.32 + * The <code>DataOutput</code> interface provides
    1.33 + * for converting data from any of the Java
    1.34 + * primitive types to a series of bytes and
    1.35 + * writing these bytes to a binary stream.
    1.36 + * There is  also a facility for converting
    1.37 + * a <code>String</code> into
    1.38 + * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
    1.39 + * format and writing the resulting series
    1.40 + * of bytes.
    1.41 + * <p>
    1.42 + * For all the methods in this interface that
    1.43 + * write bytes, it is generally true that if
    1.44 + * a byte cannot be written for any reason,
    1.45 + * an <code>IOException</code> is thrown.
    1.46 + *
    1.47 + * @author  Frank Yellin
    1.48 + * @see     java.io.DataInput
    1.49 + * @see     java.io.DataOutputStream
    1.50 + * @since   JDK1.0
    1.51 + */
    1.52 +public
    1.53 +interface DataOutput {
    1.54 +    /**
    1.55 +     * Writes to the output stream the eight
    1.56 +     * low-order bits of the argument <code>b</code>.
    1.57 +     * The 24 high-order  bits of <code>b</code>
    1.58 +     * are ignored.
    1.59 +     *
    1.60 +     * @param      b   the byte to be written.
    1.61 +     * @throws     IOException  if an I/O error occurs.
    1.62 +     */
    1.63 +    void write(int b) throws IOException;
    1.64 +
    1.65 +    /**
    1.66 +     * Writes to the output stream all the bytes in array <code>b</code>.
    1.67 +     * If <code>b</code> is <code>null</code>,
    1.68 +     * a <code>NullPointerException</code> is thrown.
    1.69 +     * If <code>b.length</code> is zero, then
    1.70 +     * no bytes are written. Otherwise, the byte
    1.71 +     * <code>b[0]</code> is written first, then
    1.72 +     * <code>b[1]</code>, and so on; the last byte
    1.73 +     * written is <code>b[b.length-1]</code>.
    1.74 +     *
    1.75 +     * @param      b   the data.
    1.76 +     * @throws     IOException  if an I/O error occurs.
    1.77 +     */
    1.78 +    void write(byte b[]) throws IOException;
    1.79 +
    1.80 +    /**
    1.81 +     * Writes <code>len</code> bytes from array
    1.82 +     * <code>b</code>, in order,  to
    1.83 +     * the output stream.  If <code>b</code>
    1.84 +     * is <code>null</code>, a <code>NullPointerException</code>
    1.85 +     * is thrown.  If <code>off</code> is negative,
    1.86 +     * or <code>len</code> is negative, or <code>off+len</code>
    1.87 +     * is greater than the length of the array
    1.88 +     * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
    1.89 +     * is thrown.  If <code>len</code> is zero,
    1.90 +     * then no bytes are written. Otherwise, the
    1.91 +     * byte <code>b[off]</code> is written first,
    1.92 +     * then <code>b[off+1]</code>, and so on; the
    1.93 +     * last byte written is <code>b[off+len-1]</code>.
    1.94 +     *
    1.95 +     * @param      b     the data.
    1.96 +     * @param      off   the start offset in the data.
    1.97 +     * @param      len   the number of bytes to write.
    1.98 +     * @throws     IOException  if an I/O error occurs.
    1.99 +     */
   1.100 +    void write(byte b[], int off, int len) throws IOException;
   1.101 +
   1.102 +    /**
   1.103 +     * Writes a <code>boolean</code> value to this output stream.
   1.104 +     * If the argument <code>v</code>
   1.105 +     * is <code>true</code>, the value <code>(byte)1</code>
   1.106 +     * is written; if <code>v</code> is <code>false</code>,
   1.107 +     * the  value <code>(byte)0</code> is written.
   1.108 +     * The byte written by this method may
   1.109 +     * be read by the <code>readBoolean</code>
   1.110 +     * method of interface <code>DataInput</code>,
   1.111 +     * which will then return a <code>boolean</code>
   1.112 +     * equal to <code>v</code>.
   1.113 +     *
   1.114 +     * @param      v   the boolean to be written.
   1.115 +     * @throws     IOException  if an I/O error occurs.
   1.116 +     */
   1.117 +    void writeBoolean(boolean v) throws IOException;
   1.118 +
   1.119 +    /**
   1.120 +     * Writes to the output stream the eight low-
   1.121 +     * order bits of the argument <code>v</code>.
   1.122 +     * The 24 high-order bits of <code>v</code>
   1.123 +     * are ignored. (This means  that <code>writeByte</code>
   1.124 +     * does exactly the same thing as <code>write</code>
   1.125 +     * for an integer argument.) The byte written
   1.126 +     * by this method may be read by the <code>readByte</code>
   1.127 +     * method of interface <code>DataInput</code>,
   1.128 +     * which will then return a <code>byte</code>
   1.129 +     * equal to <code>(byte)v</code>.
   1.130 +     *
   1.131 +     * @param      v   the byte value to be written.
   1.132 +     * @throws     IOException  if an I/O error occurs.
   1.133 +     */
   1.134 +    void writeByte(int v) throws IOException;
   1.135 +
   1.136 +    /**
   1.137 +     * Writes two bytes to the output
   1.138 +     * stream to represent the value of the argument.
   1.139 +     * The byte values to be written, in the  order
   1.140 +     * shown, are: <p>
   1.141 +     * <pre><code>
   1.142 +     * (byte)(0xff &amp; (v &gt;&gt; 8))
   1.143 +     * (byte)(0xff &amp; v)
   1.144 +     * </code> </pre> <p>
   1.145 +     * The bytes written by this method may be
   1.146 +     * read by the <code>readShort</code> method
   1.147 +     * of interface <code>DataInput</code> , which
   1.148 +     * will then return a <code>short</code> equal
   1.149 +     * to <code>(short)v</code>.
   1.150 +     *
   1.151 +     * @param      v   the <code>short</code> value to be written.
   1.152 +     * @throws     IOException  if an I/O error occurs.
   1.153 +     */
   1.154 +    void writeShort(int v) throws IOException;
   1.155 +
   1.156 +    /**
   1.157 +     * Writes a <code>char</code> value, which
   1.158 +     * is comprised of two bytes, to the
   1.159 +     * output stream.
   1.160 +     * The byte values to be written, in the  order
   1.161 +     * shown, are:
   1.162 +     * <p><pre><code>
   1.163 +     * (byte)(0xff &amp; (v &gt;&gt; 8))
   1.164 +     * (byte)(0xff &amp; v)
   1.165 +     * </code></pre><p>
   1.166 +     * The bytes written by this method may be
   1.167 +     * read by the <code>readChar</code> method
   1.168 +     * of interface <code>DataInput</code> , which
   1.169 +     * will then return a <code>char</code> equal
   1.170 +     * to <code>(char)v</code>.
   1.171 +     *
   1.172 +     * @param      v   the <code>char</code> value to be written.
   1.173 +     * @throws     IOException  if an I/O error occurs.
   1.174 +     */
   1.175 +    void writeChar(int v) throws IOException;
   1.176 +
   1.177 +    /**
   1.178 +     * Writes an <code>int</code> value, which is
   1.179 +     * comprised of four bytes, to the output stream.
   1.180 +     * The byte values to be written, in the  order
   1.181 +     * shown, are:
   1.182 +     * <p><pre><code>
   1.183 +     * (byte)(0xff &amp; (v &gt;&gt; 24))
   1.184 +     * (byte)(0xff &amp; (v &gt;&gt; 16))
   1.185 +     * (byte)(0xff &amp; (v &gt;&gt; &#32; &#32;8))
   1.186 +     * (byte)(0xff &amp; v)
   1.187 +     * </code></pre><p>
   1.188 +     * The bytes written by this method may be read
   1.189 +     * by the <code>readInt</code> method of interface
   1.190 +     * <code>DataInput</code> , which will then
   1.191 +     * return an <code>int</code> equal to <code>v</code>.
   1.192 +     *
   1.193 +     * @param      v   the <code>int</code> value to be written.
   1.194 +     * @throws     IOException  if an I/O error occurs.
   1.195 +     */
   1.196 +    void writeInt(int v) throws IOException;
   1.197 +
   1.198 +    /**
   1.199 +     * Writes a <code>long</code> value, which is
   1.200 +     * comprised of eight bytes, to the output stream.
   1.201 +     * The byte values to be written, in the  order
   1.202 +     * shown, are:
   1.203 +     * <p><pre><code>
   1.204 +     * (byte)(0xff &amp; (v &gt;&gt; 56))
   1.205 +     * (byte)(0xff &amp; (v &gt;&gt; 48))
   1.206 +     * (byte)(0xff &amp; (v &gt;&gt; 40))
   1.207 +     * (byte)(0xff &amp; (v &gt;&gt; 32))
   1.208 +     * (byte)(0xff &amp; (v &gt;&gt; 24))
   1.209 +     * (byte)(0xff &amp; (v &gt;&gt; 16))
   1.210 +     * (byte)(0xff &amp; (v &gt;&gt;  8))
   1.211 +     * (byte)(0xff &amp; v)
   1.212 +     * </code></pre><p>
   1.213 +     * The bytes written by this method may be
   1.214 +     * read by the <code>readLong</code> method
   1.215 +     * of interface <code>DataInput</code> , which
   1.216 +     * will then return a <code>long</code> equal
   1.217 +     * to <code>v</code>.
   1.218 +     *
   1.219 +     * @param      v   the <code>long</code> value to be written.
   1.220 +     * @throws     IOException  if an I/O error occurs.
   1.221 +     */
   1.222 +    void writeLong(long v) throws IOException;
   1.223 +
   1.224 +    /**
   1.225 +     * Writes a <code>float</code> value,
   1.226 +     * which is comprised of four bytes, to the output stream.
   1.227 +     * It does this as if it first converts this
   1.228 +     * <code>float</code> value to an <code>int</code>
   1.229 +     * in exactly the manner of the <code>Float.floatToIntBits</code>
   1.230 +     * method  and then writes the <code>int</code>
   1.231 +     * value in exactly the manner of the  <code>writeInt</code>
   1.232 +     * method.  The bytes written by this method
   1.233 +     * may be read by the <code>readFloat</code>
   1.234 +     * method of interface <code>DataInput</code>,
   1.235 +     * which will then return a <code>float</code>
   1.236 +     * equal to <code>v</code>.
   1.237 +     *
   1.238 +     * @param      v   the <code>float</code> value to be written.
   1.239 +     * @throws     IOException  if an I/O error occurs.
   1.240 +     */
   1.241 +    void writeFloat(float v) throws IOException;
   1.242 +
   1.243 +    /**
   1.244 +     * Writes a <code>double</code> value,
   1.245 +     * which is comprised of eight bytes, to the output stream.
   1.246 +     * It does this as if it first converts this
   1.247 +     * <code>double</code> value to a <code>long</code>
   1.248 +     * in exactly the manner of the <code>Double.doubleToLongBits</code>
   1.249 +     * method  and then writes the <code>long</code>
   1.250 +     * value in exactly the manner of the  <code>writeLong</code>
   1.251 +     * method. The bytes written by this method
   1.252 +     * may be read by the <code>readDouble</code>
   1.253 +     * method of interface <code>DataInput</code>,
   1.254 +     * which will then return a <code>double</code>
   1.255 +     * equal to <code>v</code>.
   1.256 +     *
   1.257 +     * @param      v   the <code>double</code> value to be written.
   1.258 +     * @throws     IOException  if an I/O error occurs.
   1.259 +     */
   1.260 +    void writeDouble(double v) throws IOException;
   1.261 +
   1.262 +    /**
   1.263 +     * Writes a string to the output stream.
   1.264 +     * For every character in the string
   1.265 +     * <code>s</code>,  taken in order, one byte
   1.266 +     * is written to the output stream.  If
   1.267 +     * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>
   1.268 +     * is thrown.<p>  If <code>s.length</code>
   1.269 +     * is zero, then no bytes are written. Otherwise,
   1.270 +     * the character <code>s[0]</code> is written
   1.271 +     * first, then <code>s[1]</code>, and so on;
   1.272 +     * the last character written is <code>s[s.length-1]</code>.
   1.273 +     * For each character, one byte is written,
   1.274 +     * the low-order byte, in exactly the manner
   1.275 +     * of the <code>writeByte</code> method . The
   1.276 +     * high-order eight bits of each character
   1.277 +     * in the string are ignored.
   1.278 +     *
   1.279 +     * @param      s   the string of bytes to be written.
   1.280 +     * @throws     IOException  if an I/O error occurs.
   1.281 +     */
   1.282 +    void writeBytes(String s) throws IOException;
   1.283 +
   1.284 +    /**
   1.285 +     * Writes every character in the string <code>s</code>,
   1.286 +     * to the output stream, in order,
   1.287 +     * two bytes per character. If <code>s</code>
   1.288 +     * is <code>null</code>, a <code>NullPointerException</code>
   1.289 +     * is thrown.  If <code>s.length</code>
   1.290 +     * is zero, then no characters are written.
   1.291 +     * Otherwise, the character <code>s[0]</code>
   1.292 +     * is written first, then <code>s[1]</code>,
   1.293 +     * and so on; the last character written is
   1.294 +     * <code>s[s.length-1]</code>. For each character,
   1.295 +     * two bytes are actually written, high-order
   1.296 +     * byte first, in exactly the manner of the
   1.297 +     * <code>writeChar</code> method.
   1.298 +     *
   1.299 +     * @param      s   the string value to be written.
   1.300 +     * @throws     IOException  if an I/O error occurs.
   1.301 +     */
   1.302 +    void writeChars(String s) throws IOException;
   1.303 +
   1.304 +    /**
   1.305 +     * Writes two bytes of length information
   1.306 +     * to the output stream, followed
   1.307 +     * by the
   1.308 +     * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
   1.309 +     * representation
   1.310 +     * of  every character in the string <code>s</code>.
   1.311 +     * If <code>s</code> is <code>null</code>,
   1.312 +     * a <code>NullPointerException</code> is thrown.
   1.313 +     * Each character in the string <code>s</code>
   1.314 +     * is converted to a group of one, two, or
   1.315 +     * three bytes, depending on the value of the
   1.316 +     * character.<p>
   1.317 +     * If a character <code>c</code>
   1.318 +     * is in the range <code>&#92;u0001</code> through
   1.319 +     * <code>&#92;u007f</code>, it is represented
   1.320 +     * by one byte:<p>
   1.321 +     * <pre>(byte)c </pre>  <p>
   1.322 +     * If a character <code>c</code> is <code>&#92;u0000</code>
   1.323 +     * or is in the range <code>&#92;u0080</code>
   1.324 +     * through <code>&#92;u07ff</code>, then it is
   1.325 +     * represented by two bytes, to be written
   1.326 +     * in the order shown:<p> <pre><code>
   1.327 +     * (byte)(0xc0 | (0x1f &amp; (c &gt;&gt; 6)))
   1.328 +     * (byte)(0x80 | (0x3f &amp; c))
   1.329 +     *  </code></pre>  <p> If a character
   1.330 +     * <code>c</code> is in the range <code>&#92;u0800</code>
   1.331 +     * through <code>uffff</code>, then it is
   1.332 +     * represented by three bytes, to be written
   1.333 +     * in the order shown:<p> <pre><code>
   1.334 +     * (byte)(0xe0 | (0x0f &amp; (c &gt;&gt; 12)))
   1.335 +     * (byte)(0x80 | (0x3f &amp; (c &gt;&gt;  6)))
   1.336 +     * (byte)(0x80 | (0x3f &amp; c))
   1.337 +     *  </code></pre>  <p> First,
   1.338 +     * the total number of bytes needed to represent
   1.339 +     * all the characters of <code>s</code> is
   1.340 +     * calculated. If this number is larger than
   1.341 +     * <code>65535</code>, then a <code>UTFDataFormatException</code>
   1.342 +     * is thrown. Otherwise, this length is written
   1.343 +     * to the output stream in exactly the manner
   1.344 +     * of the <code>writeShort</code> method;
   1.345 +     * after this, the one-, two-, or three-byte
   1.346 +     * representation of each character in the
   1.347 +     * string <code>s</code> is written.<p>  The
   1.348 +     * bytes written by this method may be read
   1.349 +     * by the <code>readUTF</code> method of interface
   1.350 +     * <code>DataInput</code> , which will then
   1.351 +     * return a <code>String</code> equal to <code>s</code>.
   1.352 +     *
   1.353 +     * @param      s   the string value to be written.
   1.354 +     * @throws     IOException  if an I/O error occurs.
   1.355 +     */
   1.356 +    void writeUTF(String s) throws IOException;
   1.357 +}