Class LengthRestrictedOutputStream

java.lang.Object
java.io.OutputStream
net.targetr.wtm3.io.LengthRestrictedOutputStream
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable

public class LengthRestrictedOutputStream extends OutputStream
Prevents writing too much data to an output stream.

This class simplifies writing a predefined length of data to a stream, tracking bytes written and supporting two modes of operation when the limit is reached:

Author:
Dr Michael Gardiner
  • Constructor Details

    • LengthRestrictedOutputStream

      public LengthRestrictedOutputStream(OutputStream out, long len, LengthRestrictedOutputStream.Mode mode)
      Decorates an output stream to limit how much data can be written to it using the specified mode.
      Parameters:
      out - The output stream to write to.
      len - The maximum number of bytes that may be written.
      mode - The mode of operation when the limit is reached.
      Throws:
      IllegalArgumentException - if len is negative
      NullPointerException - if out or mode is null
    • LengthRestrictedOutputStream

      public LengthRestrictedOutputStream(OutputStream out, long len, boolean throwException)
      Decorates an output stream to limit how much data can be written to it.
      Parameters:
      out - The output stream to write to.
      len - The maximum number of bytes that may be written.
      throwException - true to throw an IOException when the limit is exceeded; false to stop writing after the limit is reached.
      Throws:
      IllegalArgumentException - if len is negative
      NullPointerException - if out is null
    • LengthRestrictedOutputStream

      public LengthRestrictedOutputStream(OutputStream out, long len)
      Decorates an output stream to limit how much data can be written to it, throwing an IOException if the limit is exceeded.
      Parameters:
      out - The output stream to write to.
      len - The maximum number of bytes that may be written.
      Throws:
      IllegalArgumentException - if len is negative
      NullPointerException - if out is null
  • Method Details

    • write

      public void write(int b) throws IOException
      Writes a single byte to the output stream.
      Specified by:
      write in class OutputStream
      Parameters:
      b - The byte to write (the 8 low-order bits).
      Throws:
      IOException - if writing exceeds the length limit in LengthRestrictedOutputStream.Mode.THROW_EXCEPTION mode, or if an underlying I/O error occurs.
    • write

      public void write(byte[] buffer) throws IOException
      Writes all bytes from the specified byte array to the output stream.
      Overrides:
      write in class OutputStream
      Parameters:
      buffer - The buffer containing data to write.
      Throws:
      IOException - if writing exceeds the length limit in LengthRestrictedOutputStream.Mode.THROW_EXCEPTION mode, or if an underlying I/O error occurs.
      NullPointerException - if buffer is null.
    • write

      public void write(byte[] buffer, int off, int len) throws IOException
      Writes a portion of a byte array to the output stream.
      Overrides:
      write in class OutputStream
      Parameters:
      buffer - The buffer containing data to write.
      off - The start offset in the data.
      len - The number of bytes to write.
      Throws:
      IOException - if writing exceeds the length limit in LengthRestrictedOutputStream.Mode.THROW_EXCEPTION mode, or if an underlying I/O error occurs.
      IndexOutOfBoundsException - if off or len are invalid.
      NullPointerException - if buffer is null.
    • flush

      public void flush() throws IOException
      Flushes the underlying output stream.
      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class OutputStream
      Throws:
      IOException - if an I/O error occurs.
    • close

      public void close() throws IOException
      Closes the underlying output stream.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class OutputStream
      Throws:
      IOException - if an I/O error occurs.
    • getBytesWritten

      public long getBytesWritten()
      Returns the total number of bytes written to this stream so far.
      Returns:
      the number of bytes written
    • getRestriction

      public long getRestriction()
      Returns the maximum number of bytes that can be written to this stream.
      Returns:
      the byte limit
    • getRemaining

      public long getRemaining()
      Returns the remaining number of bytes that can be written before reaching the limit.
      Returns:
      the remaining bytes allowed
    • isLimitReached

      public boolean isLimitReached()
      Checks if the write limit was reached.
      Returns:
      true if the limit was reached, false otherwise
    • isLimitExceeded

      public boolean isLimitExceeded()
      Checks if any write attempt exceeded the limit.
      Returns:
      true if an attempt was made to write past the limit, false otherwise
    • isFinished

      public boolean isFinished()
      Checks if the stream has reached the allowed write limit.
      Returns:
      true if the limit is reached, false otherwise
    • getMode

      Returns the operational mode of this stream.
      Returns:
      the operational mode
    • getOutputStream

      public OutputStream getOutputStream()
      Returns the underlying wrapped output stream.
      Returns:
      the wrapped output stream
    • getWrappedOutputStream

      public OutputStream getWrappedOutputStream()
      Returns the underlying wrapped output stream.
      Returns:
      the wrapped output stream
    • toString

      public String toString()
      Returns a string representation of this stream.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this stream