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 & (v >> 8))
1.143 + * (byte)(0xff & 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 & (v >> 8))
1.164 + * (byte)(0xff & 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 & (v >> 24))
1.184 + * (byte)(0xff & (v >> 16))
1.185 + * (byte)(0xff & (v >>    8))
1.186 + * (byte)(0xff & 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 & (v >> 56))
1.205 + * (byte)(0xff & (v >> 48))
1.206 + * (byte)(0xff & (v >> 40))
1.207 + * (byte)(0xff & (v >> 32))
1.208 + * (byte)(0xff & (v >> 24))
1.209 + * (byte)(0xff & (v >> 16))
1.210 + * (byte)(0xff & (v >> 8))
1.211 + * (byte)(0xff & 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>\u0001</code> through
1.319 + * <code>\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>\u0000</code>
1.323 + * or is in the range <code>\u0080</code>
1.324 + * through <code>\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 & (c >> 6)))
1.328 + * (byte)(0x80 | (0x3f & c))
1.329 + * </code></pre> <p> If a character
1.330 + * <code>c</code> is in the range <code>\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 & (c >> 12)))
1.335 + * (byte)(0x80 | (0x3f & (c >> 6)))
1.336 + * (byte)(0x80 | (0x3f & 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 +}