org.apache.stanbol.entityhub.servicesapi.yard
Interface Cache

All Superinterfaces:

Yard

public interface Cache
extends Yard

The Cache is a mediator between a Yard storing the cached information and the Site acting as access point to a referenced information source.

This interface provides also access to the configuration of the cache. This includes meta data needed to decide if requested information can be retrieved by using the cache or if data need to be requested directly by the referenced site. This includes mainly cached fields used CacheStrategy for fields as well as cached languages. This may be extended in future versions.

It is important, that the configuration of the cache is stored within the Yard together with all the other cached information, because it MUST BE possible to copy&paste cached information to an other Entityhub instance. This requirements enables the initialisation of a Cache only based on the information stored within the cache.

Cache instances should be instantiated automatically by Sites based on there configuration. The only parameter needed for the initialisation of a Cache is the id of the yard (Yard.getId()). However note that the Cache is not responsible to create, configure nor activate the Yard. If the Yard for an cache is not active the cache returns false on calls to isAvailable().

Author:

Rupert Westenthaler

Field Summary

static String	ADDITIONAL_CONFIGURATION_URI The ID used to store the configuration used for the creation of new items in the cache.
static String	ADDITIONAL_MAPPINGS Key used to configure additional mappings for a cache
static String	BASE_CONFIGURATION_URI The ID used to store the configuration used for the creation of the cache.
static String	CACHE_STRATEGY They key used to configure the cache strategy
static String	CACHE_YARD Key used to store the id of the Yard used as cache
static String	FIELD_MAPPING_CONFIG_FIELD The field used to store the fieldMappings of a CacheConfiguration

Fields inherited from interface org.apache.stanbol.entityhub.servicesapi.yard.Yard

DESCRIPTION, ID, NAME

Method Summary

FieldMapper	getAdditionalMappings() Getter for the additional mappings used by this Cache.
FieldMapper	getBaseMappings() Getter for the base mappings used by this Cache.
boolean	isAvailable() Getter for the state of the Yard configured to store cached information
CacheStrategy	isField(String field) Returns the cache strategy for the given Field.
CacheStrategy	isLanguage(String lang) Returns the cache strategy for the given Language
void	setAdditionalMappings(FieldMapper fieldMapper) Sets the additional field mappings for a cache.
void	setBaseMappings(FieldMapper fieldMapper) Sets the base mappings to the parsed field mapper and stores the new configuration to the yard.
CacheStrategy	strategy() The strategy used by this Cache.

Methods inherited from interface org.apache.stanbol.entityhub.servicesapi.yard.Yard

create, create, find, findReferences, findRepresentation, getDescription, getId, getName, getQueryFactory, getRepresentation, getValueFactory, isRepresentation, remove, remove, removeAll, store, store, update, update

Field Detail

CACHE_YARD

static final String CACHE_YARD

Key used to store the id of the Yard used as cache

See Also:

Constant Field Values

BASE_CONFIGURATION_URI

static final String BASE_CONFIGURATION_URI

The ID used to store the configuration used for the creation of the cache. This configuration can only be changed by updating all the cached items.

See Also:

Constant Field Values

ADDITIONAL_CONFIGURATION_URI

static final String ADDITIONAL_CONFIGURATION_URI

The ID used to store the configuration used for the creation of new items in the cache. This configuration is called additional, because it can only define additional information to be cached. This restriction is important because the base base configuration is used to determine if queries can be answered by the cache. So it MUST BE ensured that also documents updated in the cache confirm to the base configuration.

See Also:

Constant Field Values

FIELD_MAPPING_CONFIG_FIELD

static final String FIELD_MAPPING_CONFIG_FIELD

The field used to store the fieldMappings of a CacheConfiguration

See Also:

Constant Field Values

CACHE_STRATEGY

static final String CACHE_STRATEGY

They key used to configure the cache strategy

See Also:

Constant Field Values

ADDITIONAL_MAPPINGS

static final String ADDITIONAL_MAPPINGS

Key used to configure additional mappings for a cache

See Also:

Constant Field Values

Method Detail

isField

CacheStrategy isField(String field)

Returns the cache strategy for the given Field.

