org.apache.shiro.realm
Class CachingRealm

java.lang.Object
  extended by org.apache.shiro.realm.CachingRealm
All Implemented Interfaces:
LogoutAware, CacheManagerAware, Realm, Nameable
Direct Known Subclasses:
AuthenticatingRealm

public abstract class CachingRealm
extends Object
implements Realm, Nameable, CacheManagerAware, LogoutAware

A very basic abstract extension point for the Realm interface that provides caching support for subclasses.

It also provides a convenience method, getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection), which is useful across all realm subclasses for obtaining a realm-specific principal/identity.

All actual Realm method implementations are left to subclasses.

Since:
0.9
See Also:
clearCache(org.apache.shiro.subject.PrincipalCollection), onLogout(org.apache.shiro.subject.PrincipalCollection), getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)

Constructor Summary
CachingRealm()
          Default no-argument constructor that defaults cachingEnabled (for general caching) to true and sets a default name based on the class name.
 
Method Summary
protected  void afterCacheManagerSet()
          Template method that may be implemented by subclasses should they wish to react to a CacheManager instance being set on the realm instance via the setCacheManager(org.apache.shiro.cache.CacheManager) mutator.
protected  void clearCache(PrincipalCollection principals)
          Clears out any cached data associated with the specified account identity/identities.
protected  void doClearCache(PrincipalCollection principals)
          This implementation does nothing - it is a template to be overridden by subclasses if necessary.
protected  Object getAvailablePrincipal(PrincipalCollection principals)
          A utility method for subclasses that returns the first available principal of interest to this particular realm.
 CacheManager getCacheManager()
          Returns the CacheManager used for data caching to reduce EIS round trips, or null if caching is disabled.
 String getName()
          Returns the (application-unique) name assigned to this Realm.
 boolean isCachingEnabled()
          Returns true if caching should be used if a CacheManager has been configured, false otherwise.
 void onLogout(PrincipalCollection principals)
          If caching is enabled, this will clear any cached data associated with the specified account identity.
 void setCacheManager(CacheManager cacheManager)
          Sets the CacheManager to be used for data caching to reduce EIS round trips.
 void setCachingEnabled(boolean cachingEnabled)
          Sets whether or not caching should be used if a CacheManager has been configured.
 void setName(String name)
          Sets the (preferably application unique) name for this component.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.shiro.realm.Realm
getAuthenticationInfo, supports
 

Constructor Detail

CachingRealm

public CachingRealm()
Default no-argument constructor that defaults cachingEnabled (for general caching) to true and sets a default name based on the class name.

Note that while in general, caching may be enabled by default, subclasses have control over if specific caching is enabled.

Method Detail

getCacheManager

public CacheManager getCacheManager()
Returns the CacheManager used for data caching to reduce EIS round trips, or null if caching is disabled.

Returns:
the CacheManager used for data caching to reduce EIS round trips, or null if caching is disabled.

setCacheManager

public void setCacheManager(CacheManager cacheManager)
Sets the CacheManager to be used for data caching to reduce EIS round trips.

This property is null by default, indicating that caching is turned off.

Specified by:
setCacheManager in interface CacheManagerAware
Parameters:
cacheManager - the CacheManager to use for data caching, or null to disable caching.

isCachingEnabled

public boolean isCachingEnabled()
Returns true if caching should be used if a CacheManager has been configured, false otherwise.

The default value is true since the large majority of Realms will benefit from caching if a CacheManager has been configured. However, memory-only realms should set this value to false since they would manage account data in memory already lookups would already be as efficient as possible.

Returns:
true if caching will be globally enabled if a CacheManager has been configured, false otherwise

setCachingEnabled

public void setCachingEnabled(boolean cachingEnabled)
Sets whether or not caching should be used if a CacheManager has been configured.

Parameters:
cachingEnabled - whether or not to globally enable caching for this realm.

getName

public String getName()
Description copied from interface: Realm
Returns the (application-unique) name assigned to this Realm. All realms configured for a single application must have a unique name.

Specified by:
getName in interface Realm
Returns:
the (application-unique) name assigned to this Realm.

setName

public void setName(String name)
Description copied from interface: Nameable
Sets the (preferably application unique) name for this component.

Specified by:
setName in interface Nameable
Parameters:
name - the preferably application unique name for this component.

afterCacheManagerSet

protected void afterCacheManagerSet()
Template method that may be implemented by subclasses should they wish to react to a CacheManager instance being set on the realm instance via the setCacheManager(org.apache.shiro.cache.CacheManager) mutator.


onLogout

public void onLogout(PrincipalCollection principals)
If caching is enabled, this will clear any cached data associated with the specified account identity. Subclasses are free to override for additional behavior, but be sure to call super.onLogout first.

This default implementation merely calls clearCache(org.apache.shiro.subject.PrincipalCollection).

Specified by:
onLogout in interface LogoutAware
Parameters:
principals - the application-specific Subject/user identifier that is logging out.
Since:
1.2
See Also:
clearCache(org.apache.shiro.subject.PrincipalCollection), getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)

clearCache

protected void clearCache(PrincipalCollection principals)
Clears out any cached data associated with the specified account identity/identities.

This implementation will return quietly if the principals argument is null or empty. Otherwise it delegates to doClearCache(org.apache.shiro.subject.PrincipalCollection).

Parameters:
principals - the principals of the account for which to clear any cached data.
Since:
1.2

doClearCache

protected void doClearCache(PrincipalCollection principals)
This implementation does nothing - it is a template to be overridden by subclasses if necessary.

Parameters:
principals - principals the principals of the account for which to clear any cached data.
Since:
1.2

getAvailablePrincipal

protected Object getAvailablePrincipal(PrincipalCollection principals)
A utility method for subclasses that returns the first available principal of interest to this particular realm. The heuristic used to acquire the principal is as follows:

Parameters:
principals - the PrincipalCollection holding all principals (from all realms) associated with a single Subject.
Returns:
the 'primary' principal attributed to this particular realm, or the fallback 'master' principal if it exists, or if not null.
Since:
1.2


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.