atg.service.collections.filter
Class CachedCollectionFilter

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.service.collections.filter.CachedCollectionFilter

All Implemented Interfaces:

NameContextBindingListener, NameContextElement, NameResolver, AdminableService, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener

Direct Known Subclasses:

ChainedFilter, ExcludeItemsInCartFilter, GiftlistSiteFilter, InventoryFilter, ItemSiteFilter, PriceAndStateFilter, StartEndDateFilter, ValidatorFilter

public abstract class CachedCollectionFilter
extends GenericService

This class provides the base implementation and interfaces for creating collection filters with cache management.

The interface provides the ability to write filters based on global and or personalized variables. Each execution of the filter is provided a profile object that can be used to vary results based on personal profile information.

When executing the filter, the caller can provide a string key (to uniquely identify the unfiltered collection).
That key will be included as part of the complete cache key.
Caching is not allowed without the collection identifier key.

Caching can also be disabled using configuration. If cache is disabled, the filter never consults, or updates the cache.

Filter implemenations must also determine if the current context is appropriate to perform its filtering. For instance, a filter that only filters if the user's home state of MA, would not perform filtering if the user's home state was CT. This type of business logic can be implemented in the shouldApplyFilter method, which is called prior to looking up results in the cache or generating a new filtered collection.

The filtered collection results is a mutable collection. If cache is enabled, adding or removing objects from the returned filtered collection will change the results in the cache. Subsequent requests to the filter using the same collection identifier key will result in returning the modified filtered collection.

See Also:

generateContextKey(java.util.Collection, java.lang.String, atg.repository.RepositoryItem), shouldApplyFilter(java.util.Collection, java.lang.String, atg.repository.RepositoryItem), isCacheEnabled(), generateFilteredCollection(java.util.Collection, java.lang.String, atg.repository.RepositoryItem)

Field Summary

static java.lang.String	CLASS_VERSION
static java.lang.String	FILTER_CACHE_COMPONENT
protected Cache	mCache
protected boolean	mCacheEnabled

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

CachedCollectionFilter()

Method Summary

void	dumpCache() This method will dump the filter cache to the system console.
java.util.Collection	filterCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile)
java.util.Collection	filterCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, boolean pConsultCache, boolean pUpdateCache) Called to create a filtered version of the unfiltered collection.
java.util.Collection	filterCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, boolean pConsultCache, boolean pUpdateCache, java.util.Map pExtraParameters) Called to create a filtered version of the unfiltered collection.
java.util.Collection	filterCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, java.util.Map pExtraParameters)
void	flushCache() This method will flush the filter cache if there is one configured.
protected CollectionCacheKey	generateCacheKey(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile) This method is called by the filterCollection method to create the CollectionCacheKey object used for cache lookup and update.
protected CollectionCacheKey	generateCacheKey(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, java.util.Map pExtraParameters) This method is called by the filterCollection method to create the CollectionCacheKey object used for cache lookup and update.
java.lang.Object	generateContextKey(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile) Generates a context key object that will be included as part of the cache key.
java.lang.Object	generateContextKey(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, java.util.Map pExtraParameters) Generates a context key object that will be included as part of the cache key.
protected java.util.Collection	generateFilteredCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile) Called by the filterCollection method to generate the filtered collection.
protected java.util.Collection	generateFilteredCollection(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, java.util.Map pExtraParameters) Called by the filterCollection method to generate the filtered collection.
protected java.util.Collection	generateNewCollectionObject(java.util.Collection pUnfilteredCollection) This method creates a new collection object of same base type as the unfiltered collection.
Cache	getCache() Returns the results cache for this filter
protected RepositoryItem	getDefaultProfile() This method is called by the filterCollection method when a profile item is not provided by the caller.
boolean	isCacheEnabled() Returns if caching is enabled.
void	setCache(Cache pCache) Sets the results cache
void	setCacheEnabled(boolean pCacheEnabled) Sets if caching is enabled
boolean	shouldApplyFilter(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile) This method is called by filterCollection prior to looking up the filtered collection in the cache or generating a new filtered collection.
boolean	shouldApplyFilter(java.util.Collection pUnfilteredCollection, java.lang.String pCollectionIdentifierKey, RepositoryItem pProfile, java.util.Map pExtraParameters) This method is called by filterCollection prior to looking up the filtered collection in the cache or generating a new filtered collection.
protected static java.lang.String	stringIt(java.util.Collection pObject)

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static final java.lang.String CLASS_VERSION

See Also:

Constant Field Values

FILTER_CACHE_COMPONENT

public static final java.lang.String FILTER_CACHE_COMPONENT

See Also:

Constant Field Values

mCache

protected Cache mCache

mCacheEnabled

protected boolean mCacheEnabled

Constructor Detail

CachedCollectionFilter

public CachedCollectionFilter()

Method Detail

getCache

public Cache getCache()

Returns the results cache for this filter

