View Javadoc
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</code>s.  Various output destinations, such as
34   * <code>OutputStream</code>s and <code>File</code>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</code>, ImageOutputStream
39   * extends its counterpart, <code>ImageInputStream</code>.  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</code> 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</code> 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</code> is 0, nothing is written.
76       * The byte <code>b[0]</code> is written first, then the byte
77       * <code>b[1]</code>, 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</code>s to be written.
85       *
86       * @exception NullPointerException if <code>b</code> is
87       * <code>null</code>.
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</code> is 0, nothing is written.
95       * The byte <code>b[off]</code> is written first, then the byte
96       * <code>b[off + 1]</code>, 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</code>s to be written.
107      * @param off the start offset in the data.
108      * @param len the number of <code>byte</code>s to write.
109      *
110      * @exception IndexOutOfBoundsException if <code>off</code> is
111      * negative, <code>len</code> is negative, or <code>off +
112      * len</code> is greater than <code>b.length</code>.
113      * @exception NullPointerException if <code>b</code> is
114      * <code>null</code>.
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</code> value to the stream.  If
121      * <code>v</code> is true, the value <code>(byte)1</code> is
122      * written; if <code>v</code> is false, the value
123      * <code>(byte)0</code> 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</code> 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</code> to the
138      * stream. The 24 high-order bits of <code>v</code> are ignored.
139      * (This means that <code>writeByte</code> does exactly the same
140      * thing as <code>write</code> 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</code> 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</code> to the
156      * stream. The 16 high-order bits of <code>v</code> 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</code> 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</code> 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</code> 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</code> 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</code> 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</code> 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</code> value, which is comprised of four
272      * bytes, to the output stream. It does this as if it first
273      * converts this <code>float</code> value to an <code>int</code>
274      * in exactly the manner of the <code>Float.floatToIntBits</code>
275      * method and then writes the int value in exactly the manner of
276      * the <code>writeInt</code> 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</code> 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</code> value, which is comprised of four
292      * bytes, to the output stream. It does this as if it first
293      * converts this <code>double</code> value to an <code>long</code>
294      * in exactly the manner of the
295      * <code>Double.doubleToLongBits</code> method and then writes the
296      * long value in exactly the manner of the <code>writeLong</code>
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</code> 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</code>, taken in order, one byte is written
314      * to the output stream. If <code>s</code> is <code>null</code>, a
315      * <code>NullPointerException</code> is thrown.
316      *
317      * <p> If <code>s.length</code> is zero, then no bytes are
318      * written. Otherwise, the character <code>s[0]</code> is written
319      * first, then <code>s[1]</code>, and so on; the last character
320      * written is <code>s[s.length-1]</code>. For each character, one
321      * byte is written, the low-order byte, in exactly the manner of
322      * the <code>writeByte</code> 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</code> containing the value to be
331      * written.
332      *
333      * @exception NullPointerException if <code>s</code> is
334      * <code>null</code>.
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</code>, 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</code> is <code>null</code>, a
346      * <code>NullPointerException</code> is thrown.
347      *
348      * <p> If <code>s.length</code> is zero, then no bytes are
349      * written. Otherwise, the character <code>s[0]</code> is written
350      * first, then <code>s[1]</code>, and so on; the last character
351      * written is <code>s[s.length-1]</code>.
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</code> containing the value to be
359      * written.
360      *
361      * @exception NullPointerException if <code>s</code> is
362      * <code>null</code>.
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</code>.
373      * If <code>s</code> is <code>null</code>, a
374      * <code>NullPointerException</code> is thrown.  Each character in
375      * the string <code>s</code> 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</code> is in the range
379      * <code>&#92;u0001</code> through <code>&#92;u007f</code>, it is
380      * represented by one byte:
381      *
382      * <p><pre>
383      * (byte)c
384      * </pre>
385      *
386      * <p> If a character <code>c</code> is <code>&#92;u0000</code> or
387      * is in the range <code>&#92;u0080</code> through
388      * <code>&#92;u07ff</code>, then it is represented by two bytes,
389      * to be written in the order shown:
390      *
391      * <p> <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</code> is in the range
397      * <code>&#92;u0800</code> through <code>uffff</code>, then it is
398      * represented by three bytes, to be written in the order shown:
399      *
400      * <p> <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</code> is calculated. If this number
408      * is larger than <code>65535</code>, then a
409      * <code>UTFDataFormatException</code> is thrown. Otherwise, this
410      * length is written to the output stream in exactly the manner of
411      * the <code>writeShort</code> method; after this, the one-, two-,
412      * or three-byte representation of each character in the string
413      * <code>s</code> 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</code> containing the value to be
428      * written.
429      *
430      * @exception NullPointerException if <code>s</code> is
431      * <code>null</code>.
432      * @exception java.io.UTFDataFormatException if the modified UTF-8
433      * representation of <code>s</code> 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</code> is 0, nothing is written.
441      * The short <code>s[off]</code> is written first, then the short
442      * <code>s[off + 1]</code>, 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</code>s to be written.
452      * @param off the start offset in the data.
453      * @param len the number of <code>short</code>s to write.
454      *
455      * @exception IndexOutOfBoundsException if <code>off</code> is
456      * negative, <code>len</code> is negative, or <code>off +
457      * len</code> is greater than <code>s.length</code>.
458      * @exception NullPointerException if <code>s</code> is
459      * <code>null</code>.
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</code> is 0, nothing is written.
467      * The char <code>c[off]</code> is written first, then the char
468      * <code>c[off + 1]</code>, 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</code>s to be written.
478      * @param off the start offset in the data.
479      * @param len the number of <code>char</code>s to write.
480      *
481      * @exception IndexOutOfBoundsException if <code>off</code> is
482      * negative, <code>len</code> is negative, or <code>off +
483      * len</code> is greater than <code>c.length</code>.
484      * @exception NullPointerException if <code>c</code> is
485      * <code>null</code>.
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</code> is 0, nothing is written.
493      * The int <code>i[off]</code> is written first, then the int
494      * <code>i[off + 1]</code>, 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</code>s to be written.
504      * @param off the start offset in the data.
505      * @param len the number of <code>int</code>s to write.
506      *
507      * @exception IndexOutOfBoundsException if <code>off</code> is
508      * negative, <code>len</code> is negative, or <code>off +
509      * len</code> is greater than <code>i.length</code>.
510      * @exception NullPointerException if <code>i</code> is
511      * <code>null</code>.
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</code> is 0, nothing is written.
519      * The long <code>l[off]</code> is written first, then the long
520      * <code>l[off + 1]</code>, 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</code>s to be written.
530      * @param off the start offset in the data.
531      * @param len the number of <code>long</code>s to write.
532      *
533      * @exception IndexOutOfBoundsException if <code>off</code> is
534      * negative, <code>len</code> is negative, or <code>off +
535      * len</code> is greater than <code>l.length</code>.
536      * @exception NullPointerException if <code>l</code> is
537      * <code>null</code>.
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</code> is 0, nothing is written.
545      * The float <code>f[off]</code> is written first, then the float
546      * <code>f[off + 1]</code>, 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</code>s to be written.
556      * @param off the start offset in the data.
557      * @param len the number of <code>float</code>s to write.
558      *
559      * @exception IndexOutOfBoundsException if <code>off</code> is
560      * negative, <code>len</code> is negative, or <code>off +
561      * len</code> is greater than <code>f.length</code>.
562      * @exception NullPointerException if <code>f</code> is
563      * <code>null</code>.
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</code> is 0, nothing is written.
571      * The double <code>d[off]</code> is written first, then the double
572      * <code>d[off + 1]</code>, 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</code>s to be written.
582      * @param off the start offset in the data.
583      * @param len the number of <code>double</code>s to write.
584      *
585      * @exception IndexOutOfBoundsException if <code>off</code> is
586      * negative, <code>len</code> is negative, or <code>off +
587      * len</code> is greater than <code>d.length</code>.
588      * @exception NullPointerException if <code>d</code> is
589      * <code>null</code>.
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</code> 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</code>
615      * least significant bits of the <code>bits</code> 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 -
618      * numBits</code> bits of the argument are ignored.  The bit
619      * offset is advanced by <code>numBits</code> 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</code> 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</code> containing the bits to be
635      * written, starting with the bit in position <code>numBits -
636      * 1</code> down to the least significant bit.
637      *
638      * @param numBits an <code>int</code> between 0 and 64, inclusive.
639      *
640      * @exception IllegalArgumentException if <code>numBits</code> 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</code> or
649      * <code>File</code>.  Attempting to seek to the flushed portion
650      * of the stream will result in an
651      * <code>IndexOutOfBoundsException</code>.
652      *
653      * @param pos a <code>long</code> containing the length of the
654      * stream prefix that may be flushed to the destination.
655      *
656      * @exception IndexOutOfBoundsException if <code>pos</code> 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 }