1 /*
   2  * Copyright (c) 2000, 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 javax.imageio.stream;
  27 
  28 import java.io.DataOutput;
  29 import java.io.IOException;
  30 
  31 /**
  32  * A seekable output stream interface for use by
  33  * {@code ImageWriter}s.  Various output destinations, such as
  34  * {@code OutputStream}s and {@code File}s, as well as
  35  * future fast I/O destinations may be "wrapped" by a suitable
  36  * implementation of this interface for use by the Image I/O API.
  37  *
  38  * <p> Unlike a standard {@code OutputStream}, ImageOutputStream
  39  * extends its counterpart, {@code ImageInputStream}.  Thus it is
  40  * possible to read from the stream as it is being written.  The same
  41  * seek and flush positions apply to both reading and writing, although
  42  * the semantics for dealing with a non-zero bit offset before a byte-aligned
  43  * write are necessarily different from the semantics for dealing with
  44  * a non-zero bit offset before a byte-aligned read.  When reading bytes,
  45  * any bit offset is set to 0 before the read; when writing bytes, a
  46  * non-zero bit offset causes the remaining bits in the byte to be written
  47  * as 0s. The byte-aligned write then starts at the next byte position.
  48  *
  49  * @see ImageInputStream
  50  *
  51  */
  52 public interface ImageOutputStream extends ImageInputStream, DataOutput {
  53 
  54     /**
  55      * Writes a single byte to the stream at the current position.
  56      * The 24 high-order bits of {@code b} are ignored.
  57      *
  58      * <p> If the bit offset within the stream is non-zero, the
  59      * remainder of the current byte is padded with 0s
  60      * and written out first.  The bit offset will be 0 after the
  61      * write.  Implementers can use the
  62      * {@link ImageOutputStreamImpl#flushBits flushBits}
  63      * method of {@link ImageOutputStreamImpl ImageOutputStreamImpl}
  64      * to guarantee this.
  65      *
  66      * @param b an {@code int} whose lower 8 bits are to be
  67      * written.
  68      *
  69      * @exception IOException if an I/O error occurs.
  70      */
  71     void write(int b) throws IOException;
  72 
  73     /**
  74      * Writes a sequence of bytes to the stream at the current
  75      * position.  If {@code b.length} is 0, nothing is written.
  76      * The byte {@code b[0]} is written first, then the byte
  77      * {@code b[1]}, and so on.
  78      *
  79      * <p> If the bit offset within the stream is non-zero, the
  80      * remainder of the current byte is padded with 0s
  81      * and written out first.  The bit offset will be 0 after the
  82      * write.
  83      *
  84      * @param b an array of {@code byte}s to be written.
  85      *
  86      * @exception NullPointerException if {@code b} is
  87      * {@code null}.
  88      * @exception IOException if an I/O error occurs.
  89      */
  90     void write(byte b[]) throws IOException;
  91 
  92     /**
  93      * Writes a sequence of bytes to the stream at the current
  94      * position.  If {@code len} is 0, nothing is written.
  95      * The byte {@code b[off]} is written first, then the byte
  96      * {@code b[off + 1]}, and so on.
  97      *
  98      * <p> If the bit offset within the stream is non-zero, the
  99      * remainder of the current byte is padded with 0s
 100      * and written out first.  The bit offset will be 0 after the
 101      * write.  Implementers can use the
 102      * {@link ImageOutputStreamImpl#flushBits flushBits}
 103      * method of {@link ImageOutputStreamImpl ImageOutputStreamImpl}
 104      * to guarantee this.
 105      *
 106      * @param b an array of {@code byte}s to be written.
 107      * @param off the start offset in the data.
 108      * @param len the number of {@code byte}s to write.
 109      *
 110      * @exception IndexOutOfBoundsException if {@code off} is
 111      * negative, {@code len} is negative, or {@code off + len}
 112      * is greater than {@code b.length}.
 113      * @exception NullPointerException if {@code b} is
 114      * {@code null}.
 115      * @exception IOException if an I/O error occurs.
 116      */
 117     void write(byte b[], int off, int len) throws IOException;
 118 
 119     /**
 120      * Writes a {@code boolean} value to the stream.  If
 121      * {@code v} is true, the value {@code (byte)1} is
 122      * written; if {@code v} is false, the value
 123      * {@code (byte)0} is written.
 124      *
 125      * <p> If the bit offset within the stream is non-zero, the
 126      * remainder of the current byte is padded with 0s
 127      * and written out first.  The bit offset will be 0 after the
 128      * write.
 129      *
 130      * @param v the {@code boolean} to be written.
 131      *
 132      * @exception IOException if an I/O error occurs.
 133      */
 134     void writeBoolean(boolean v) throws IOException;
 135 
 136     /**
 137      * Writes the 8 low-order bits of {@code v} to the
 138      * stream. The 24 high-order bits of {@code v} are ignored.
 139      * (This means that {@code writeByte} does exactly the same
 140      * thing as {@code write} for an integer argument.)
 141      *
 142      * <p> If the bit offset within the stream is non-zero, the
 143      * remainder of the current byte is padded with 0s
 144      * and written out first.  The bit offset will be 0 after the
 145      * write.
 146      *
 147      * @param v an {@code int} containing the byte value to be
 148      * written.
 149      *
 150      * @exception IOException if an I/O error occurs.
 151      */
 152     void writeByte(int v) throws IOException;
 153 
 154     /**
 155      * Writes the 16 low-order bits of {@code v} to the
 156      * stream. The 16 high-order bits of {@code v} are ignored.
 157      * If the stream uses network byte order, the bytes written, in
 158      * order, will be:
 159      *
 160      * <pre>
 161      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 162      * (byte)(v &amp; 0xff)
 163      * </pre>
 164      *
 165      * Otherwise, the bytes written will be:
 166      *
 167      * <pre>
 168      * (byte)(v &amp; 0xff)
 169      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 170      * </pre>
 171      *
 172      * <p> If the bit offset within the stream is non-zero, the
 173      * remainder of the current byte is padded with 0s
 174      * and written out first.  The bit offset will be 0 after the
 175      * write.
 176      *
 177      * @param v an {@code int} containing the short value to be
 178      * written.
 179      *
 180      * @exception IOException if an I/O error occurs.
 181      */
 182     void writeShort(int v) throws IOException;
 183 
 184     /**
 185      * This method is a synonym for {@link #writeShort writeShort}.
 186      *
 187      * @param v an {@code int} containing the char (unsigned
 188      * short) value to be written.
 189      *
 190      * @exception IOException if an I/O error occurs.
 191      *
 192      * @see #writeShort(int)
 193      */
 194     void writeChar(int v) throws IOException;
 195 
 196     /**
 197      * Writes the 32 bits of {@code v} to the stream.  If the
 198      * stream uses network byte order, the bytes written, in order,
 199      * will be:
 200      *
 201      * <pre>
 202      * (byte)((v &gt;&gt; 24) &amp; 0xff)
 203      * (byte)((v &gt;&gt; 16) &amp; 0xff)
 204      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 205      * (byte)(v &amp; 0xff)
 206      * </pre>
 207      *
 208      * Otheriwse, the bytes written will be:
 209      *
 210      * <pre>
 211      * (byte)(v &amp; 0xff)
 212      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 213      * (byte)((v &gt;&gt; 16) &amp; 0xff)
 214      * (byte)((v &gt;&gt; 24) &amp; 0xff)
 215      * </pre>
 216      *
 217      * <p> If the bit offset within the stream is non-zero, the
 218      * remainder of the current byte is padded with 0s
 219      * and written out first.  The bit offset will be 0 after the
 220      * write.
 221      *
 222      * @param v an {@code int} containing the value to be
 223      * written.
 224      *
 225      * @exception IOException if an I/O error occurs.
 226      */
 227     void writeInt(int v) throws IOException;
 228 
 229     /**
 230      * Writes the 64 bits of {@code v} to the stream.  If the
 231      * stream uses network byte order, the bytes written, in order,
 232      * will be:
 233      *
 234      * <pre>
 235      * (byte)((v &gt;&gt; 56) &amp; 0xff)
 236      * (byte)((v &gt;&gt; 48) &amp; 0xff)
 237      * (byte)((v &gt;&gt; 40) &amp; 0xff)
 238      * (byte)((v &gt;&gt; 32) &amp; 0xff)
 239      * (byte)((v &gt;&gt; 24) &amp; 0xff)
 240      * (byte)((v &gt;&gt; 16) &amp; 0xff)
 241      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 242      * (byte)(v &amp; 0xff)
 243      * </pre>
 244      *
 245      * Otherwise, the bytes written will be:
 246      *
 247      * <pre>
 248      * (byte)(v &amp; 0xff)
 249      * (byte)((v &gt;&gt; 8) &amp; 0xff)
 250      * (byte)((v &gt;&gt; 16) &amp; 0xff)
 251      * (byte)((v &gt;&gt; 24) &amp; 0xff)
 252      * (byte)((v &gt;&gt; 32) &amp; 0xff)
 253      * (byte)((v &gt;&gt; 40) &amp; 0xff)
 254      * (byte)((v &gt;&gt; 48) &amp; 0xff)
 255      * (byte)((v &gt;&gt; 56) &amp; 0xff)
 256      * </pre>
 257      *
 258      * <p> If the bit offset within the stream is non-zero, the
 259      * remainder of the current byte is padded with 0s
 260      * and written out first.  The bit offset will be 0 after the
 261      * write.
 262      *
 263      * @param v a {@code long} containing the value to be
 264      * written.
 265      *
 266      * @exception IOException if an I/O error occurs.
 267      */
 268     void writeLong(long v) throws IOException;
 269 
 270     /**
 271      * Writes a {@code float} value, which is comprised of four
 272      * bytes, to the output stream. It does this as if it first
 273      * converts this {@code float} value to an {@code int}
 274      * in exactly the manner of the {@code Float.floatToIntBits}
 275      * method and then writes the int value in exactly the manner of
 276      * the {@code writeInt} method.
 277      *
 278      * <p> If the bit offset within the stream is non-zero, the
 279      * remainder of the current byte is padded with 0s
 280      * and written out first.  The bit offset will be 0 after the
 281      * write.
 282      *
 283      * @param v a {@code float} containing the value to be
 284      * written.
 285      *
 286      * @exception IOException if an I/O error occurs.
 287      */
 288     void writeFloat(float v) throws IOException;
 289 
 290     /**
 291      * Writes a {@code double} value, which is comprised of four
 292      * bytes, to the output stream. It does this as if it first
 293      * converts this {@code double} value to a {@code long}
 294      * in exactly the manner of the
 295      * {@code Double.doubleToLongBits} method and then writes the
 296      * long value in exactly the manner of the {@code writeLong}
 297      * method.
 298      *
 299      * <p> If the bit offset within the stream is non-zero, the
 300      * remainder of the current byte is padded with 0s
 301      * and written out first.  The bit offset will be 0 after the
 302      * write.
 303      *
 304      * @param v a {@code double} containing the value to be
 305      * written.
 306      *
 307      * @exception IOException if an I/O error occurs.
 308      */
 309     void writeDouble(double v) throws IOException;
 310 
 311     /**
 312      * Writes a string to the output stream. For every character in
 313      * the string {@code s}, taken in order, one byte is written
 314      * to the output stream. If {@code s} is {@code null}, a
 315      * {@code NullPointerException} is thrown.
 316      *
 317      * <p> If {@code s.length} is zero, then no bytes are
 318      * written. Otherwise, the character {@code s[0]} is written
 319      * first, then {@code s[1]}, and so on; the last character
 320      * written is {@code s[s.length-1]}. For each character, one
 321      * byte is written, the low-order byte, in exactly the manner of
 322      * the {@code writeByte} method. The high-order eight bits of
 323      * each character in the string are ignored.
 324      *
 325      * <p> If the bit offset within the stream is non-zero, the
 326      * remainder of the current byte is padded with 0s
 327      * and written out first.  The bit offset will be 0 after the
 328      * write.
 329      *
 330      * @param s a {@code String} containing the value to be
 331      * written.
 332      *
 333      * @exception NullPointerException if {@code s} is
 334      * {@code null}.
 335      * @exception IOException if an I/O error occurs.
 336      */
 337     void writeBytes(String s) throws IOException;
 338 
 339     /**
 340      * Writes a string to the output stream. For every character in
 341      * the string {@code s}, taken in order, two bytes are
 342      * written to the output stream, ordered according to the current
 343      * byte order setting.  If network byte order is being used, the
 344      * high-order byte is written first; the order is reversed
 345      * otherwise.  If {@code s} is {@code null}, a
 346      * {@code NullPointerException} is thrown.
 347      *
 348      * <p> If {@code s.length} is zero, then no bytes are
 349      * written. Otherwise, the character {@code s[0]} is written
 350      * first, then {@code s[1]}, and so on; the last character
 351      * written is {@code s[s.length-1]}.
 352      *
 353      * <p> If the bit offset within the stream is non-zero, the
 354      * remainder of the current byte is padded with 0s
 355      * and written out first.  The bit offset will be 0 after the
 356      * write.
 357      *
 358      * @param s a {@code String} containing the value to be
 359      * written.
 360      *
 361      * @exception NullPointerException if {@code s} is
 362      * {@code null}.
 363      * @exception IOException if an I/O error occurs.
 364      */
 365     void writeChars(String s) throws IOException;
 366 
 367     /**
 368      * Writes two bytes of length information to the output stream in
 369      * network byte order, followed by the
 370      * <a href="../../../java/io/DataInput.html#modified-utf-8">modified
 371      * UTF-8</a>
 372      * representation of every character in the string {@code s}.
 373      * If {@code s} is {@code null}, a
 374      * {@code NullPointerException} is thrown.  Each character in
 375      * the string {@code s} is converted to a group of one, two,
 376      * or three bytes, depending on the value of the character.
 377      *
 378      * <p> If a character {@code c} is in the range
 379      * <code>\u0001</code> through <code>\u007f</code>, it is
 380      * represented by one byte:
 381      *
 382      * <pre>
 383      * (byte)c
 384      * </pre>
 385      *
 386      * <p> If a character {@code c} is <code>\u0000</code> or
 387      * is in the range <code>\u0080</code> through
 388      * <code>\u07ff</code>, then it is represented by two bytes,
 389      * to be written in the order shown:
 390      *
 391      * <pre><code>
 392      * (byte)(0xc0 | (0x1f &amp; (c &gt;&gt; 6)))
 393      * (byte)(0x80 | (0x3f &amp; c))
 394      * </code></pre>
 395      *
 396      * <p> If a character {@code c} is in the range
 397      * <code>\u0800</code> through {@code uffff}, then it is
 398      * represented by three bytes, to be written in the order shown:
 399      *
 400      * <pre><code>
 401      * (byte)(0xe0 | (0x0f &amp; (c &gt;&gt; 12)))
 402      * (byte)(0x80 | (0x3f &amp; (c &gt;&gt; 6)))
 403      * (byte)(0x80 | (0x3f &amp; c))
 404      * </code></pre>
 405      *
 406      * <p> First, the total number of bytes needed to represent all
 407      * the characters of {@code s} is calculated. If this number
 408      * is larger than {@code 65535}, then a
 409      * {@code UTFDataFormatException} is thrown. Otherwise, this
 410      * length is written to the output stream in exactly the manner of
 411      * the {@code writeShort} method; after this, the one-, two-,
 412      * or three-byte representation of each character in the string
 413      * {@code s} is written.
 414      *
 415      * <p> The current byte order setting is ignored.
 416      *
 417      * <p> If the bit offset within the stream is non-zero, the
 418      * remainder of the current byte is padded with 0s
 419      * and written out first.  The bit offset will be 0 after the
 420      * write.
 421      *
 422      * <p><strong>Note:</strong> This method should not be used in
 423      * the  implementation of image formats that use standard UTF-8,
 424      * because  the modified UTF-8 used here is incompatible with
 425      * standard UTF-8.
 426      *
 427      * @param s a {@code String} containing the value to be
 428      * written.
 429      *
 430      * @exception NullPointerException if {@code s} is
 431      * {@code null}.
 432      * @exception java.io.UTFDataFormatException if the modified UTF-8
 433      * representation of {@code s} requires more than 65536 bytes.
 434      * @exception IOException if an I/O error occurs.
 435      */
 436     void writeUTF(String s) throws IOException;
 437 
 438     /**
 439      * Writes a sequence of shorts to the stream at the current
 440      * position.  If {@code len} is 0, nothing is written.
 441      * The short {@code s[off]} is written first, then the short
 442      * {@code s[off + 1]}, and so on.  The byte order of the
 443      * stream is used to determine the order in which the individual
 444      * bytes are written.
 445      *
 446      * <p> If the bit offset within the stream is non-zero, the
 447      * remainder of the current byte is padded with 0s
 448      * and written out first.  The bit offset will be 0 after the
 449      * write.
 450      *
 451      * @param s an array of {@code short}s to be written.
 452      * @param off the start offset in the data.
 453      * @param len the number of {@code short}s to write.
 454      *
 455      * @exception IndexOutOfBoundsException if {@code off} is
 456      * negative, {@code len} is negative, or {@code off + len}
 457      * is greater than {@code s.length}.
 458      * @exception NullPointerException if {@code s} is
 459      * {@code null}.
 460      * @exception IOException if an I/O error occurs.
 461      */
 462     void writeShorts(short[] s, int off, int len) throws IOException;
 463 
 464     /**
 465      * Writes a sequence of chars to the stream at the current
 466      * position.  If {@code len} is 0, nothing is written.
 467      * The char {@code c[off]} is written first, then the char
 468      * {@code c[off + 1]}, and so on.  The byte order of the
 469      * stream is used to determine the order in which the individual
 470      * bytes are written.
 471      *
 472      * <p> If the bit offset within the stream is non-zero, the
 473      * remainder of the current byte is padded with 0s
 474      * and written out first.  The bit offset will be 0 after the
 475      * write.
 476      *
 477      * @param c an array of {@code char}s to be written.
 478      * @param off the start offset in the data.
 479      * @param len the number of {@code char}s to write.
 480      *
 481      * @exception IndexOutOfBoundsException if {@code off} is
 482      * negative, {@code len} is negative, or {@code off + len}
 483      * is greater than {@code c.length}.
 484      * @exception NullPointerException if {@code c} is
 485      * {@code null}.
 486      * @exception IOException if an I/O error occurs.
 487      */
 488     void writeChars(char[] c, int off, int len) throws IOException;
 489 
 490     /**
 491      * Writes a sequence of ints to the stream at the current
 492      * position.  If {@code len} is 0, nothing is written.
 493      * The int {@code i[off]} is written first, then the int
 494      * {@code i[off + 1]}, and so on.  The byte order of the
 495      * stream is used to determine the order in which the individual
 496      * bytes are written.
 497      *
 498      * <p> If the bit offset within the stream is non-zero, the
 499      * remainder of the current byte is padded with 0s
 500      * and written out first.  The bit offset will be 0 after the
 501      * write.
 502      *
 503      * @param i an array of {@code int}s to be written.
 504      * @param off the start offset in the data.
 505      * @param len the number of {@code int}s to write.
 506      *
 507      * @exception IndexOutOfBoundsException if {@code off} is
 508      * negative, {@code len} is negative, or {@code off + len}
 509      * is greater than {@code i.length}.
 510      * @exception NullPointerException if {@code i} is
 511      * {@code null}.
 512      * @exception IOException if an I/O error occurs.
 513      */
 514     void writeInts(int[] i, int off, int len) throws IOException;
 515 
 516     /**
 517      * Writes a sequence of longs to the stream at the current
 518      * position.  If {@code len} is 0, nothing is written.
 519      * The long {@code l[off]} is written first, then the long
 520      * {@code l[off + 1]}, and so on.  The byte order of the
 521      * stream is used to determine the order in which the individual
 522      * bytes are written.
 523      *
 524      * <p> If the bit offset within the stream is non-zero, the
 525      * remainder of the current byte is padded with 0s
 526      * and written out first.  The bit offset will be 0 after the
 527      * write.
 528      *
 529      * @param l an array of {@code long}s to be written.
 530      * @param off the start offset in the data.
 531      * @param len the number of {@code long}s to write.
 532      *
 533      * @exception IndexOutOfBoundsException if {@code off} is
 534      * negative, {@code len} is negative, or {@code off + len}
 535      * is greater than {@code l.length}.
 536      * @exception NullPointerException if {@code l} is
 537      * {@code null}.
 538      * @exception IOException if an I/O error occurs.
 539      */
 540     void writeLongs(long[] l, int off, int len) throws IOException;
 541 
 542     /**
 543      * Writes a sequence of floats to the stream at the current
 544      * position.  If {@code len} is 0, nothing is written.
 545      * The float {@code f[off]} is written first, then the float
 546      * {@code f[off + 1]}, and so on.  The byte order of the
 547      * stream is used to determine the order in which the individual
 548      * bytes are written.
 549      *
 550      * <p> If the bit offset within the stream is non-zero, the
 551      * remainder of the current byte is padded with 0s
 552      * and written out first.  The bit offset will be 0 after the
 553      * write.
 554      *
 555      * @param f an array of {@code float}s to be written.
 556      * @param off the start offset in the data.
 557      * @param len the number of {@code float}s to write.
 558      *
 559      * @exception IndexOutOfBoundsException if {@code off} is
 560      * negative, {@code len} is negative, or {@code off + len}
 561      * is greater than {@code f.length}.
 562      * @exception NullPointerException if {@code f} is
 563      * {@code null}.
 564      * @exception IOException if an I/O error occurs.
 565      */
 566     void writeFloats(float[] f, int off, int len) throws IOException;
 567 
 568     /**
 569      * Writes a sequence of doubles to the stream at the current
 570      * position.  If {@code len} is 0, nothing is written.
 571      * The double {@code d[off]} is written first, then the double
 572      * {@code d[off + 1]}, and so on.  The byte order of the
 573      * stream is used to determine the order in which the individual
 574      * bytes are written.
 575      *
 576      * <p> If the bit offset within the stream is non-zero, the
 577      * remainder of the current byte is padded with 0s
 578      * and written out first.  The bit offset will be 0 after the
 579      * write.
 580      *
 581      * @param d an array of {@code doubles}s to be written.
 582      * @param off the start offset in the data.
 583      * @param len the number of {@code double}s to write.
 584      *
 585      * @exception IndexOutOfBoundsException if {@code off} is
 586      * negative, {@code len} is negative, or {@code off + len}
 587      * is greater than {@code d.length}.
 588      * @exception NullPointerException if {@code d} is
 589      * {@code null}.
 590      * @exception IOException if an I/O error occurs.
 591      */
 592     void writeDoubles(double[] d, int off, int len) throws IOException;
 593 
 594     /**
 595      * Writes a single bit, given by the least significant bit of the
 596      * argument, to the stream at the current bit offset within the
 597      * current byte position.  The upper 31 bits of the argument are
 598      * ignored.  The given bit replaces the previous bit at that
 599      * position.  The bit offset is advanced by one and reduced modulo
 600      * 8.
 601      *
 602      * <p> If any bits of a particular byte have never been set
 603      * at the time the byte is flushed to the destination, those
 604      * bits will be set to 0 automatically.
 605      *
 606      * @param bit an {@code int} whose least significant bit
 607      * is to be written to the stream.
 608      *
 609      * @exception IOException if an I/O error occurs.
 610      */
 611     void writeBit(int bit) throws IOException;
 612 
 613     /**
 614      * Writes a sequence of bits, given by the {@code numBits}
 615      * least significant bits of the {@code bits} argument in
 616      * left-to-right order, to the stream at the current bit offset
 617      * within the current byte position.  The upper {@code 64 - numBits}
 618      * bits of the argument are ignored.  The bit
 619      * offset is advanced by {@code numBits} and reduced modulo
 620      * 8.  Note that a bit offset of 0 always indicates the
 621      * most-significant bit of the byte, and bytes of bits are written
 622      * out in sequence as they are encountered.  Thus bit writes are
 623      * always effectively in network byte order.  The actual stream
 624      * byte order setting is ignored.
 625      *
 626      * <p> Bit data may be accumulated in memory indefinitely, until
 627      * {@code flushBefore} is called.  At that time, all bit data
 628      * prior to the flushed position will be written.
 629      *
 630      * <p> If any bits of a particular byte have never been set
 631      * at the time the byte is flushed to the destination, those
 632      * bits will be set to 0 automatically.
 633      *
 634      * @param bits a {@code long} containing the bits to be
 635      * written, starting with the bit in position {@code numBits - 1}
 636      * down to the least significant bit.
 637      *
 638      * @param numBits an {@code int} between 0 and 64, inclusive.
 639      *
 640      * @exception IllegalArgumentException if {@code numBits} is
 641      * not between 0 and 64, inclusive.
 642      * @exception IOException if an I/O error occurs.
 643      */
 644     void writeBits(long bits, int numBits) throws IOException;
 645 
 646     /**
 647      * Flushes all data prior to the given position to the underlying
 648      * destination, such as an {@code OutputStream} or
 649      * {@code File}.  Attempting to seek to the flushed portion
 650      * of the stream will result in an
 651      * {@code IndexOutOfBoundsException}.
 652      *
 653      * @param pos a {@code long} containing the length of the
 654      * stream prefix that may be flushed to the destination.
 655      *
 656      * @exception IndexOutOfBoundsException if {@code pos} lies
 657      * in the flushed portion of the stream or past the current stream
 658      * position.
 659      * @exception IOException if an I/O error occurs.
 660      */
 661     void flushBefore(long pos) throws IOException;
 662 }