| InputStream is an abstract class that defines the fundamental ways in which a destination (consumer) reads a stream of bytes from some source. |
| read() |
| The most important method to the consumer of an input stream is the one that reads bytes from the source. |
| Here's the first form of read(): |
| InputStream s
= getAnInputStreamFromSomewhere(); byte[] buffer = new byte[1024]; // any size will do if (s.read(buffer) != buffer.length) System.out.println("I got less than I expected."); |
| This form of read() attempts to fill the entire buffer given. If it cannot (usually due to reaching the end of the input stream), it returns the actual number of bytes that were read into the buffer. After that, any further calls to read() return -1, indicating that you are at the end of the stream. Note that the if statement still works even in this case, because -1 != 1024 (this corresponds to an input stream with no bytes in it at all). |
| skip() |
| What if you want to skip over some of the bytes in a stream, or start reading a stream from other than its beginning? A method similar to read() does the trick: |
| if (s.skip(1024) != 1024) System.out.println("I skipped less than I expected."); |
| This example skips over the next 1024 bytes in the input stream. However, the implementation of skip() in InputStream may skip fewer bytes than the given argument, and so it returns a long integer representing the number of bytes it actually skipped. In this example, therefore, a message is printed if the actual number of bytes skipped is less than 1024. |
| available() |
| If for some reason we would like to know how many bytes are in the stream right now, we can ask the following: |
| if (s.available() < 1024) System.out.println("Too little is available right now."); |
| This tells us the number of bytes that we can read without blocking. |
| mark() and reset() InputStream s = getAnInputStreamFromSomewhere(); if (s.markSupported()) { // does s support the notion? . . . // read the stream for a while s.mark(1024); . . . // read less than 1024 more bytes s.reset(); . . . // we can now re-read those bytes } else { . . . // no, perform some alternative } |
| When marking a stream, we specify the maximum number of bytes you intend to allow to pass before resetting it. This allows the stream to limit the size of its byte "memory." If this number of bytes goes by and you have not yet used reset(), the mark becomes invalid, and attempting to use reset() will throw an exception. |
| Marking and resetting a stream is most valuable when you are attempting to identify the type of the stream (or the next part of the stream), but to do so, you must consume a significant piece of it in the process. Often, this is because you have several black-box parsers that you can hand the stream to, but they will consume some (unknown to you) number of bytes before making up their mind about whether the stream is of their type. Set a large size for the limit in mark(), and let each parser run until it either throws an error or completes a successful parse. If an error is thrown, use reset() and try the next parser. |
| close() InputStream s = alwaysMakesANewInputStream(); try { . . . // use s to your heart's content } finally { s.close(); |
| Get used to this idiom (using finally); it's a useful way to be sure something (such as closing the stream) always gets done. |
| Java provides many classes that make "I/O" (input and output) relatively easy and platform independent. In this lesson, we will learn how to act upon the file structure of a platform from inside a Java application. Note that Java applets are NOT permitted to access a platform's file structure for security reasons. |
 |
 |
 |