Package org.tukaani.xz

## Class ArrayCache

- java.lang.Object
- - org.tukaani.xz.ArrayCache

Direct Known Subclasses:
  `BasicArrayCache`, `ResettableArrayCache`

    public class ArrayCache
    extends Object

Caches large arrays for reuse (base class and a dummy cache implementation).

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.

Since:
  1.7
See Also:
  `BasicArrayCache`

### Constructor Summary

Constructors
`ArrayCache()` Creates a new `ArrayCache` that does no caching (a dummy cache).

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`byte[]` `getByteArray​(int size, boolean fillWithZeros)` Allocates a new byte array.
`static ArrayCache` `getDefaultCache()` Gets the default `ArrayCache` instance.
`static ArrayCache` `getDummyCache()` Returns a statically-allocated `ArrayCache` instance.
`int[]` `getIntArray​(int size, boolean fillWithZeros)` Allocates a new int array.
`void` `putArray​(byte[] array)` Puts the given byte array to the cache.
`void` `putArray​(int[] array)` Puts the given int array to the cache.
`static void` `setDefaultCache​(ArrayCache arrayCache)` Sets the default `ArrayCache` instance.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### ArrayCache

    public ArrayCache()

Creates a new `ArrayCache` that does no caching (a dummy cache). If you need a dummy cache, you may want to call `getDummyCache()` instead.

### Method Detail

#### getDummyCache

    public static ArrayCache getDummyCache()

Returns a statically-allocated `ArrayCache` instance. It can be shared by all code that needs a dummy cache.

#### getDefaultCache

    public static ArrayCache getDefaultCache()

Gets the default `ArrayCache` instance. This is a global cache that is used when the application specifies nothing else. The default is a dummy cache (see `getDummyCache()`).

#### setDefaultCache

    public static void setDefaultCache​(ArrayCache arrayCache)

Sets the default `ArrayCache` instance. Use with care. Other libraries using this package probably shouldn't call this function as libraries cannot know if there are other users of the xz package in the same application.

#### getByteArray

    public byte[] getByteArray​(int size,
                               boolean fillWithZeros)

Allocates a new byte array.

This implementation simply returns `new byte[size]`.

Parameters:
  `size` - the minimum size of the array to allocate; an implementation may return an array that is larger than the given `size`
  `fillWithZeros` - if true, the caller expects that the first `size` elements in the array are zero; if false, the array contents can be anything, which speeds things up when reusing a cached array

#### putArray

    public void putArray​(byte[] array)

Puts the given byte array to the cache. The caller must no longer use the array.

This implementation does nothing.

#### getIntArray

    public int[] getIntArray​(int size,
                             boolean fillWithZeros)

Allocates a new int array.

This implementation simply returns `new int[size]`.

Parameters:
  `size` - the minimum size of the array to allocate; an implementation may return an array that is larger than the given `size`
  `fillWithZeros` - if true, the caller expects that the first `size` elements in the array are zero; if false, the array contents can be anything, which speeds things up when reusing a cached array

#### putArray

    public void putArray​(int[] array)

Puts the given int array to the cache. The caller must no longer use the array.

This implementation does nothing.