public class CachedInputStream extends InputStream implements ICachedStream
InputStream
wrapper that can be re-read any number of times. This
class will cache the wrapped input steam content the first time it is read,
and subsequent read will use the cache.
To create new instances of CachedInputStream
, use the
CachedStreamFactory
class. Reusing the same factory
will ensure all CachedInputStream
instances created share the same
combined maximum memory. Invoking one of the
newInputStream(...)
methods on this class have the same effect.
In order to re-use this InputStream, you must call rewind()
first
on it. Once done reading the stream, you will get the -1 character as
expected, and it will remain at that until you rewind or dispose.
Starting reading the stream again will start reading bytes from the beginning (re)using its internal cache.
Calling InputStream.close()
has
no effect, and the cache data remains available for subsequent read.
To explicitly dispose of resources allocated to the cache, you can
use the dispose()
method.
Attempting to read a disposed instance will throw an IOException
.
It is recommended you explicitly dispose of CachedInputStream
instances to speed up the release of resources. Otherwise, resources are
de-allocated automatically when the instance is finalized.
The internal cache stores read bytes into memory, up to to the configured maximum cache size. If content exceeds the cache limit, the cache transforms itself into a fast file-based cache of unlimited size. Default memory cache size is 128 KB.
Starting with 1.6.0, mark(int)
is supported. The mark
limit is always unlimited so the method argument is ignored.
CachedStreamFactory
Modifier and Type | Method and Description |
---|---|
int |
available() |
static CachedInputStream |
cache(InputStream is)
Casts to
CachedInputSteam if argument is already of that
type, else create a new CachedInputStream from the input
stream argument using default CachedStreamFactory settings. |
static CachedInputStream |
cache(InputStream is,
CachedStreamFactory streamFactory)
Casts to
CachedInputSteam if argument is already of that
type, else create a new CachedInputStream from the input
stream argument using the given stream factory
(or defaults if null ). |
void |
dispose() |
void |
enforceFullCaching()
If not already fully cached, forces the inner input stream to be
fully cached.
|
protected void |
finalize() |
Path |
getCacheDirectory()
Gets the cache directory where temporary cache files are created.
|
long |
getMemCacheSize() |
CachedStreamFactory |
getStreamFactory() |
boolean |
isCacheEmpty()
Returns
true if was nothing to cache (no writing was
performed) or if the stream was closed. |
boolean |
isDisposed() |
boolean |
isEmpty()
Returns
true if this input stream is empty (zero-lenght
content). |
boolean |
isInMemory()
Whether caching is done in memory for this instance for what has been
read so far.
|
int |
length()
Gets the length of the cached input stream.
|
void |
mark(int readlimit)
The read limit value is ignored.
|
boolean |
markSupported()
Always
true since 1.6.0. |
CachedInputStream |
newInputStream(InputStream is)
Creates a new
CachedInputStream using the same factory settings
that were used to create this instance. |
CachedInputStream |
newInputStream(Path file)
Creates a new
CachedInputStream using the same factory settings
that were used to create this instance. |
int |
read() |
int |
read(byte[] b,
int off,
int len) |
void |
reset()
If no mark has previously been set, it resets to the beginning.
|
void |
rewind()
Rewinds this stream so it can be read again from the beginning.
|
close, read, skip
public static CachedInputStream cache(InputStream is, CachedStreamFactory streamFactory)
CachedInputSteam
if argument is already of that
type, else create a new CachedInputStream
from the input
stream argument using the given stream factory
(or defaults if null
).is
- input streamstreamFactory
- a stream factorypublic static CachedInputStream cache(InputStream is)
CachedInputSteam
if argument is already of that
type, else create a new CachedInputStream
from the input
stream argument using default CachedStreamFactory
settings.is
- input streampublic boolean markSupported()
true
since 1.6.0.markSupported
in class InputStream
true
public void mark(int readlimit)
mark
in class InputStream
readlimit
- any value (ignored)public void reset() throws IOException
reset
in class InputStream
IOException
public boolean isInMemory()
true
if caching is in memory.public boolean isEmpty() throws IOException
true
if this input stream is empty (zero-lenght
content). Unless the stream has been fully read at least once, this
method is more efficient than checking if length()
is zero.true
if emptyIOException
- problem checking if emptypublic int read() throws IOException
read
in class InputStream
IOException
public int read(byte[] b, int off, int len) throws IOException
read
in class InputStream
IOException
public void enforceFullCaching() throws IOException
IOException
- could not enforce full cachingpublic void rewind()
public void dispose() throws IOException
IOException
public int available() throws IOException
available
in class InputStream
IOException
public final Path getCacheDirectory()
getCacheDirectory
in interface ICachedStream
public boolean isCacheEmpty()
true
if was nothing to cache (no writing was
performed) or if the stream was closed.true
if emptypublic boolean isDisposed()
public long getMemCacheSize()
getMemCacheSize
in interface ICachedStream
public int length()
Gets the length of the cached input stream. The length represents the number of bytes that were read from this input stream, after it was read entirely at least once.
Note: Invoking this method when this stream is only partially read (on a first read) will force it to read entirely and cache the inner input stream it wraps. To prevent an unnecessary read cycle, it is always best to invoke this method after this stream was fully read through normal use first.
public CachedInputStream newInputStream(Path file)
CachedInputStream
using the same factory settings
that were used to create this instance.file
- file to create the input stream frompublic CachedInputStream newInputStream(InputStream is)
CachedInputStream
using the same factory settings
that were used to create this instance.is
- input streampublic CachedStreamFactory getStreamFactory()
Copyright © 2008–2023 Norconex Inc.. All rights reserved.