com.evanmclean.evlib.io
Class BoundedOutputStream

java.lang.Object
  extended by java.io.OutputStream
      extended by com.evanmclean.evlib.io.BoundedOutputStream
All Implemented Interfaces:
Closeable, Flushable

public class BoundedOutputStream
extends OutputStream

Output stream wrapper that limits and optionally enforces the number of bytes written. BE CAREFUL. The right combination of parameters could lead to a lot of padding bytes being written.

May throw an OverrunIOException during a write operation if the total number of bytes written exceeds the limit.

May throw an UnderrunIOException during a call to pad() or close() if the total number of bytes written is less than the limit.

Author:
Evan McLean McLean Computer Services (see the overview for copyright and licensing.)

Field Summary
protected  OutputStream out
           
 
Constructor Summary
BoundedOutputStream(OutputStream out, long max)
          Write at most max bytes to the output stream.
BoundedOutputStream(OutputStream out, long max, boolean ignore_underrun, boolean discard_overrun)
          Write at most max bytes to the output stream.
BoundedOutputStream(OutputStream out, long max, byte pad)
          Write at most max bytes to the output stream.
BoundedOutputStream(OutputStream out, long max, byte pad, boolean discard_overrun)
          Write at most max bytes to the output stream.
 
Method Summary
 void close()
          Close the output stream after calling pad().
 void flush()
           
 long getRemaining()
          Get the number of bytes that we can still write to this stream.
 long pad()
          If max bytes have not been written, then pad with the pad byte.
 long pad(byte bt)
          If max bytes have not been written, then pad with the specified byte (this overrides the ignore_underrun flag).
 void write(byte[] arr, int off, int len)
           
 void write(int bt)
           
 
Methods inherited from class java.io.OutputStream
write
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

out

protected final OutputStream out
Constructor Detail

BoundedOutputStream

public BoundedOutputStream(OutputStream out,
                           long max)
Write at most max bytes to the output stream. Will throw an exception on close() or pad() if exactly max bytes have not been written. Will throw an exception if you try and write more than max bytes to the output stream.

Parameters:
out - The output stream to write.
max - The maximum number of bytes to write. If less than zero than no padding or limit enforcement is made.

BoundedOutputStream

public BoundedOutputStream(OutputStream out,
                           long max,
                           boolean ignore_underrun,
                           boolean discard_overrun)
Write at most max bytes to the output stream.

Parameters:
out - The output stream to write.
max - The maximum number of bytes to write. If less than zero than no padding or limit enforcement is made.
ignore_underrun - If true we will not throw an exception on close() or pad() if at least max bytes have not been written.
discard_overrun - If true we will silently throw away any writes that go over a total of max bytes.

BoundedOutputStream

public BoundedOutputStream(OutputStream out,
                           long max,
                           byte pad)
Write at most max bytes to the output stream. Will pad the output stream with the specified byte on close() or pad() if exactly max bytes have not been written. Will throw an exception if you try and write more than max bytes to the output stream.

Parameters:
out - The output stream to write.
max - The maximum number of bytes to write. If less than zero than no padding or limit enforcement is made.
pad - The byte value to pad the output stream with if we ran under.

BoundedOutputStream

public BoundedOutputStream(OutputStream out,
                           long max,
                           byte pad,
                           boolean discard_overrun)
Write at most max bytes to the output stream. Will pad the output stream with the specified byte on close() or pad() if exactly max bytes have not been written.

Parameters:
out - The output stream to write.
max - The maximum number of bytes to write. If less than zero than no padding or limit enforcement is made.
pad - The byte value to pad the output stream with if we run under.
discard_overrun - If true we will silently throw away any writes that go over a total of max bytes.
Method Detail

close

public void close()
           throws UnderrunIOException,
                  IOException
Close the output stream after calling pad().

Specified by:
close in interface Closeable
Overrides:
close in class OutputStream
Throws:
UnderrunIOException - If there were not enough bytes written and a pad character was not specified in the constructor, or ignore_underrun was false (the default).
IOException - If an IO exception occurred while writing padding characters to the output stream or in closing the stream.

flush

public void flush()
           throws IOException
Specified by:
flush in interface Flushable
Overrides:
flush in class OutputStream
Throws:
IOException

getRemaining

public long getRemaining()
Get the number of bytes that we can still write to this stream.

Returns:
The remaining number of bytes that can be written (always greater or equal to zero).

pad

public long pad()
         throws UnderrunIOException,
                IOException
If max bytes have not been written, then pad with the pad byte.

Returns:
The number of bytes written.
Throws:
UnderrunIOException - If there were not enough bytes written and a pad character was not specified in the constructor, or ignore_underrun was false (the default).
IOException - If an IO exception occurred while writing padding characters to the output stream.

pad

public long pad(byte bt)
         throws IOException
If max bytes have not been written, then pad with the specified byte (this overrides the ignore_underrun flag).

Parameters:
bt - The byte to use for padding.
Returns:
The number of bytes written.
Throws:
IOException

write

public void write(byte[] arr,
                  int off,
                  int len)
           throws IOException
Overrides:
write in class OutputStream
Throws:
IOException

write

public void write(int bt)
           throws IOException
Specified by:
write in class OutputStream
Throws:
IOException