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 26package javax.imageio.stream; 27 28import java.io.DataOutput; 29import 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 */ 52public 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/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 & (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} 663