com.evanmclean.evlib.io
Class BoundedOutputStream

java.lang.Object
  java.io.OutputStream
      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 M^cLean M^cLean 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