1 /*
2 * Copyright (c) 2000, 2018, 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 >> 8) & 0xff)
162 * (byte)(v & 0xff)
163 * </pre>
164 *
165 * Otherwise, the bytes written will be:
166 *
167 * <pre>
168 * (byte)(v & 0xff)
169 * (byte)((v >> 8) & 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 >> 24) & 0xff)
203 * (byte)((v >> 16) & 0xff)
204 * (byte)((v >> 8) & 0xff)
205 * (byte)(v & 0xff)
206 * </pre>
207 *
208 * Otheriwse, the bytes written will be:
209 *
210 * <pre>
211 * (byte)(v & 0xff)
212 * (byte)((v >> 8) & 0xff)
213 * (byte)((v >> 16) & 0xff)
214 * (byte)((v >> 24) & 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 >> 56) & 0xff)
236 * (byte)((v >> 48) & 0xff)
237 * (byte)((v >> 40) & 0xff)
238 * (byte)((v >> 32) & 0xff)
239 * (byte)((v >> 24) & 0xff)
240 * (byte)((v >> 16) & 0xff)
241 * (byte)((v >> 8) & 0xff)
242 * (byte)(v & 0xff)
243 * </pre>
244 *
245 * Otherwise, the bytes written will be:
246 *
247 * <pre>
248 * (byte)(v & 0xff)
249 * (byte)((v >> 8) & 0xff)
250 * (byte)((v >> 16) & 0xff)
251 * (byte)((v >> 24) & 0xff)
252 * (byte)((v >> 32) & 0xff)
253 * (byte)((v >> 40) & 0xff)
254 * (byte)((v >> 48) & 0xff)
255 * (byte)((v >> 56) & 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.base/java/io/DataInput.html#modified-utf-8">
371 * modifiedUTF-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 & (c >> 6)))
393 * (byte)(0x80 | (0x3f & 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 & (c >> 12)))
402 * (byte)(0x80 | (0x3f & (c >> 6)))
403 * (byte)(0x80 | (0x3f & 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 }
--- EOF ---