Apache Commons logo

Commons JCS™

Serializing and De-serializing Cache Objects

When using auxiliary caches, cache elements need to be serialized into a byte stream in order to be stored on disk or transported through a network. For reading from these caches, bytes must be de-serialized into objects. By default, JCS uses the standard JDK methods for serializing and de-serializing objects. However, all of the auxiliaries also support setting a custom serializer to have finer control of the behavior.

This document describes the built-in serializers and their configuration.

Compressing Serializer

The CompressingSerializer gzips the bytes after serializing the cache object the default way. For reading, the bytes will be de-compressed first and then de-serialized into a Java object. The class can also be used as a wrapper around an arbitrary class implementing IElementSerializer.

The configuration for a typical application looks like this:

                
# Block Disk Cache
jcs.auxiliary.blockDiskCache=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheFactory
jcs.auxiliary.blockDiskCache.attributes=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheAttributes
jcs.auxiliary.blockDiskCache.attributes.DiskPath=target/test-sandbox/block-disk-cache
jcs.auxiliary.blockDiskCache.serializer=org.apache.commons.jcs3.utils.serialization.CompressingSerializer
                
            

Encrypting Serializer

The EncryptingSerializer uses AES to encrypt the bytes after serializing the cache object the default way. For reading, the bytes will be decrypted first and then de-serialized into a Java object. The class can also be used as a wrapper around an arbitrary class implementing IElementSerializer.

The implementation uses a symmetrical pre-shared key phrase for encrypting and decrypting the data. The key is salted separately for each object and the salt is stored together with the serialized data.

The configuration for a typical application looks like this:

                
# Block Disk Cache
jcs.auxiliary.blockDiskCache2=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheFactory
jcs.auxiliary.blockDiskCache2.attributes=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheAttributes
jcs.auxiliary.blockDiskCache2.attributes.DiskPath=target/test-sandbox/block-disk-cache2
jcs.auxiliary.blockDiskCache2.serializer=org.apache.commons.jcs3.utils.serialization.EncryptingSerializer
jcs.auxiliary.blockDiskCache2.serializer.attributes.preSharedKey=my_secret
                
            

The AES cipher transformation default is AES/ECB/PKCS5Padding as this algorithm must be supported by every JDK 8, according to the docs. Special handling is provided for the AES/GCM/NoPadding algorithm which can be activated like this:

                
jcs.auxiliary.blockDiskCache2.serializer.attributes.aesCipherTransformation=AES/GCM/NoPadding
                
            

The encryption code uses the default constructor of SecureRandom() to create a random number generator. Depending on your security requirements, you should configure a SecureRandom that works for your environment, giving preference to the ones with good randomness (given that your environment generates entropy fast enough, we saw problems with Linux).