1 /*

     2  * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.io;

    27 

    28 /**

    29  * The <code>DataOutput</code> interface provides

    30  * for converting data from any of the Java

    31  * primitive types to a series of bytes and

    32  * writing these bytes to a binary stream.

    33  * There is  also a facility for converting

    34  * a <code>String</code> into

    35  * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>

    36  * format and writing the resulting series

    37  * of bytes.

    38  * <p>

    39  * For all the methods in this interface that

    40  * write bytes, it is generally true that if

    41  * a byte cannot be written for any reason,

    42  * an <code>IOException</code> is thrown.

    43  *

    44  * @author  Frank Yellin

    45  * @see     java.io.DataInput

    46  * @see     java.io.DataOutputStream

    47  * @since   1.0

    48  */

    49 public

    50 interface DataOutput {

    51     /**

    52      * Writes to the output stream the eight

    53      * low-order bits of the argument <code>b</code>.

    54      * The 24 high-order  bits of <code>b</code>

    55      * are ignored.

    56      *

    57      * @param      b   the byte to be written.

    58      * @throws     IOException  if an I/O error occurs.

    59      */

    60     void write(int b) throws IOException;

    61 

    62     /**

    63      * Writes to the output stream all the bytes in array <code>b</code>.

    64      * If <code>b</code> is <code>null</code>,

    65      * a <code>NullPointerException</code> is thrown.

    66      * If <code>b.length</code> is zero, then

    67      * no bytes are written. Otherwise, the byte

    68      * <code>b[0]</code> is written first, then

    69      * <code>b[1]</code>, and so on; the last byte

    70      * written is <code>b[b.length-1]</code>.

    71      *

    72      * @param      b   the data.

    73      * @throws     IOException  if an I/O error occurs.

    74      */

    75     void write(byte b[]) throws IOException;

    76 

    77     /**

    78      * Writes <code>len</code> bytes from array

    79      * <code>b</code>, in order,  to

    80      * the output stream.  If <code>b</code>

    81      * is <code>null</code>, a <code>NullPointerException</code>

    82      * is thrown.  If <code>off</code> is negative,

    83      * or <code>len</code> is negative, or <code>off+len</code>

    84      * is greater than the length of the array

    85      * <code>b</code>, then an <code>IndexOutOfBoundsException</code>

    86      * is thrown.  If <code>len</code> is zero,

    87      * then no bytes are written. Otherwise, the

    88      * byte <code>b[off]</code> is written first,

    89      * then <code>b[off+1]</code>, and so on; the

    90      * last byte written is <code>b[off+len-1]</code>.

    91      *

    92      * @param      b     the data.

    93      * @param      off   the start offset in the data.

    94      * @param      len   the number of bytes to write.

    95      * @throws     IOException  if an I/O error occurs.

    96      */

    97     void write(byte b[], int off, int len) throws IOException;

    98 

    99     /**

   100      * Writes a <code>boolean</code> value to this output stream.

   101      * If the argument <code>v</code>

   102      * is <code>true</code>, the value <code>(byte)1</code>

   103      * is written; if <code>v</code> is <code>false</code>,

   104      * the  value <code>(byte)0</code> is written.

   105      * The byte written by this method may

   106      * be read by the <code>readBoolean</code>

   107      * method of interface <code>DataInput</code>,

   108      * which will then return a <code>boolean</code>

   109      * equal to <code>v</code>.

   110      *

   111      * @param      v   the boolean to be written.

   112      * @throws     IOException  if an I/O error occurs.

   113      */

   114     void writeBoolean(boolean v) throws IOException;

   115 

   116     /**

   117      * Writes to the output stream the eight low-

   118      * order bits of the argument <code>v</code>.

   119      * The 24 high-order bits of <code>v</code>

   120      * are ignored. (This means  that <code>writeByte</code>

   121      * does exactly the same thing as <code>write</code>

   122      * for an integer argument.) The byte written

   123      * by this method may be read by the <code>readByte</code>

   124      * method of interface <code>DataInput</code>,

   125      * which will then return a <code>byte</code>

   126      * equal to <code>(byte)v</code>.

   127      *

   128      * @param      v   the byte value to be written.

   129      * @throws     IOException  if an I/O error occurs.

   130      */

   131     void writeByte(int v) throws IOException;

   132 

   133     /**

   134      * Writes two bytes to the output

   135      * stream to represent the value of the argument.

   136      * The byte values to be written, in the  order

   137      * shown, are:

   138      * <pre>{@code

   139      * (byte)(0xff & (v >> 8))

   140      * (byte)(0xff & v)

   141      * }</pre> <p>

   142      * The bytes written by this method may be

   143      * read by the <code>readShort</code> method

   144      * of interface <code>DataInput</code> , which

   145      * will then return a <code>short</code> equal

   146      * to <code>(short)v</code>.

   147      *

   148      * @param      v   the <code>short</code> value to be written.

   149      * @throws     IOException  if an I/O error occurs.

   150      */

   151     void writeShort(int v) throws IOException;

   152 

   153     /**

   154      * Writes a <code>char</code> value, which

   155      * is comprised of two bytes, to the

   156      * output stream.

   157      * The byte values to be written, in the  order

   158      * shown, are:

   159      * <pre>{@code

   160      * (byte)(0xff & (v >> 8))

   161      * (byte)(0xff & v)

   162      * }</pre><p>

   163      * The bytes written by this method may be

   164      * read by the <code>readChar</code> method

   165      * of interface <code>DataInput</code> , which

   166      * will then return a <code>char</code> equal

   167      * to <code>(char)v</code>.

   168      *

   169      * @param      v   the <code>char</code> value to be written.

   170      * @throws     IOException  if an I/O error occurs.

   171      */

   172     void writeChar(int v) throws IOException;

   173 

   174     /**

   175      * Writes an <code>int</code> value, which is

   176      * comprised of four bytes, to the output stream.

   177      * The byte values to be written, in the  order

   178      * shown, are:

   179      * <pre>{@code

   180      * (byte)(0xff & (v >> 24))

   181      * (byte)(0xff & (v >> 16))

   182      * (byte)(0xff & (v >>  8))

   183      * (byte)(0xff & v)

   184      * }</pre><p>

   185      * The bytes written by this method may be read

   186      * by the <code>readInt</code> method of interface

   187      * <code>DataInput</code> , which will then

   188      * return an <code>int</code> equal to <code>v</code>.

   189      *

   190      * @param      v   the <code>int</code> value to be written.

   191      * @throws     IOException  if an I/O error occurs.

   192      */

   193     void writeInt(int v) throws IOException;

   194 

   195     /**

   196      * Writes a <code>long</code> value, which is

   197      * comprised of eight bytes, to the output stream.

   198      * The byte values to be written, in the  order

   199      * shown, are:

   200      * <pre>{@code

   201      * (byte)(0xff & (v >> 56))

   202      * (byte)(0xff & (v >> 48))

   203      * (byte)(0xff & (v >> 40))

   204      * (byte)(0xff & (v >> 32))

   205      * (byte)(0xff & (v >> 24))

   206      * (byte)(0xff & (v >> 16))

   207      * (byte)(0xff & (v >>  8))

   208      * (byte)(0xff & v)

   209      * }</pre><p>

   210      * The bytes written by this method may be

   211      * read by the <code>readLong</code> method

   212      * of interface <code>DataInput</code> , which

   213      * will then return a <code>long</code> equal

   214      * to <code>v</code>.

   215      *

   216      * @param      v   the <code>long</code> value to be written.

   217      * @throws     IOException  if an I/O error occurs.

   218      */

   219     void writeLong(long v) throws IOException;

   220 

   221     /**

   222      * Writes a <code>float</code> value,

   223      * which is comprised of four bytes, to the output stream.

   224      * It does this as if it first converts this

   225      * <code>float</code> value to an <code>int</code>

   226      * in exactly the manner of the <code>Float.floatToIntBits</code>

   227      * method  and then writes the <code>int</code>

   228      * value in exactly the manner of the  <code>writeInt</code>

   229      * method.  The bytes written by this method

   230      * may be read by the <code>readFloat</code>

   231      * method of interface <code>DataInput</code>,

   232      * which will then return a <code>float</code>

   233      * equal to <code>v</code>.

   234      *

   235      * @param      v   the <code>float</code> value to be written.

   236      * @throws     IOException  if an I/O error occurs.

   237      */

   238     void writeFloat(float v) throws IOException;

   239 

   240     /**

   241      * Writes a <code>double</code> value,

   242      * which is comprised of eight bytes, to the output stream.

   243      * It does this as if it first converts this

   244      * <code>double</code> value to a <code>long</code>

   245      * in exactly the manner of the <code>Double.doubleToLongBits</code>

   246      * method  and then writes the <code>long</code>

   247      * value in exactly the manner of the  <code>writeLong</code>

   248      * method. The bytes written by this method

   249      * may be read by the <code>readDouble</code>

   250      * method of interface <code>DataInput</code>,

   251      * which will then return a <code>double</code>

   252      * equal to <code>v</code>.

   253      *

   254      * @param      v   the <code>double</code> value to be written.

   255      * @throws     IOException  if an I/O error occurs.

   256      */

   257     void writeDouble(double v) throws IOException;

   258 

   259     /**

   260      * Writes a string to the output stream.

   261      * For every character in the string

   262      * <code>s</code>,  taken in order, one byte

   263      * is written to the output stream.  If

   264      * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>

   265      * is thrown.<p>  If <code>s.length</code>

   266      * is zero, then no bytes are written. Otherwise,

   267      * the character <code>s[0]</code> is written

   268      * first, then <code>s[1]</code>, and so on;

   269      * the last character written is <code>s[s.length-1]</code>.

   270      * For each character, one byte is written,

   271      * the low-order byte, in exactly the manner

   272      * of the <code>writeByte</code> method . The

   273      * high-order eight bits of each character

   274      * in the string are ignored.

   275      *

   276      * @param      s   the string of bytes to be written.

   277      * @throws     IOException  if an I/O error occurs.

   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      * @throws     IOException  if an I/O error occurs.

   298      */

   299     void writeChars(String s) throws IOException;

   300 

   301     /**

   302      * Writes two bytes of length information

   303      * to the output stream, followed

   304      * by the

   305      * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>

   306      * representation

   307      * of  every character in the string <code>s</code>.

   308      * If <code>s</code> is <code>null</code>,

   309      * a <code>NullPointerException</code> is thrown.

   310      * Each character in the string <code>s</code>

   311      * is converted to a group of one, two, or

   312      * three bytes, depending on the value of the

   313      * character.<p>

   314      * If a character <code>c</code>

   315      * is in the range <code>&#92;u0001</code> through

   316      * <code>&#92;u007f</code>, it is represented

   317      * by one byte:

   318      * <pre>(byte)c </pre>  <p>

   319      * If a character <code>c</code> is <code>&#92;u0000</code>

   320      * or is in the range <code>&#92;u0080</code>

   321      * through <code>&#92;u07ff</code>, then it is

   322      * represented by two bytes, to be written

   323      * in the order shown: <pre>{@code

   324      * (byte)(0xc0 | (0x1f & (c >> 6)))

   325      * (byte)(0x80 | (0x3f & c))

   326      * }</pre> <p> If a character

   327      * <code>c</code> is in the range <code>&#92;u0800</code>

   328      * through <code>uffff</code>, then it is

   329      * represented by three bytes, to be written

   330      * in the order shown: <pre>{@code

   331      * (byte)(0xe0 | (0x0f & (c >> 12)))

   332      * (byte)(0x80 | (0x3f & (c >>  6)))

   333      * (byte)(0x80 | (0x3f & c))

   334      * }</pre>  <p> First,

   335      * the total number of bytes needed to represent

   336      * all the characters of <code>s</code> is

   337      * calculated. If this number is larger than

   338      * <code>65535</code>, then a <code>UTFDataFormatException</code>

   339      * is thrown. Otherwise, this length is written

   340      * to the output stream in exactly the manner

   341      * of the <code>writeShort</code> method;

   342      * after this, the one-, two-, or three-byte

   343      * representation of each character in the

   344      * string <code>s</code> is written.<p>  The

   345      * bytes written by this method may be read

   346      * by the <code>readUTF</code> method of interface

   347      * <code>DataInput</code> , which will then

   348      * return a <code>String</code> equal to <code>s</code>.

   349      *

   350      * @param      s   the string value to be written.

   351      * @throws     IOException  if an I/O error occurs.

   352      */

   353     void writeUTF(String s) throws IOException;

   354 }