• CacheStrategy.all indicates that this field is cached for all Representations within the cache.
• CacheStrategy.used indicates that this field is only present for some Representations within the cache.
• CacheStrategy.none indicates that this field is ignored by the cache.

Parameters:

field - the field

Returns:

the cache strategy for this field

isLanguage

CacheStrategy isLanguage(String lang)

Returns the cache strategy for the given Language

• CacheStrategy.all indicates that this language is cached for all Representations within the cache.
• CacheStrategy.used indicates that this language is only present for some Representations within the cache.
• CacheStrategy.none indicates that this language is ignored by the cache.

Parameters:

lang - the language

Returns:

the cache strategy for this language

strategy

CacheStrategy strategy()

The strategy used by this Cache.

CacheStrategy.all indicates that one can assume that this cache holds at least some data for all Representations of the cached referenced site.

CacheStrategy.used indicates that this cache holds only previously used entities of the referenced site.

CacheStrategy.none indicates that this cache holds no data of the ReferencedSite. This value is normally not used by a real cache implementation. One needs to use isField(String) and isLanguage(String) to check how specific fields are treated by the cahce.

e.g. a cache may store dc:titel and dc:author for all documents, but all other fields only for previously used items. In such cases this method would return CacheStrategy.all but a call to isField("dc:description") would return CacheStrategy.used.

This would indicate, that queries for titles and authors could be executed by using the cache. Queries that also searches for dc:descriptions would need to be performed directly on the referenced site.

Returns:

the strategy

isAvailable

boolean isAvailable()

Getter for the state of the Yard configured to store cached information

Returns:

true if the yard used by this cache is available (active).

setBaseMappings

void setBaseMappings(FieldMapper fieldMapper)
                     throws YardException

Sets the base mappings to the parsed field mapper and stores the new configuration to the yard. If the #baseMapper is null this method removes any existing configuration from the yard.

NOTE: (Expert Usage only)Take care if using this method! The base configuration MUST BE in correspondence with the cached data! Typically this configuration is set by the code that creates a Full-Cache (CacheStrategy.all) for an entity source (referenced site) and is not modified later on. Changes to the base configuration usually requires all entities in the cache to be updated!

Parameters:

fieldMapper - the fieldMapper holding the new base field mapping configuration

Throws:

YardException - on any error while storing the new configuration. The new configuration is not set if storage is not successful to prevent an configuration that do not correspond with the cached information in the yard.

setAdditionalMappings

void setAdditionalMappings(FieldMapper fieldMapper)
                           throws YardException

Sets the additional field mappings for a cache. This mapping defines fields that are cached in addition to that defined by the base mapping when Representation of entities are stored/updated in the cache.

Changing the additional mappings will only influence documents stored/ updated in the cache after the change. Already cached documents are not affected changed. This means, that by changing this configuration a cache will contain documents written by using different configurations. To avoid that one needs to delete all documents in the cache.

However changes to this configuration can not affect the base configuration of the cache, because base mappings cannot be undone by this configuration.

Note that typically Caches used for Sites using the CacheStrategy.used do not define any base configuration. Also note that setting the additional mappings to null means:

• using the base configuration if one is present or
• storing all data of the parsed Representations if no base configuration is present.

Parameters:

fieldMapper - the fieldMapper holding the new additional field mapping configuration

Throws:

YardException - on any error while storing the new configuration. The new configuration is not set if storage is not successful to prevent an configuration that do not correspond with the cached information in the yard.

getAdditionalMappings

FieldMapper getAdditionalMappings()

Getter for the additional mappings used by this Cache. Modifications on the returned object do not have any influence on the mappings, because this method returns a clone. Use setAdditionalMappings(FieldMapper) to change the used additional mappings. However make sure you understand the implications of changing the base mappings as described in the documentation of the setter method

Returns:

A clone of the additional mappings or null if no additional mappings are defined

getBaseMappings

FieldMapper getBaseMappings()

Getter for the base mappings used by this Cache. Modifications on the returned object do not have any influence on the mappings, because this method returns a clone. Use setBaseMappings(FieldMapper) to change the used base mappings. However make sure you understand the implications of changing the base mappings as described in the documentation of the setter method

Returns:

A clone of the base mappings or null if no base mappings are defined