1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 /** 18 * @author Rustem V. Rafikov 19 * @version $Revision: 1.2 $ 20 */ 21 22 package javax.imageio.stream; 23 24 import java.io.DataInput; 25 import java.io.IOException; 26 import java.nio.ByteOrder; 27 28 /** 29 * The ImageInputStream represents input stream interface that is used by 30 * ImageReaders. 31 * 32 * @since Android 1.0 33 */ 34 public interface ImageInputStream extends DataInput { 35 36 /** 37 * Sets the specified byte order for reading of data values from this 38 * stream. 39 * 40 * @param byteOrder 41 * the byte order. 42 */ 43 void setByteOrder(ByteOrder byteOrder); 44 45 /** 46 * Gets the byte order. 47 * 48 * @return the byte order. 49 */ 50 ByteOrder getByteOrder(); 51 52 /** 53 * Reads a byte from the stream. 54 * 55 * @return the byte of the stream, or -1 for EOF indicating. 56 * @throws IOException 57 * if an I/O exception has occurred. 58 */ 59 int read() throws IOException; 60 61 /** 62 * Reads number of bytes which is equal to the specified array's length and 63 * stores a result to this array. 64 * 65 * @param b 66 * the byte array. 67 * @return the number of read bytes, or -1 indicated EOF. 68 * @throws IOException 69 * if an I/O exception has occurred. 70 */ 71 int read(byte[] b) throws IOException; 72 73 /** 74 * Reads the number of bytes specified by len parameter from the stream and 75 * stores a result to the specified array with the specified offset. 76 * 77 * @param b 78 * the byte array. 79 * @param off 80 * the offset. 81 * @param len 82 * the number of bytes to be read. 83 * @return the number of read bytes, or -1 indicated EOF. 84 * @throws IOException 85 * if an I/O exception has occurred. 86 */ 87 int read(byte[] b, int off, int len) throws IOException; 88 89 /** 90 * Reads the number of bytes specified by len parameter from the stream, and 91 * modifies the specified IIOByteBuffer with the byte array, offset, and 92 * length. 93 * 94 * @param buf 95 * the IIOByteBuffer. 96 * @param len 97 * the number of bytes to be read. 98 * @throws IOException 99 * if an I/O exception has occurred. 100 */ 101 void readBytes(IIOByteBuffer buf, int len) throws IOException; 102 103 /** 104 * Reads a byte from the stream and returns a boolean true value if it is 105 * non zero, false if it is zero. 106 * 107 * @return the boolean value for read byte. 108 * @throws IOException 109 * if an I/O exception has occurred. 110 */ 111 boolean readBoolean() throws IOException; 112 113 /** 114 * Reads a byte from the stream and returns its value as signed byte. 115 * 116 * @return the signed byte value for read byte. 117 * @throws IOException 118 * if an I/O exception has occurred. 119 */ 120 byte readByte() throws IOException; 121 122 /** 123 * Reads a byte from the stream and returns its value as an integer. 124 * 125 * @return the unsigned byte value for read byte as an integer. 126 * @throws IOException 127 * if an I/O exception has occurred. 128 */ 129 int readUnsignedByte() throws IOException; 130 131 /** 132 * Reads 2 bytes from the stream, and returns the result as a short. 133 * 134 * @return the signed short value from the stream. 135 * @throws IOException 136 * if an I/O exception has occurred. 137 */ 138 short readShort() throws IOException; 139 140 /** 141 * Reads 2 bytes from the stream and returns its value as an unsigned short. 142 * 143 * @return a unsigned short value coded in an integer. 144 * @throws IOException 145 * if an I/O exception has occurred. 146 */ 147 int readUnsignedShort() throws IOException; 148 149 /** 150 * Reads 2 bytes from the stream and returns their unsigned char value. 151 * 152 * @return the unsigned char value. 153 * @throws IOException 154 * if an I/O exception has occurred. 155 */ 156 char readChar() throws IOException; 157 158 /** 159 * Reads 4 bytes from the stream, and returns the result as an integer. 160 * 161 * @return the signed integer value from the stream. 162 * @throws IOException 163 * if an I/O exception has occurred. 164 */ 165 int readInt() throws IOException; 166 167 /** 168 * Reads 4 bytes from the stream and returns its value as long. 169 * 170 * @return the unsigned integer value as long. 171 * @throws IOException 172 * if an I/O exception has occurred. 173 */ 174 long readUnsignedInt() throws IOException; 175 176 /** 177 * Reads 8 bytes from the stream, and returns the result as a long. 178 * 179 * @return the long value from the stream. 180 * @throws IOException 181 * if an I/O exception has occurred. 182 */ 183 long readLong() throws IOException; 184 185 /** 186 * Reads 4 bytes from the stream, and returns the result as a float. 187 * 188 * @return the float value from the stream. 189 * @throws IOException 190 * if an I/O exception has occurred. 191 */ 192 float readFloat() throws IOException; 193 194 /** 195 * Reads 8 bytes from the stream, and returns the result as a double. 196 * 197 * @return the double value from the stream. 198 * @throws IOException 199 * if an I/O exception has occurred. 200 */ 201 double readDouble() throws IOException; 202 203 /** 204 * Reads a line from the stream. 205 * 206 * @return the string contained the line from the stream. 207 * @throws IOException 208 * if an I/O exception has occurred. 209 */ 210 String readLine() throws IOException; 211 212 /** 213 * Reads bytes from the stream in a string that has been encoded in a 214 * modified UTF-8 format. 215 * 216 * @return the string read from stream and modified UTF-8 format. 217 * @throws IOException 218 * if an I/O exception has occurred. 219 */ 220 String readUTF() throws IOException; 221 222 /** 223 * Reads the specified number of bytes from the stream, and stores the 224 * result into the specified array starting at the specified index offset. 225 * 226 * @param b 227 * the byte array. 228 * @param off 229 * the offset. 230 * @param len 231 * the number of bytes to be read. 232 * @throws IOException 233 * if an I/O exception has occurred. 234 */ 235 void readFully(byte[] b, int off, int len) throws IOException; 236 237 /** 238 * Reads number of bytes from the stream which is equal to the specified 239 * array's length, and stores them into this array. 240 * 241 * @param b 242 * the byte array. 243 * @throws IOException 244 * if an I/O exception has occurred. 245 */ 246 void readFully(byte[] b) throws IOException; 247 248 /** 249 * Reads the specified number of shorts from the stream, and stores the 250 * result into the specified array starting at the specified index offset. 251 * 252 * @param s 253 * the short array. 254 * @param off 255 * the offset. 256 * @param len 257 * the number of shorts to be read. 258 * @throws IOException 259 * if an I/O exception has occurred. 260 */ 261 void readFully(short[] s, int off, int len) throws IOException; 262 263 /** 264 * Reads the specified number of chars from the stream, and stores the 265 * result into the specified array starting at the specified index offset. 266 * 267 * @param c 268 * the char array. 269 * @param off 270 * the offset. 271 * @param len 272 * the number of chars to be read. 273 * @throws IOException 274 * if an I/O exception has occurred. 275 */ 276 void readFully(char[] c, int off, int len) throws IOException; 277 278 /** 279 * Reads the specified number of integer from the stream, and stores the 280 * result into the specified array starting at the specified index offset. 281 * 282 * @param i 283 * the integer array. 284 * @param off 285 * the offset. 286 * @param len 287 * the number of integer to be read. 288 * @throws IOException 289 * if an I/O exception has occurred. 290 */ 291 void readFully(int[] i, int off, int len) throws IOException; 292 293 /** 294 * Reads the specified number of longs from the stream, and stores the 295 * result into the specified array starting at the specified index offset. 296 * 297 * @param l 298 * the long array. 299 * @param off 300 * the offset. 301 * @param len 302 * the number of longs to be read. 303 * @throws IOException 304 * if an I/O exception has occurred. 305 */ 306 void readFully(long[] l, int off, int len) throws IOException; 307 308 /** 309 * Reads the specified number of floats from the stream, and stores the 310 * result into the specified array starting at the specified index offset. 311 * 312 * @param f 313 * the float array. 314 * @param off 315 * the offset. 316 * @param len 317 * the number of floats to be read. 318 * @throws IOException 319 * if an I/O exception has occurred. 320 */ 321 void readFully(float[] f, int off, int len) throws IOException; 322 323 /** 324 * Reads the specified number of doubles from the stream, and stores the 325 * result into the specified array starting at the specified index offset. 326 * 327 * @param d 328 * the double array. 329 * @param off 330 * the offset. 331 * @param len 332 * the number of doubles to be read. 333 * @throws IOException 334 * if an I/O exception has occurred. 335 */ 336 void readFully(double[] d, int off, int len) throws IOException; 337 338 /** 339 * Gets the stream position. 340 * 341 * @return the stream position. 342 * @throws IOException 343 * if an I/O exception has occurred. 344 */ 345 long getStreamPosition() throws IOException; 346 347 /** 348 * Gets the bit offset. 349 * 350 * @return the bit offset. 351 * @throws IOException 352 * if an I/O exception has occurred. 353 */ 354 int getBitOffset() throws IOException; 355 356 /** 357 * Sets the bit offset to an integer between 0 and 7. 358 * 359 * @param bitOffset 360 * the bit offset. 361 * @throws IOException 362 * if an I/O exception has occurred. 363 */ 364 void setBitOffset(int bitOffset) throws IOException; 365 366 /** 367 * Reads a bit from the stream and returns the value 0 or 1. 368 * 369 * @return the value of single bit: 0 or 1. 370 * @throws IOException 371 * if an I/O exception has occurred. 372 */ 373 int readBit() throws IOException; 374 375 /** 376 * Read the specified number of bits and returns their values as long. 377 * 378 * @param numBits 379 * the number of bits to be read. 380 * @return the bit string as a long. 381 * @throws IOException 382 * if an I/O exception has occurred. 383 */ 384 long readBits(int numBits) throws IOException; 385 386 /** 387 * Returns the length of the stream. 388 * 389 * @return the length of the stream, or -1 if unknown. 390 * @throws IOException 391 * if an I/O exception has occurred. 392 */ 393 long length() throws IOException; 394 395 /** 396 * Skips the specified number of bytes by moving stream position. 397 * 398 * @param n 399 * the number of bytes. 400 * @return the actual skipped number of bytes. 401 * @throws IOException 402 * if an I/O exception has occurred. 403 */ 404 int skipBytes(int n) throws IOException; 405 406 /** 407 * Skips the specified number of bytes by moving stream position. 408 * 409 * @param n 410 * the number of bytes. 411 * @return the actual skipped number of bytes. 412 * @throws IOException 413 * if an I/O exception has occurred. 414 */ 415 long skipBytes(long n) throws IOException; 416 417 /** 418 * Sets the current stream position to the specified location. 419 * 420 * @param pos 421 * a file pointer position. 422 * @throws IOException 423 * if an I/O exception has occurred. 424 */ 425 void seek(long pos) throws IOException; 426 427 /** 428 * Marks a position in the stream to be returned to by a subsequent call to 429 * reset. 430 */ 431 void mark(); 432 433 /** 434 * Returns the file pointer to its previous position. 435 * 436 * @throws IOException 437 * if an I/O exception has occurred. 438 */ 439 void reset() throws IOException; 440 441 /** 442 * Flushes the initial position in this stream prior to the specified stream 443 * position. 444 * 445 * @param pos 446 * the position. 447 * @throws IOException 448 * if an I/O exception has occurred. 449 */ 450 void flushBefore(long pos) throws IOException; 451 452 /** 453 * Flushes the initial position in this stream prior to the current stream 454 * position. 455 * 456 * @throws IOException 457 * if an I/O exception has occurred. 458 */ 459 void flush() throws IOException; 460 461 /** 462 * Gets the flushed position. 463 * 464 * @return the flushed position. 465 */ 466 long getFlushedPosition(); 467 468 /** 469 * Returns true if this ImageInputStream caches data in order to allow 470 * seeking backwards. 471 * 472 * @return true, if this ImageInputStream caches data in order to allow 473 * seeking backwards, false otherwise. 474 */ 475 boolean isCached(); 476 477 /** 478 * Returns true if this ImageInputStream caches data in order to allow 479 * seeking backwards, and keeps it in memory. 480 * 481 * @return true, if this ImageInputStream caches data in order to allow 482 * seeking backwards, and keeps it in memory. 483 */ 484 boolean isCachedMemory(); 485 486 /** 487 * Returns true if this ImageInputStream caches data in order to allow 488 * seeking backwards, and keeps it in a temporary file. 489 * 490 * @return true, if this ImageInputStream caches data in order to allow 491 * seeking backwards, and keeps it in a temporary file. 492 */ 493 boolean isCachedFile(); 494 495 /** 496 * Closes this stream. 497 * 498 * @throws IOException 499 * if an I/O exception has occurred. 500 */ 501 void close() throws IOException; 502 } 503
