Package org.opencms.loader

Class CmsS3ImageCache

java.lang.Object

org.opencms.loader.CmsS3ImageCache

All Implemented Interfaces:

AutoCloseable, I_CmsImageCache, I_CmsImageCacheAccessMetadataProvider

public class CmsS3ImageCache
extends Object
implements I_CmsImageCache, I_CmsImageCacheAccessMetadataProvider

S3 based storage for generated image cache entries.

Nested Class Summary

Nested classes/interfaces inherited from interface org.opencms.loader.I_CmsImageCache

I_CmsImageCache.I_CmsImageCacheEntryVisitor

Constructor Summary

Constructors

Constructor	Description
CmsS3ImageCache(CmsS3ClientConfiguration configuration)	Creates a new image cache.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears all image cache entries.
void	clear(int deleteBatchSize)	Clears the image cache using S3 multi-object delete requests.
void	close()	Closes the image cache and releases associated resources.
void	delete(String key)	Deletes an image cache entry.
CmsS3DeleteResult	deleteBatch(List<String> keys)	Deletes image cache entries with one S3 multi-object request.
boolean	exists(String key)	Returns if the image cache entry exists.
boolean	existsAuthoritatively(String key)	Performs an authoritative existence check which does not rely on locally cached positive metadata.
long	getLength(String key)	Returns the image cache entry length.
CmsS3ObjectMetadata	getMetadata(String key)	Loads metadata for a single image cache entry.
CmsImageCacheEntry	getRecentAccessMetadata(String key)	Returns recently observed metadata for an entry without accessing the backend.
protected void	initClient(I_CmsS3Client s3Client)	Initializes the S3 client.
boolean	renew(String key, String expectedRevision, Instant renewalTime)	Renews an image cache entry by conditionally copying the S3 object onto itself.
boolean	supportsRangeDelivery()	Returns if range delivery is supported.
void	visitEntries(String prefix, I_CmsImageCache.I_CmsImageCacheEntryVisitor visitor)	Visits image cache entries whose normalized keys start with the given prefix.
void	visitEntries(I_CmsImageCache.I_CmsImageCacheEntryVisitor visitor)	Visits all image cache entries.
void	visitEntriesWithMetadata(String prefix, I_CmsS3Client.I_CmsS3ObjectMetadataVisitor visitor)	Visits image cache entries with the given cache key prefix and metadata returned directly by the S3 listing.
void	visitEntriesWithMetadata(I_CmsS3Client.I_CmsS3ObjectMetadataVisitor visitor)	Visits image cache entries with metadata returned directly by the S3 listing.
void	write(String key, byte[] content)	Writes an image cache entry.
void	writeRangeTo(String key, long start, long length, OutputStream out)	Writes an image cache entry byte range to the output stream.
void	writeTo(String key, OutputStream out)	Writes an image cache entry to the output stream.

Methods inherited from class java.lang.Object

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

Constructor Details

CmsS3ImageCache

public CmsS3ImageCache(CmsS3ClientConfiguration configuration)
                throws Exception

Creates a new image cache.

Parameters:

configuration - the S3 configuration

Throws:

Exception - if the configured bucket can not be accessed

Method Details

clear

public void clear()
           throws Exception

Description copied from interface: I_CmsImageCache

Clears all image cache entries.

Specified by:

clear in interface I_CmsImageCache

Throws:

Exception - if clearing fails

See Also:

• I_CmsImageCache.clear()

clear

public void clear(int deleteBatchSize)
           throws Exception

Clears the image cache using S3 multi-object delete requests.

Parameters:

deleteBatchSize - the number of keys per request

Throws:

Exception - if listing or deleting fails

close

public void close()
           throws Exception

Description copied from interface: I_CmsImageCache

Closes the image cache and releases associated resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface I_CmsImageCache

Throws:

Exception - if closing fails

See Also:

• I_CmsImageCache.close()

delete

public void delete(String key)
            throws Exception

Deletes an image cache entry.

Parameters:

key - the image cache key

Throws:

Exception - if deleting fails

deleteBatch

public CmsS3DeleteResult deleteBatch(List<String> keys)
                              throws Exception

Deletes image cache entries with one S3 multi-object request.

Parameters:

keys - the image cache keys

Returns:

the per-entry result using normalized image cache keys

Throws:

Exception - if the complete request fails

exists

public boolean exists(String key)
               throws Exception

Description copied from interface: I_CmsImageCache

Returns if the image cache entry exists.

Specified by:

exists in interface I_CmsImageCache

Parameters:

key - the image cache key

Returns:

true if the image cache entry exists

Throws:

Exception - if the store access fails

See Also:

• I_CmsImageCache.exists(java.lang.String)

existsAuthoritatively

public boolean existsAuthoritatively(String key)
                              throws Exception

Description copied from interface: I_CmsImageCache

Performs an authoritative existence check which does not rely on locally cached positive metadata.

This is used for requests which do not read the cache entry body and can therefore not detect a stale positive existence result while streaming. Implementations without a positive metadata cache can use the default implementation.

Specified by:

existsAuthoritatively in interface I_CmsImageCache

Parameters:

key - the image cache key

Returns:

true if the image cache entry exists in the backing store

Throws:

Exception - if the store access fails

See Also:

• I_CmsImageCache.existsAuthoritatively(java.lang.String)

getLength

public long getLength(String key)
               throws Exception

Description copied from interface: I_CmsImageCache

