mondrian.spi

Interface SegmentCache

All Known Implementing Classes:

MemorySegmentCache

public interface SegmentCache

SPI definition of the segments cache.

Lookups are performed using SegmentHeaders and SegmentBodys. Both are immutable and fully serializable.

There are a few ways to declare a SegmentCache implementation in Mondrian. The first one is to set the MondrianProperties.SegmentCache property.

The second one is to use the Java Services API. This is the preferred mean. You will need to create a jar file, accessible through the same class loader as Mondrian, and add a file called /META-INF/services/mondrian.spi.SegmentCache which contains the name of the segment cache implementation to use.

The third method is to use the SegmentCache.SegmentCacheInjector. This is to be used as a last resort, in environments where the cache implementation is not part of the same class loader as Mondrian. In those cases, Mondrian can't dynamically load the segment cache class. The injector serves as an IoC-like service.

All of the segment caches that Mondrian discovers, throughout all of these means of discovery, will be used simultaneously. It is not possible to register new segment caches for a previously existing instance of a Mondrian server. The caches are scanned and configured when each Mondrian instance gets created.

Implementations are expected to be thread-safe. Mondrian is likely to submit multiple requests at the same time, from different threads. It is the responsibility of the cache implementation to maintain a consistent state.

Implementations must implement a time-out policy, if needed. Mondrian knows that a call to the cache might take a while. (Mondrian uses worker threads to call into the cache for precisely that reason.) Left to its own devices, Mondrian will wait forever for a call to complete. The cache implementation might know that a call to get(mondrian.spi.SegmentHeader) that has taken 100 milliseconds already is probably hung, so it should return null or throw an exception. Then Mondrian can get on with its life, and get the segment some other way.

Implementations must provide a default empty constructor. Mondrian creates one segment cache instance per Mondrian server. There could be more than one Mondrian server running in the same JVM.

Author:

LBoudreau

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SegmentCache.SegmentCacheInjector The SegmentCache.SegmentCacheInjector is a means to inject SegmentCache instances directly into Mondrian, instead of passing a class name.
static interface	SegmentCache.SegmentCacheListener SegmentCache.SegmentCacheListener objects are used to listen to the state of the cache and be notified of changes to its state or its entries.

Method Summary

Modifier and Type	Method and Description
void	addListener(SegmentCache.SegmentCacheListener listener) Adds a listener to this segment cache implementation.
SegmentBody	get(SegmentHeader header) Returns a SegmentBody once the cache has returned any results, or null if no segment corresponding to the header could be found.
List<SegmentHeader>	getSegmentHeaders() Returns a list of all segments present in the cache.
boolean	put(SegmentHeader header, SegmentBody body) Stores a segment data in the cache.
boolean	remove(SegmentHeader header) Removes a segment from the cache.
void	removeListener(SegmentCache.SegmentCacheListener listener) Unregisters a listener from this segment cache implementation.
boolean	supportsRichIndex() Tells Mondrian whether this segment cache uses the SegmentHeader objects as an index, thus preserving them in a serialized state, or if it uses its identification number only.
void	tearDown() Tear down and clean up the cache.

Method Detail

get

SegmentBody get(SegmentHeader header)

Returns a SegmentBody once the cache has returned any results, or null if no segment corresponding to the header could be found.

Cache implementations are at liberty to 'forget' segments. Therefore it is allowable for this method to return null at any time

Parameters:

header - The header of the segment to find. Consider this as a key.

Returns:

A SegmentBody, or null if no corresponding segment could be found in cache.

getSegmentHeaders

List<SegmentHeader> getSegmentHeaders()

Returns a list of all segments present in the cache.

Returns:

A List of segment headers describing the contents of the cache.

put

boolean put(SegmentHeader header,
            SegmentBody body)

Stores a segment data in the cache.

Parameters:

header - The header of the segment.

body - The segment body to cache.

Returns:

Whether the cache write succeeded

remove

boolean remove(SegmentHeader header)

Removes a segment from the cache.

Parameters:

header - The header of the segment we want to remove.

Returns:

True if the segment was found and removed, false otherwise.

tearDown

void tearDown()

Tear down and clean up the cache.

addListener

void addListener(SegmentCache.SegmentCacheListener listener)

Adds a listener to this segment cache implementation. The listener will get notified via SegmentCache.SegmentCacheListener.SegmentCacheEvent instances.

Parameters:

listener - The listener to attach to this cache.

removeListener

void removeListener(SegmentCache.SegmentCacheListener listener)

Unregisters a listener from this segment cache implementation.

Parameters:

listener - The listener to remove.

supportsRichIndex

boolean supportsRichIndex()

Tells Mondrian whether this segment cache uses the SegmentHeader objects as an index, thus preserving them in a serialized state, or if it uses its identification number only.

Not using a rich index prevents Mondrian from doing partial cache invalidation.

It is assumed that this method returns fairly quickly, and for a given cache always returns the same value.

Returns:

Whether this segment cache preserves headers in serialized state