This will default to the component specified by FILTER_CACHE_COMPONENT.

See Also:

FILTER_CACHE_COMPONENT

setCache

public void setCache(Cache pCache)

Sets the results cache

isCacheEnabled

public boolean isCacheEnabled()

Returns if caching is enabled.

This method will return false if the filter does not have a cache component configured.

setCacheEnabled

public void setCacheEnabled(boolean pCacheEnabled)

Sets if caching is enabled

generateNewCollectionObject

protected java.util.Collection generateNewCollectionObject(java.util.Collection pUnfilteredCollection)
                                                    throws FilterException

This method creates a new collection object of same base type as the unfiltered collection.

Default collections types are used for types that can not be instantiated: ArrayList for instances of List and HashSet for instances of Set. E.g. classes that can not be instantiated directly:

• atg.adapter.gsa.ChangeAwareList
• atg.adapter.gsa.ChangeAwareSet
• java.util.RandomAccessSubList
• java.util.SubList

Parameters:

pUnfilteredCollection - the unfiltered collection

Returns:

a new collection object.

Throws:

FilterException - If a new collection object can not be instantiated or filter does not have access to its constructors.

generateContextKey

public java.lang.Object generateContextKey(java.util.Collection pUnfilteredCollection,
                                           java.lang.String pCollectionIdentifierKey,
                                           RepositoryItem pProfile)

Generates a context key object that will be included as part of the cache key. A context key can be used by a filter implementation to attach context information to the cache key.

For instance, a filter that creates results relative to the current date might return a date object representing today's date. Or a filter that creates results relative to gender, might return a string object of "M" of "F", depending on the current profile's gender.

Objects returned by this method will be included in the key used for cache lookup. Therefore, they should implement a hashCode and equals method when appropriate.

A null value is a valid return value for filters that don't require a specific context.

Returns:

the context key object.

generateContextKey

public java.lang.Object generateContextKey(java.util.Collection pUnfilteredCollection,
                                           java.lang.String pCollectionIdentifierKey,
                                           RepositoryItem pProfile,
                                           java.util.Map pExtraParameters)

Generates a context key object that will be included as part of the cache key. A context key can be used by a filter implementation to attach context information to the cache key.

For instance, a filter that creates results relative to the current date might return a date object representing today's date. Or a filter that creates results relative to gender, might return a string object of "M" of "F", depending on the current profile's gender.

Objects returned by this method will be included in the key used for cache lookup. Therefore, they should implement a hashCode and equals method when appropriate.

A null value is a valid return value for filters that don't require a specific context.

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key that was passed to the filterCollection method.

pProfile - the user profile

pExtraParameters - map containing key-value pairs with extra parameters

Returns:

the context key object.

generateFilteredCollection

protected java.util.Collection generateFilteredCollection(java.util.Collection pUnfilteredCollection,
                                                          java.lang.String pCollectionIdentifierKey,
                                                          RepositoryItem pProfile)
                                                   throws FilterException

Called by the filterCollection method to generate the filtered collection.

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key that was passed to the filterCollection method.

pProfile - Repository item

Returns:

the filtered collection. If null is returned from this method, the filterCollection method will return the original unfiltered collection as the filtered results. If all items are filtered from the collection, an empty collection should be returned.

Throws:

FilterException

generateFilteredCollection

protected java.util.Collection generateFilteredCollection(java.util.Collection pUnfilteredCollection,
                                                          java.lang.String pCollectionIdentifierKey,
                                                          RepositoryItem pProfile,
                                                          java.util.Map pExtraParameters)
                                                   throws FilterException

Called by the filterCollection method to generate the filtered collection.

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key that was passed to the filterCollection method.

pExtraParameters - map containing key-value pairs with extra parameters

Returns:

the filtered collection. If null is returned from this method, the filterCollection method will return the original unfiltered collection as the filtered results. If all items are filtered from the collection, an empty collection should be returned.

Throws:

FilterException

shouldApplyFilter

public boolean shouldApplyFilter(java.util.Collection pUnfilteredCollection,
                                 java.lang.String pCollectionIdentifierKey,
                                 RepositoryItem pProfile)

This method is called by filterCollection prior to looking up the filtered collection in the cache or generating a new filtered collection. Implementations should use this method to bypass the filter when it doesn't apply to the current execution context. (e.g. a profile attribute has the wrong value etc.)

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key param as passed to filterCollection

pProfile - the user profile

Returns:

false to bypass the filter prior to generating the filteredCollection, including cache lookup.

See Also:

filterCollection(java.util.Collection, java.lang.String, atg.repository.RepositoryItem, boolean, boolean)

shouldApplyFilter

public boolean shouldApplyFilter(java.util.Collection pUnfilteredCollection,
                                 java.lang.String pCollectionIdentifierKey,
                                 RepositoryItem pProfile,
                                 java.util.Map pExtraParameters)

