Package org.apache.commons.io.input

Class BoundedInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

org.apache.commons.io.input.ProxyInputStream

org.apache.commons.io.input.BoundedInputStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class BoundedInputStream
extends ProxyInputStream

Reads bytes up to a maximum count and stops once reached.

To build an instance: Use the builder() to access all features.

By default, a BoundedInputStream is unbound; so make sure to call BoundedInputStream.AbstractBuilder.setMaxCount(long).

You can find out how many bytes this stream has seen so far by calling getCount(). This value reflects bytes read and skipped.

Using a ServletInputStream

A ServletInputStream can block if you try to read content that isn't there because it doesn't know whether the content hasn't arrived yet or whether the content has finished. Initialize an BoundedInputStream with the Content-Length sent in the ServletInputStream's header, this stop it from blocking, providing it's been sent with a correct content length in the first place.

Using NIO

 BoundedInputStream s = BoundedInputStream.builder()
   .setPath(Paths.get("MyFile.xml"))
   .setMaxCount(1024)
   .setPropagateClose(false)
   .get();
 
 

Using IO

 BoundedInputStream s = BoundedInputStream.builder()
   .setFile(new File("MyFile.xml"))
   .setMaxCount(1024)
   .setPropagateClose(false)
   .get();
 
 

Counting Bytes

You can set the running count when building, which is most useful when starting from another stream:

 InputStream in = ...;
 BoundedInputStream s = BoundedInputStream.builder()
   .setInputStream(in)
   .setCount(12)
   .setMaxCount(1024)
   .setPropagateClose(false)
   .get();
 
 

Listening for the max count reached

 BoundedInputStream s = BoundedInputStream.builder()
   .setPath(Paths.get("MyFile.xml"))
   .setMaxCount(1024)
   .setOnMaxCount((max, count) -> System.out.printf("Max count %,d reached with a last read count of %,d%n", max, count))
   .get();
 
 

Since:

2.0

See Also:

BoundedInputStream.Builder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	BoundedInputStream.AbstractBuilder<T extends BoundedInputStream.AbstractBuilder<T>>	For subclassing builders from BoundedInputStream subclassses.
static class	BoundedInputStream.Builder	Builds a new BoundedInputStream.

Field Summary

Fields

Modifier and Type	Field	Description
private long	count	The current count of bytes counted.
private long	mark	The current mark.
private long	maxCount	The max count of bytes to read.
private IOBiConsumer<java.lang.Long,java.lang.Long>	onMaxCount
private boolean	propagateClose	Flag if close should be propagated.

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor	Description
BoundedInputStream(java.io.InputStream in)	Deprecated. Use IOSupplier.get().
BoundedInputStream(java.io.InputStream inputStream, long maxCount)	Deprecated. Use IOSupplier.get().
BoundedInputStream(java.io.InputStream inputStream, BoundedInputStream.Builder builder)
BoundedInputStream(BoundedInputStream.Builder builder)

Method Summary

Modifier and Type	Method	Description
protected void	afterRead(int n)	Adds the number of read bytes to the count.
int	available()	Invokes the delegate's InputStream.available() method.
static BoundedInputStream.Builder	builder()	Constructs a new BoundedInputStream.AbstractBuilder.
void	close()	Invokes the delegate's InputStream.close() method if isPropagateClose() is true.
long	getCount()	Gets the count of bytes read.
long	getMaxCount()	Gets the max count of bytes to read.
long	getMaxLength()	Deprecated. Use getMaxCount().
long	getRemaining()	Gets how many bytes remain to read.
private boolean	isMaxCount()
boolean	isPropagateClose()	Tests whether the close() method should propagate to the underling InputStream.
void	mark(int readLimit)	Invokes the delegate's InputStream.mark(int) method.
boolean	markSupported()	Invokes the delegate's InputStream.markSupported() method.
protected void	onMaxLength(long max, long count)	A caller has caused a request that would cross the maxLength boundary.
int	read()	Invokes the delegate's InputStream.read() method if the current position is less than the limit.
int	read(byte[] b)	Invokes the delegate's InputStream.read(byte[]) method.
int	read(byte[] b, int off, int len)	Invokes the delegate's InputStream.read(byte[], int, int) method.
void	reset()	Invokes the delegate's InputStream.reset() method.
void	setPropagateClose(boolean propagateClose)	Deprecated. Use BoundedInputStream.AbstractBuilder.setPropagateClose(boolean).
long	skip(long n)	Invokes the delegate's InputStream.skip(long) method.
private long	toReadLen(long len)
java.lang.String	toString()	Invokes the delegate's Object.toString() method.

Methods inherited from class org.apache.commons.io.input.ProxyInputStream

beforeRead, checkOpen, handleIOException, isClosed, setReference, unwrap

Methods inherited from class java.io.InputStream

nullInputStream, readAllBytes, readNBytes, readNBytes, transferTo

Methods inherited from class java.lang.Object

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

Field Detail

count

private long count

The current count of bytes counted.

mark

private long mark

The current mark.

maxCount

private final long maxCount

The max count of bytes to read.

onMaxCount

private final IOBiConsumer<java.lang.Long,java.lang.Long> onMaxCount

propagateClose

private boolean propagateClose

Flag if close should be propagated. TODO Make final in 3.0.

Constructor Detail

BoundedInputStream

BoundedInputStream(BoundedInputStream.Builder builder)
            throws java.io.IOException

Throws:

java.io.IOException

BoundedInputStream

@Deprecated
public BoundedInputStream(java.io.InputStream in)

Deprecated.

