Package com.globalmentor.io

Class TempOutputStream

java.lang.Object
java.io.OutputStream
com.globalmentor.io.OutputStreamDecorator<OutputStream>
com.globalmentor.io.TempOutputStream
All Implemented Interfaces:
Disposable, Closeable, Flushable, AutoCloseable
public class TempOutputStream extends OutputStreamDecorator<OutputStream>
An output stream used for the temporary collection of bytes. The bytes are collected in memory using a ByteArrayOutputStream. If the collected bytes rise above a configured threshold, bytes are collected instead in a temporary file that is removed when the output stream is closed. No additional buffering is performed, allowing buffered to be controlled at a higher level.

An input stream to the collected bytes can be requested at any time using getInputStream(). Retrieving an input stream effectively closes the output stream and any future writes will fail. Retrieving an input stream also calls dispose(), regardless of the auto-dispose setting.

Once the stream is closed, if auto-dispose is turned on the underlying output stream is released and the temporary file, if any, is deleted. Thus if it is not known exactly when the stream will be closed, either auto-dispose should be turned off and/or a subclass should be created that overrides OutputStreamDecorator.beforeClose(), at which point getInputStream() can be called to retrieve the written bytes.

It is very important to properly close this output stream when finished using it; otherwise, orphaned temporary files may remain. It is similarly important to close any retrieved input stream for the same reason.

Author:
Garret Wilson

  • Field Details

    • DEFAULT_THRESHOLD

      public static final int DEFAULT_THRESHOLD
      The default threshold number of bytes for switching from memory to a temporary file.
      See Also:

  • Constructor Details

    • TempOutputStream

      public TempOutputStream()
      Default constructor with default threshold, automatically calling dispose() when closed.
      See Also:

    • TempOutputStream

      public TempOutputStream(boolean autoDispose)
      Auto-dispose constructor with default threshold.
      Parameters:
      autoDispose - Whether the temporary files, if any, should be deleted.
      See Also:

    • TempOutputStream

      public TempOutputStream(int threshold)
      Threshold constructor, automatically calling dispose() when closed. If the threshold is set to zero, this output stream will always use a temporary file.
      Parameters:
      threshold - The threshold number of bytes for switching from memory to a temporary file.
      Throws:
      IllegalArgumentException - if the given threshold is negative.

    • TempOutputStream

      public TempOutputStream(int threshold, boolean autoDispose)
      Threshold constructor. If the threshold is set to zero, this output stream will always use a temporary file.
      Parameters:
      threshold - The threshold number of bytes for switching from memory to a temporary file.
      autoDispose - Whether the temporary files, if any, should be deleted.
      Throws:
      IllegalArgumentException - if the given threshold is negative.

  • Method Details

    • getThreshold

      public int getThreshold()
      The threshold number of bytes for switching from memory to a temporary file. If set to zero, this output stream will always use a temporary file.
      Returns:
      The threshold number of bytes for switching from memory to a temporary file.

    • getInputStream

      public InputStream getInputStream() throws IOException
      Flushes and retrieves an input stream to the current data. This method effectively closes the output stream, and no further writes will be allowed. Transfer of responsibility of the temporary file, if any, is transferred to the input stream, making it important that the consumer close the input stream when finished to ensure the temporary file is deleted.

      This method unconditionally calls dispose(), regardless of the auto-dispose setting.

      Returns:
      An input stream to the current data.
      Throws:
      IOException - if the output stream has already been closed.
      IOException - if there is an error retrieving an input stream to the data.
      See Also:

    • beforeWrite

      protected void beforeWrite(int len) throws IOException
      Called before any writes occur, passing the number of bytes that will be written.

      Examines the number of bytes prepared to write and, if writing them would surpass the threshold, switches immediately to a temporary file and writes the so-far accumulated bytes to that file.

      Parameters:
      len - The number of bytes ready to be written.
      Throws:
      IOException - if the output stream has already been closed.
      IOException - if there is an error updating the streams.
      See Also:

    • write

      public void write(int b) throws IOException
      This version performs pre-write checks and updates.
      Overrides:
      write in class OutputStreamDecorator<OutputStream>
      Throws:
      IOException
      See Also:

    • write

      public void write(byte[] b) throws IOException
      This version performs pre-write checks and updates.
      Overrides:
      write in class OutputStreamDecorator<OutputStream>
      Throws:
      IOException
      See Also:

    • write

      public void write(byte[] b, int off, int len) throws IOException
      This version performs pre-write checks and updates.
      Overrides:
      write in class OutputStreamDecorator<OutputStream>
      Throws:
      IOException
      See Also:

    • close

      public void close(boolean closeDecoratedStream) throws IOException
      Closes this output stream and releases any system resources associated with the stream. A closed stream cannot perform output operations and cannot be reopened. If auto-dispose is enabled, OutputStreamDecorator.dispose() will be called if closing is successful. This version does not allow closing without closing the decorated stream.
      Overrides:
      close in class OutputStreamDecorator<OutputStream>
      Parameters:
      closeDecoratedStream - Whether the decorated stream should also be closed.
      Throws:
      IllegalArgumentException - if the close decorated stream flag is false.
      IOException - if an I/O error occurs.
      See Also:

    • createTempFile

      protected static File createTempFile() throws IOException
      Creates a temporary file. The file will not be marked for automatic deletion.
      Returns:
      A new file for temporarily storing data.
      Throws:
      IOException - if there is an error creating a temporary file.

    • dispose

      public void dispose()
      Uninitializes the object. After calling this method, the object should not be used further. This method can be called multiple times without danger. All exceptions should be caught and dealt with in this method. Child classes must call the parent class version. This version deletes the temporary file, if any.
      Specified by:
      dispose in interface Disposable
      Overrides:
      dispose in class OutputStreamDecorator<OutputStream>