Java PushbackInputStream Class

by

PushbackInputStream is a class in Java that provides a way to “push back” or unread bytes that have been read from an input stream. This can be useful in situations where you need to peek at the next few bytes in the input stream to decide how to handle the current byte.

The PushbackInputStream class is a subclass of FilterInputStream, which means that it provides additional functionality on top of the basic input stream methods.

Here’s an example of how to use PushbackInputStream:

try (PushbackInputStream in = new PushbackInputStream(new FileInputStream("file.txt"))) {
    int b = in.read();
    if (b == 'A') {
        // "Push back" the byte and read it again later
        in.unread(b);
        // Handle the 'A' case
    } else {
        // Handle the non-'A' case
    }
} catch (IOException e) {
    // Handle the exception
}

In this example, we’re creating a PushbackInputStream that wraps a FileInputStream for a file named “file.txt”. We’re then reading a byte from the input stream and checking if it’s the character ‘A’. If it is, we’re “pushing back” the byte using the unread method and handling the ‘A’ case later. If it’s not ‘A’, we’re handling the non-‘A’ case immediately.

Note that when you push back a byte, it’s not actually removed from the input stream. Instead, it’s just marked as unread, so the next time you call read, it will return the same byte again. You can push back as many bytes as you want, but be aware that there’s a limit to how many bytes can be pushed back, depending on the implementation.

Class declaration:

Here’s the class declaration for PushbackInputStream in Java:

public class PushbackInputStream extends FilterInputStream {
    // Constructor(s)
    public PushbackInputStream(InputStream in);
    public PushbackInputStream(InputStream in, int size);

    // Method(s)
    public void unread(int b) throws IOException;
    public void unread(byte[] b) throws IOException;
    public void unread(byte[] b, int off, int len) throws IOException;
    public int read() throws IOException;
    public int read(byte[] b, int off, int len) throws IOException;
}

As you can see, PushbackInputStream is a subclass of FilterInputStream, which means it has access to all the methods and fields of FilterInputStream, as well as its own additional methods.

The class provides two constructors: one that takes an InputStream as its only argument, and one that takes an InputStream and a size argument. The size argument specifies the size of the pushback buffer, which is the amount of data that can be pushed back using the unread method.

The class provides three versions of the unread method, one that takes a single int argument and two that take a byte array and an offset and length. These methods allow you to push back bytes onto the input stream.

The class also provides two versions of the read method, one that reads a single byte and one that reads a buffer of bytes. These methods allow you to read bytes from the input stream, taking into account any bytes that have been pushed back using the unread method.

Class Methods:

Here are the methods provided by the PushbackInputStream class in Java:

  1. PushbackInputStream(InputStream in) – constructs a new PushbackInputStream object that wraps the specified InputStream object.
  2. PushbackInputStream(InputStream in, int size) – constructs a new PushbackInputStream object that wraps the specified InputStream object and sets the size of the pushback buffer.
  3. void unread(int b) throws IOException – pushes back the specified byte onto the input stream. The next byte read will be the pushed-back byte.
  4. void unread(byte[] b) throws IOException – pushes back the specified byte array onto the input stream. The next bytes read will be the pushed-back bytes.
  5. void unread(byte[] b, int off, int len) throws IOException – pushes back a subarray of the specified byte array onto the input stream. The next bytes read will be the pushed-back bytes.
  6. int read() throws IOException – reads a single byte from the input stream, or the pushed-back byte if there is one.
  7. int read(byte[] b, int off, int len) throws IOException – reads up to len bytes of data from the input stream into an array, starting at offset off. Returns the number of bytes read, or -1 if the end of the stream has been reached.

Note that all methods that perform I/O operations can throw an IOException if an I/O error occurs.

Example of PushbackInputStream class:

Here’s an example of how to use the PushbackInputStream class to read and push back bytes from an input stream:

import java.io.FileInputStream;
import java.io.PushbackInputStream;
import java.io.IOException;

public class PushbackInputStreamExample {
    public static void main(String[] args) {
        try (PushbackInputStream in = new PushbackInputStream(new FileInputStream("file.txt"))) {
            int b;
            while ((b = in.read()) != -1) {
                System.out.print((char)b);
                if (b == ' ') {
                    // Push back the space character and read it again
                    in.unread(b);
                    b = in.read();
                    System.out.print((char)b);
                }
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

In this example, we’re creating a PushbackInputStream that wraps a FileInputStream for a file named “file.txt”. We’re then reading bytes from the input stream and printing them to the console. If we encounter a space character, we’re “pushing back” the space character using the unread method, and then reading it again to print it to the console.

This program will output the contents of the file, with each space character duplicated:

This is a test.
This  is  a  test.

Note that in this example, we’re using the try-with-resources statement to automatically close the PushbackInputStream when we’re done with it. This is recommended practice to ensure that the input stream is properly closed, even if an exception is thrown.