Returns the image cache entry length.

Specified by:

getLength in interface I_CmsImageCache

Parameters:

key - the image cache key

Returns:

the image cache entry length

Throws:

Exception - if the store access fails

See Also:

• I_CmsImageCache.getLength(java.lang.String)

getMetadata

public CmsS3ObjectMetadata getMetadata(String key)
                                throws Exception

Loads metadata for a single image cache entry.

Parameters:

key - the image cache key

Returns:

the object metadata using the normalized image cache key

Throws:

Exception - if the metadata can not be loaded

getRecentAccessMetadata

public CmsImageCacheEntry getRecentAccessMetadata(String key)

Description copied from interface: I_CmsImageCacheAccessMetadataProvider

Returns recently observed metadata for an entry without accessing the backend.

Specified by:

getRecentAccessMetadata in interface I_CmsImageCacheAccessMetadataProvider

Parameters:

key - the image cache key

Returns:

the metadata, or null if no metadata is locally available

See Also:

• I_CmsImageCacheAccessMetadataProvider.getRecentAccessMetadata(java.lang.String)

renew

public boolean renew(String key,
 String expectedRevision,
 Instant renewalTime)
              throws Exception

Renews an image cache entry by conditionally copying the S3 object onto itself.

Parameters:

key - the image cache key

expectedRevision - the expected object revision

renewalTime - the requested renewal time

Returns:

true if the entry was renewed, or false if it no longer matched

Throws:

Exception - if renewal fails

supportsRangeDelivery

public boolean supportsRangeDelivery()

Description copied from interface: I_CmsImageCache

Returns if range delivery is supported.

Specified by:

supportsRangeDelivery in interface I_CmsImageCache

Returns:

true if ranges can be streamed

See Also:

• I_CmsImageCache.supportsRangeDelivery()

visitEntries

public void visitEntries(I_CmsImageCache.I_CmsImageCacheEntryVisitor visitor)
                  throws Exception

Description copied from interface: I_CmsImageCache

Visits all image cache entries.

Specified by:

visitEntries in interface I_CmsImageCache

Parameters:

visitor - the image cache entry visitor

Throws:

Exception - if listing fails

See Also:

• I_CmsImageCache.visitEntries(org.opencms.loader.I_CmsImageCache.I_CmsImageCacheEntryVisitor)

visitEntries

public void visitEntries(String prefix,
 I_CmsImageCache.I_CmsImageCacheEntryVisitor visitor)
                  throws Exception

Description copied from interface: I_CmsImageCache

Visits image cache entries whose normalized keys start with the given prefix.

Implementations with a prefix-aware storage backend should override this method to apply the prefix while listing. The default implementation filters the result of I_CmsImageCache.visitEntries(I_CmsImageCacheEntryVisitor).

Specified by:

visitEntries in interface I_CmsImageCache

Parameters:

prefix - the image cache key prefix, or an empty string for all entries

visitor - the image cache entry visitor

Throws:

Exception - if listing fails

See Also:

• I_CmsImageCache.visitEntries(java.lang.String, org.opencms.loader.I_CmsImageCache.I_CmsImageCacheEntryVisitor)

visitEntriesWithMetadata

public void visitEntriesWithMetadata(I_CmsS3Client.I_CmsS3ObjectMetadataVisitor visitor)
                              throws Exception

Visits image cache entries with metadata returned directly by the S3 listing.

Parameters:

visitor - the metadata visitor

Throws:

Exception - if listing fails

visitEntriesWithMetadata

public void visitEntriesWithMetadata(String prefix,
 I_CmsS3Client.I_CmsS3ObjectMetadataVisitor visitor)
                              throws Exception

Visits image cache entries with the given cache key prefix and metadata returned directly by the S3 listing.

Parameters:

prefix - the image cache key prefix, or an empty string for all entries

visitor - the metadata visitor

Throws:

Exception - if listing fails

write

public void write(String key,
 byte[] content)
           throws Exception

Description copied from interface: I_CmsImageCache

Writes an image cache entry.

Specified by:

write in interface I_CmsImageCache

Parameters:

key - the image cache key

content - the image cache content

Throws:

Exception - if writing fails

See Also:

• I_CmsImageCache.write(java.lang.String, byte[])

writeRangeTo

public void writeRangeTo(String key,
 long start,
 long length,
 OutputStream out)
                  throws Exception

Description copied from interface: I_CmsImageCache

Writes an image cache entry byte range to the output stream.

Specified by:

writeRangeTo in interface I_CmsImageCache

Parameters:

key - the image cache key

start - the first byte to write

length - the number of bytes to write

out - the output stream

Throws:

Exception - if reading fails

See Also:

• I_CmsImageCache.writeRangeTo(java.lang.String, long, long, java.io.OutputStream)

writeTo

public void writeTo(String key,
 OutputStream out)
             throws Exception

Description copied from interface: I_CmsImageCache

Writes an image cache entry to the output stream.

Specified by:

writeTo in interface I_CmsImageCache

Parameters:

key - the image cache key

out - the output stream

Throws:

Exception - if reading fails

See Also:

• I_CmsImageCache.writeTo(java.lang.String, java.io.OutputStream)

initClient

protected void initClient(I_CmsS3Client s3Client)
                   throws Exception

Initializes the S3 client.

Parameters:

s3Client - the S3 client

Throws:

Exception - if the configured bucket can not be accessed