Use IOSupplier.get().

Constructs a new BoundedInputStream that wraps the given input stream and is unbounded.

To build an instance: Use the builder() to access all features.

Parameters:

in - The wrapped input stream.

BoundedInputStream

BoundedInputStream(java.io.InputStream inputStream,
                   BoundedInputStream.Builder builder)

BoundedInputStream

@Deprecated
public BoundedInputStream(java.io.InputStream inputStream,
                          long maxCount)

Deprecated.

Use IOSupplier.get().

Constructs a new BoundedInputStream that wraps the given input stream and limits it to a certain size.

Parameters:

inputStream - The wrapped input stream.

maxCount - The maximum number of bytes to return, negative means unbound.

Method Detail

builder

public static BoundedInputStream.Builder builder()

Constructs a new BoundedInputStream.AbstractBuilder.

Returns:

a new BoundedInputStream.AbstractBuilder.

Since:

2.16.0

afterRead

protected void afterRead(int n)
                  throws java.io.IOException

Adds the number of read bytes to the count.

Overrides:

afterRead in class ProxyInputStream

Parameters:

n - number of bytes read, or -1 if no more bytes are available

Throws:

java.io.IOException - Not thrown here but subclasses may throw.

Since:

2.0

available

public int available()
              throws java.io.IOException

Invokes the delegate's InputStream.available() method.

Overrides:

available in class ProxyInputStream

Returns:

the number of available bytes, 0 if the stream is closed.

Throws:

java.io.IOException - if an I/O error occurs.

close

public void close()
           throws java.io.IOException

Invokes the delegate's InputStream.close() method if isPropagateClose() is true.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Overrides:

close in class ProxyInputStream

Throws:

java.io.IOException - if an I/O error occurs.

getCount

public long getCount()

Gets the count of bytes read.

Returns:

The count of bytes read.

Since:

2.12.0

getMaxCount

public long getMaxCount()

Gets the max count of bytes to read.

Returns:

The max count of bytes to read.

Since:

2.16.0

getMaxLength

@Deprecated
public long getMaxLength()

Deprecated.

Use getMaxCount().

Gets the max count of bytes to read.

Returns:

The max count of bytes to read.

Since:

2.12.0

getRemaining

public long getRemaining()

Gets how many bytes remain to read.

Returns:

bytes how many bytes remain to read.

Since:

2.16.0

isMaxCount

private boolean isMaxCount()

isPropagateClose

public boolean isPropagateClose()

Tests whether the close() method should propagate to the underling InputStream.

Returns:

true if calling close() propagates to the close() method of the underlying stream or false if it does not.

mark

public void mark(int readLimit)

Invokes the delegate's InputStream.mark(int) method.

Overrides:

mark in class ProxyInputStream

Parameters:

readLimit - read ahead limit

markSupported

public boolean markSupported()

Invokes the delegate's InputStream.markSupported() method.

Overrides:

markSupported in class ProxyInputStream

Returns:

true if mark is supported, otherwise false

See Also:

ProxyInputStream.mark(int), ProxyInputStream.reset()

onMaxLength

protected void onMaxLength(long max,
                           long count)
                    throws java.io.IOException

A caller has caused a request that would cross the maxLength boundary.

Delegates to the consumer set in BoundedInputStream.AbstractBuilder.setOnMaxCount(IOBiConsumer).

Parameters:

max - The max count of bytes to read.

count - The count of bytes read.

Throws:

java.io.IOException - Subclasses may throw.

Since:

2.12.0

read

public int read()
         throws java.io.IOException

Invokes the delegate's InputStream.read() method if the current position is less than the limit.

Overrides:

read in class ProxyInputStream

Returns:

the byte read or -1 if the end of stream or the limit has been reached.

Throws:

java.io.IOException - if an I/O error occurs.

read

public int read(byte[] b)
         throws java.io.IOException

Invokes the delegate's InputStream.read(byte[]) method.

Overrides:

read in class ProxyInputStream

Parameters:

b - the buffer to read the bytes into

Returns:

the number of bytes read or -1 if the end of stream or the limit has been reached.

Throws:

java.io.IOException - if an I/O error occurs.

read

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

Invokes the delegate's InputStream.read(byte[], int, int) method.

Overrides:

read in class ProxyInputStream

Parameters:

b - the buffer to read the bytes into

off - The start offset

len - The number of bytes to read

Returns:

the number of bytes read or -1 if the end of stream or the limit has been reached.

Throws:

java.io.IOException - if an I/O error occurs.

reset

public void reset()
           throws java.io.IOException

Invokes the delegate's InputStream.reset() method.

Overrides:

reset in class ProxyInputStream

Throws:

java.io.IOException - if an I/O error occurs.

setPropagateClose

@Deprecated
public void setPropagateClose(boolean propagateClose)

Deprecated.

Use BoundedInputStream.AbstractBuilder.setPropagateClose(boolean).

Sets whether the close() method should propagate to the underling InputStream.

Parameters:

propagateClose - true if calling close() propagates to the close() method of the underlying stream or false if it does not.

skip

public long skip(long n)
          throws java.io.IOException

Invokes the delegate's InputStream.skip(long) method.

Overrides:

skip in class ProxyInputStream

Parameters:

n - the number of bytes to skip

Returns:

the actual number of bytes skipped

Throws:

java.io.IOException - if an I/O error occurs.

toReadLen

private long toReadLen(long len)

toString

public java.lang.String toString()

Invokes the delegate's Object.toString() method.

Overrides:

toString in class java.lang.Object

Returns:

the delegate's Object.toString()