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:
  `java.io.Closeable`, `java.io.Flushable`, `java.lang.AutoCloseable`

Direct Known Subclasses:
  `DeferredFileOutputStream`

    public abstract class ThresholdingOutputStream
    extends java.io.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
`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
`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 java.io.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 java.io.IOException

Writes the specified byte to this output stream.

Specified by:
  `write` in class `java.io.OutputStream`
Parameters:
  `b` - The byte to be written.
Throws:
  `java.io.IOException` - if an error occurs.

#### write

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

Writes `b.length` bytes from the specified byte array to this output stream.

Overrides:
  `write` in class `java.io.OutputStream`
Parameters:
  `b` - The array of bytes to be written.
Throws:
  `java.io.IOException` - if an error occurs.

#### write

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

Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.

Overrides:
  `write` in class `java.io.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:
  `java.io.IOException` - if an error occurs.

#### flush

    public void flush()
               throws java.io.IOException

Flushes this output stream and forces any buffered output bytes to be written out.

Specified by:
  `flush` in interface `java.io.Flushable`
Overrides:
  `flush` in class `java.io.OutputStream`
Throws:
  `java.io.IOException` - if an error occurs.

#### close

    public void close()
               throws java.io.IOException

Closes this output stream and releases any system resources associated with this stream.

Specified by:
  `close` in interface `java.lang.AutoCloseable`
Specified by:
  `close` in interface `java.io.Closeable`
Overrides:
  `close` in class `java.io.OutputStream`
Throws:
  `java.io.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 java.io.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:
  `java.io.IOException` - if an error occurs.

#### getStream

    protected abstract java.io.OutputStream getStream()
                                               throws java.io.IOException

Returns the underlying output stream, to which the corresponding `OutputStream` methods in this class will ultimately delegate.

Returns:
  The underlying output stream.
Throws:
  `java.io.IOException` - if an error occurs.

#### thresholdReached

    protected abstract void thresholdReached()
                                      throws java.io.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:
  `java.io.IOException` - if an error occurs.