public Class ArrayCache

When compressing or decompressing many (very) small files in a row, the time spent in construction of new compressor or decompressor objects can be longer than the time spent in actual compression or decompression. A large part of this initialization overhead comes from allocation and garbage collection of large arrays.

The ArrayCache API provides a way to cache large array allocations for reuse. It can give a major performance improvement when compressing or decompressing many tiny files. If you are only (de)compressing one or two files or the files a very big, array caching won't improve anything, although it won't make anything slower either.

Important: The users of ArrayCache don't return the allocated arrays back to the cache in all situations. This a reason why it's called a cache instead of a pool. If it is important to be able to return every array back to a cache, ResettableArrayCache can be useful.

In compressors (OutputStreams) the arrays are returned to the cache when a call to finish() or close() returns successfully (no exceptions are thrown).

In decompressors (InputStreams) the arrays are returned to the cache when the decompression is successfully finished (read returns -1) or close() or close(boolean) is called. This is true even if closing throws an exception.

Raw decompressors don't support close(boolean). With raw decompressors, if one wants to put the arrays back to the cache without closing the underlying InputStream, one can wrap the InputStream into CloseIgnoringInputStream when creating the decompressor instance. Then one can use close().

Different cache implementations can be extended from this base class. All cache implementations must be thread safe.

This class also works as a dummy cache that simply calls new to allocate new arrays and doesn't try to cache anything. A statically allocated dummy cache is available via getDummyCache().

If no ArrayCache is specified when constructing a compressor or decompressor, the default ArrayCache implementation is used. See getDefaultCache() and setDefaultCache(ArrayCache).

This is a class instead of an interface because it's possible that in the future we may want to cache other array types too. New methods can be added to this class without breaking existing cache implementations.