This method is called by filterCollection prior to looking up the filtered collection in the cache or generating a new filtered collection. Implementations should use this method to bypass the filter when it doesn't apply to the current execution context. (e.g. a profile attribute has the wrong value etc.)

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key param as passed to filterCollection

pProfile - the user profile

pExtraParameters - key-value pairs with extra parameters

Returns:

false to bypass the filter prior to generating the filteredCollection, including cache lookup.

See Also:

filterCollection(java.util.Collection, java.lang.String, atg.repository.RepositoryItem, boolean, boolean)

generateCacheKey

protected CollectionCacheKey generateCacheKey(java.util.Collection pUnfilteredCollection,
                                              java.lang.String pCollectionIdentifierKey,
                                              RepositoryItem pProfile)

This method is called by the filterCollection method to create the CollectionCacheKey object used for cache lookup and update. It first calls the generateContextKey method to create the context specific key object(if any), and then creates a new instance of CollectionCacheKey using CollectionCacheKey(this,pCollectionIdentifierKey,contextKey).

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key that is was provided on the call to filterCollection

pProfile - the profile repository item.

Returns:

the CollectionCacheKey used for cache lookup and update.

See Also:

generateContextKey(java.util.Collection, java.lang.String, atg.repository.RepositoryItem), CollectionCacheKey

generateCacheKey

protected CollectionCacheKey generateCacheKey(java.util.Collection pUnfilteredCollection,
                                              java.lang.String pCollectionIdentifierKey,
                                              RepositoryItem pProfile,
                                              java.util.Map pExtraParameters)

This method is called by the filterCollection method to create the CollectionCacheKey object used for cache lookup and update. It first calls the generateContextKey method to create the context specific key object(if any), and then creates a new instance of CollectionCacheKey using CollectionCacheKey(this,pCollectionIdentifierKey,contextKey).

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the key that is was provided on the call to filterCollection

pProfile - the profile repository item.

pExtraParameters - key-value pairs with extra parameters

Returns:

the CollectionCacheKey used for cache lookup and update.

See Also:

generateContextKey(java.util.Collection, java.lang.String, atg.repository.RepositoryItem), CollectionCacheKey

getDefaultProfile

protected RepositoryItem getDefaultProfile()

This method is called by the filterCollection method when a profile item is not provided by the caller.

Returns:

the current session profile

filterCollection

public java.util.Collection filterCollection(java.util.Collection pUnfilteredCollection,
                                             java.lang.String pCollectionIdentifierKey,
                                             RepositoryItem pProfile,
                                             boolean pConsultCache,
                                             boolean pUpdateCache)
                                      throws FilterException

Called to create a filtered version of the unfiltered collection.

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the string that uniquely identifies the unfilterd collection. This string will be included as part of the complete key for cache lookup.

pProfile - the profile repository item.

pConsultCache - if true the cache is first consulted for filtered results

pUpdateCache - if true the cache is updated with the new filtered collection.

Returns:

the filtered collection

Throws:

FilterException

filterCollection

public java.util.Collection filterCollection(java.util.Collection pUnfilteredCollection,
                                             java.lang.String pCollectionIdentifierKey,
                                             RepositoryItem pProfile,
                                             boolean pConsultCache,
                                             boolean pUpdateCache,
                                             java.util.Map pExtraParameters)
                                      throws FilterException

Called to create a filtered version of the unfiltered collection.

Parameters:

pUnfilteredCollection - the unfiltered collection

pCollectionIdentifierKey - the string that uniquely identifies the unfilterd collection. This string will be included as part of the complete key for cache lookup.

pProfile - the profile repository item.

pConsultCache - if true the cache is first consulted for filtered results

pUpdateCache - if true the cache is updated with the new filtered collection.

pExtraParameters - key-value pairs with extra parameters

Returns:

the filtered collection

Throws:

FilterException

filterCollection

public java.util.Collection filterCollection(java.util.Collection pUnfilteredCollection,
                                             java.lang.String pCollectionIdentifierKey,
                                             RepositoryItem pProfile)
                                      throws FilterException

Throws:

FilterException

See Also:

filterCollection(java.util.Collection, java.lang.String, atg.repository.RepositoryItem, boolean, boolean)

filterCollection

public java.util.Collection filterCollection(java.util.Collection pUnfilteredCollection,
                                             java.lang.String pCollectionIdentifierKey,
                                             RepositoryItem pProfile,
                                             java.util.Map pExtraParameters)
                                      throws FilterException

Throws:

FilterException

See Also:

filterCollection(java.util.Collection, java.lang.String, atg.repository.RepositoryItem, boolean, boolean)

stringIt

protected static java.lang.String stringIt(java.util.Collection pObject)

flushCache

public void flushCache()

This method will flush the filter cache if there is one configured.

See Also:

Cache.flush()

dumpCache

public void dumpCache()

This method will dump the filter cache to the system console.

See Also:

Cache.dump(java.io.PrintStream)