ThresholdingOutputStream (Apache Tomcat 10.1.14 API Documentation)

Package org.apache.tomcat.util.http.fileupload

## Class ThresholdingOutputStream

- java.lang.Object
- - java.io.OutputStream
  - - org.apache.tomcat.util.http.fileupload.ThresholdingOutputStream

- All Implemented Interfaces:
    `Closeable`, `Flushable`, `AutoCloseable`
  Direct Known Subclasses:
    `DeferredFileOutputStream`

      public abstract class ThresholdingOutputStream
      extends OutputStream

  An output stream which triggers an event when a specified number of bytes of data have been written to it. The event can be used, for example, to throw an exception if a maximum has been reached, or to switch the underlying stream type when the threshold is exceeded.

  This class overrides all `OutputStream` methods. However, these overrides ultimately call the corresponding methods in the underlying output stream implementation.

  NOTE: This implementation may trigger the event before the threshold is actually reached, since it triggers when a pending write operation would cause the threshold to be exceeded.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ThresholdingOutputStream​(int threshold)` | Constructs an instance of this class which will trigger an event at the specified threshold.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `checkThreshold​(int count)` | Checks to see if writing the specified number of bytes would cause the configured threshold to be exceeded.
    `void` | `close()` | Closes this output stream and releases any system resources associated with this stream.
    `void` | `flush()` | Flushes this output stream and forces any buffered output bytes to be written out.
    `protected abstract OutputStream` | `getStream()` | Returns the underlying output stream, to which the corresponding `OutputStream` methods in this class will ultimately delegate.
    `boolean` | `isThresholdExceeded()` | Determines whether or not the configured threshold has been exceeded for this output stream.
    `protected abstract void` | `thresholdReached()` | Indicates that the configured threshold has been reached, and that a subclass should take whatever action necessary on this event.
    `void` | `write​(byte[] b)` | Writes `b.length` bytes from the specified byte array to this output stream.
    `void` | `write​(byte[] b, int off, int len)` | Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.
    `void` | `write​(int b)` | Writes the specified byte to this output stream.

    - ### Methods inherited from class java.io.OutputStream

      `nullOutputStream`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ThresholdingOutputStream

          public ThresholdingOutputStream​(int threshold)

      Constructs an instance of this class which will trigger an event at the specified threshold.
      Parameters:
        `threshold` - The number of bytes at which to trigger an event.

  - ### Method Detail

    - #### write

          public void write​(int b)
                     throws IOException

      Writes the specified byte to this output stream.
      Specified by:
        `write` in class `OutputStream`
      Parameters:
        `b` - The byte to be written.
      Throws:
        `IOException` - if an error occurs.

    - #### write

          public void write​(byte[] b)
                     throws IOException

      Writes `b.length` bytes from the specified byte array to this output stream.
      Overrides:
        `write` in class `OutputStream`
      Parameters:
        `b` - The array of bytes to be written.
      Throws:
        `IOException` - if an error occurs.

    - #### write

          public void write​(byte[] b,
                            int off,
                            int len)
                     throws IOException

      Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.
      Overrides:
        `write` in class `OutputStream`
      Parameters:
        `b` - The byte array from which the data will be written.
        `off` - The start offset in the byte array.
        `len` - The number of bytes to write.
      Throws:
        `IOException` - if an error occurs.

    - #### flush

          public void flush()
                     throws IOException

      Flushes this output stream and forces any buffered output bytes to be written out.
      Specified by:
        `flush` in interface `Flushable`
      Overrides:
        `flush` in class `OutputStream`
      Throws:
        `IOException` - if an error occurs.

    - #### close

          public void close()
                     throws IOException

      Closes this output stream and releases any system resources associated with this stream.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`
      Overrides:
        `close` in class `OutputStream`
      Throws:
        `IOException` - if an error occurs.

    - #### isThresholdExceeded

          public boolean isThresholdExceeded()

      Determines whether or not the configured threshold has been exceeded for this output stream.
      Returns:
        `true` if the threshold has been reached; `false` otherwise.

    - #### checkThreshold

          protected void checkThreshold​(int count)
                                 throws IOException

      Checks to see if writing the specified number of bytes would cause the configured threshold to be exceeded. If so, triggers an event to allow a concrete implementation to take action on this.
      Parameters:
        `count` - The number of bytes about to be written to the underlying output stream.
      Throws:
        `IOException` - if an error occurs.

    - #### getStream

          protected abstract OutputStream getStream()
                                             throws IOException

      Returns the underlying output stream, to which the corresponding `OutputStream` methods in this class will ultimately delegate.
      Returns:
        The underlying output stream.
      Throws:
        `IOException` - if an error occurs.

    - #### thresholdReached

          protected abstract void thresholdReached()
                                            throws IOException

      Indicates that the configured threshold has been reached, and that a subclass should take whatever action necessary on this event. This may include changing the underlying output stream.
      Throws:
        `IOException` - if an error occurs.