oracle.jsp.jwcache
Class CachePolicy

java.lang.Object
  |
  +--oracle.jsp.jwcache.CachePolicy

public class CachePolicy

extends java.lang.Object

implements java.io.Serializable

CachePolicy is a class that represents a cache policy in Oracle Java Web Cache. Apart from holding cache policy attributes, such as, "selected parameters", expiration policy and cache repository name, a CachePolicy object also have methods for cache operation, e.g. putCache and getCache to store and get cache through the cache policy. A cache policy object is constructed upon usage of OracleJSP cache tag. All cache operations are performed through this CachePolicy.

See Also:

Serialized Form

Field Summary

Type	Field
static int	AUTO_INVALIDATE_APP_LEVEL AUTO_INVALIDATE_APP_LEVEL is the integer constant that represents the application invalidate level for automatic naming cache (i.e.
static java.lang.String	AUTO_INVALIDATE_APP_LEVEL_STR AUTO_INVALIDATE_APP_LEVEL_STR is the string constant that represents the application invalidate level for automatic naming cache (i.e.
static int	AUTO_INVALIDATE_COOKIE_LEVEL AUTO_INVALIDATE_COOKIE_LEVEL is the integer constant that represents the cookie invalidate level for automatic naming cache (i.e.
static java.lang.String	AUTO_INVALIDATE_COOKIE_LEVEL_STR AUTO_INVALIDATE_COOKIE_LEVEL_STR is the string constant that represents the cookie invalidate level for automatic naming cache (i.e.
static int	AUTO_INVALIDATE_PAGE_LEVEL AUTO_INVALIDATE_PAGE_LEVEL is the integer constant that represents the page invalidate level for automatic naming cache (i.e.
static java.lang.String	AUTO_INVALIDATE_PAGE_LEVEL_STR AUTO_INVALIDATE_PAGE_LEVEL_STR is the string constant that represents the page invalidate level for automatic naming cache (i.e.
static int	AUTO_INVALIDATE_PARAM_LEVEL AUTO_INVALIDATE_PARAM_LEVEL is the integer constant that represents the parameter invalidate level for automatic naming cache (i.e.
static java.lang.String	AUTO_INVALIDATE_PARAM_LEVEL_STR AUTO_INVALIDATE_PARAM_LEVEL_STR is the string constant that represents the parameter invalidate level for automatic naming cache (i.e.
static int	AUTO_INVALIDATE_UNDEFINED AUTO_INVALIDATE_UNDEFINED is the integer constant that represents the undefined invalidate level for automatic naming cache (i.e.
static java.lang.String	CACHE_POLICIES internal name of the table of cache policy objects used in servlet context
static java.lang.String	CACHE_REPOS internal name of the table of cache repository objects used in servlet context
static java.lang.String	CACHENAME_AUTO the internal string constant used in generating the internal name of caches which is NOT under TYPE_USERSPECIFIED.
static java.lang.String	CACHENAME_USER the internal string constant used in generating the internal name of caches which is under TYPE_USERSPECIFIED.
static java.lang.String	DEFAULT_REPO_NAME the name of the default cache repository
static int	REUSABLE_ALWAYS the integer constant to specify the cache is always reusable if it exists / it has not expired yet.
static java.lang.String	REUSABLE_IGNORED the String constant used to specify "ignored" values in reusableTimeStamp and reusableDeltaTime
static int	SCOPE_APP the integer constant to specify the scope of cache as application / servlet context
static java.lang.String	SCOPE_APP_STR the string constant to specify the scope of cache as applcation / servlet context
static int	SCOPE_SESSION the integer constant to specify the scope of cache as HTTP session
static java.lang.String	SCOPE_SESSION_STR the string constant to specify the scope of cache as HTTP session
static java.lang.String	SECTION_ID internal name of auto counter section id of JSP cache fragments used in pageContext
static java.lang.String	SESSION_CACHE_REPO internal name of the HTTP-session-scoped cache repository used in HTTP session
static java.lang.String[]	TYPE_STRS the array of string constants that represents different types of cache policy
static int	TYPE_URI_ALLPARAM the integer constant to specify the cache policy type as URI plus all parameters naming
static int	TYPE_URI_EXCLUDEDPARAM the integer constant to specify the cache policy type as URI plus excluded parameters naming
static int	TYPE_URI_ONLY the integer constant to specify the cache policy type as URI only naming
static int	TYPE_URI_QUERYSTR the integer constant to specify the cache policy type as URI plus query string naming
static int	TYPE_URI_SELECTEDPARAM the integer constant to specify the cache policy type as URI plus selected parameters naming
static int	TYPE_USERSPECIFIED the integer constant to specify the cache policy type as user specified naming

Constructor Summary

Type	Constructor
	CachePolicy(CachePolicy cPolicy) copy constructor of cache policy
	CachePolicy(javax.servlet.ServletConfig config) Default cache policy constructor
protected	CachePolicy(javax.servlet.ServletConfig config, boolean attrChanged, boolean ignoreCache, int scope, int autoType, java.lang.String[] selectedParameters, java.lang.String[] selectedCookies, long reusableTimeStamp, long reusableDeltaTime, ExpirationPolicy expirationPolicyObj, java.lang.String repoName, boolean reportException) a protected cache policy constructor that accepts each member as an individual argument.
	CachePolicy(javax.servlet.ServletConfig config, CachePolicy cPolicy) copy constructor of cache policy with an overriding servlet config object.

Method Summary

Type	Method
static int	autoInvalidateStrToLevelInt(java.lang.String s) the convenient method to convert the AUTO INVALIDATE LEVEL String to the corresponding the AUTO INVALIDATE LEVEL integer constant, which is used in invalidateCacheLike method.
boolean	getAttrChanged() a public method used to check whether an attribute of cache policy is changed since construction / creation
CacheBlock	getAutoCacheForOtherPath(javax.servlet.http.HttpServletRequest req, java.lang.String otherPath, javax.servlet.http.Cookie[] newCookies, StringSectionId sectionId) get a cache entry for a specified string-based section id for the specified page path.
CacheBlock	getAutoCacheForOtherPath(javax.servlet.http.HttpServletRequest req, java.lang.String otherPath, StringSectionId sectionId) get a cache entry for a specified string-based section id for the specified page path.
int	getAutoType() to get the type of this cache policy.
CacheBlock	getCache(javax.servlet.http.HttpServletRequest req, SectionId sectionId) to get the cache block (as CacheBlock) object) through this cache policy.
CacheBlock	getCache(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName) to get the cache block (as CacheBlock) object) through this cache policy.
CacheBlock	getCache(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName, SectionId sectionId) to get the cache block (as CacheBlock) object) through this cache policy.
java.lang.String	getCacheRepositoryName() to get the cache repository name used in this cache policy
java.util.Date	getCurrentTime() to get the current time from the cache repository specified in this cache policy.
java.lang.String	getDebugCacheName(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName, SectionId sectionId) to generate the internal (for advanced debug purpose) cache name (most users do not need to call this function.)
ExpirationPolicy	getExpirationPolicy() to get the expiration policy object
boolean	getIgnoreCache() to check whether cache is always ignored
boolean	getReportException() to get the value of reportException flag.
long	getReusableDeltaTime() to get the reusable delta time
java.util.Date	getReusableTimeStamp() to get the reusable time stamp
int	getScope() to get the scope of the cache policy: session or application.
java.lang.String[]	getSelectedCookies() to get the String array of selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM
java.lang.String[]	getSelectedParam() to get the array of selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM.
void	invalidateCache(javax.servlet.http.HttpServletRequest req, SectionId sectionId) to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters
void	invalidateCache(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName) to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters
void	invalidateCache(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName, SectionId sectionId) to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters
void	invalidateCacheLike(javax.servlet.http.HttpServletRequest req, int autoInvalidateLevel) to invalidate a collection of cache blocks through this cache policy that matches with given paramaters
void	invalidateCacheLike(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName) to invalidate a collection of cache blocks through this cache policy that matches with given paramaters
void	invalidateCacheLike(javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName, int autoInvalidateLevel) to invalidate a collection of cache blocks through this cache policy that matches with given paramaters
void	invalidateCacheOtherPathLike(javax.servlet.http.HttpServletRequest req, java.lang.String otherPath) invalidate the caches of another page, not the one associated with the current request.
void	invalidateCacheOtherPathLike(javax.servlet.http.HttpServletRequest req, java.lang.String otherPath, javax.servlet.http.Cookie[] newCookies, int autoInvalidateLevel) invalidate the caches of another page, not the one associated with the current request.
boolean	isRecent(CacheBlock block) to test with a cache block is recent enough to reuse according to the reusableTimeStamp and reusableDeltaTime attribute, where reusableTimeStamp takes precedence over reusableDeltaTime.
void	markupBegin(javax.servlet.ServletContext sc, javax.servlet.http.HttpServletRequest req, java.io.Writer out, java.lang.String specifiedName, SectionId sectionId) an API to markup the beginning of a cache block; mainly for future integration with downstream level-3 caching; not being used by external users as of this version
void	markupEnd(javax.servlet.ServletContext sc, javax.servlet.http.HttpServletRequest req, java.io.Writer out, java.lang.String specifiedName, SectionId sectionId) an API to markup the end of a cache block; mainly for future integration with downstream level-3 caching; not being used by external users as of this version
static java.lang.String[]	parseSpaceDelimitedString(java.lang.String s) a convenient method to parse a space delimited String into a String array
void	putAutoCacheForOtherPath(java.lang.Object obj, javax.servlet.http.HttpServletRequest req, java.lang.String otherPath, javax.servlet.http.Cookie[] newCookies, StringSectionId sectionId) put a cache entry for a specified string-based section id for the specified page path.
void	putAutoCacheForOtherPath(java.lang.Object obj, javax.servlet.http.HttpServletRequest req, java.lang.String otherPath, StringSectionId sectionId) put a cache entry for a specified string-based section id for the specified page path.
void	putCache(java.lang.Object obj, javax.servlet.http.HttpServletRequest req, SectionId sectionId) to put an object into the cache repository through this cache policy.
void	putCache(java.lang.Object obj, javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName) to put an object into the cache repository through this cache policy.
void	putCache(java.lang.Object obj, javax.servlet.http.HttpServletRequest req, java.lang.String specifiedName, SectionId sectionId) to put an object into the cache repository through this cache policy.
protected void	resetAttrChanged() a protected method used internally to mark an attribute of cache policy is NOT changed since construction / creation
protected void	setAttrChanged() a protected method used internally to mark an attribute of cache policy is changed since construction / creation
void	setAutoType(int autoType) to set the type of this cache policy with an integer parameter
void	setAutoType(java.lang.String s) to set type of this cache policy with a String parameter
void	setCacheRepositoryName(java.lang.String repoName) to set the cache repository name used in this cache policy (the definition of cache repository, including the name, is specified in /WEB-INF/wcache.xml)
void	setExpirationPolicy(ExpirationPolicy expirationPolicyObj) to set the expiration policy of this cache policy
void	setIgnoreCache(boolean ignoreCache) to set whether cache is always ignored
void	setIgnoreCache(java.lang.String v) to set whether cache is always ignored
void	setReportException(boolean reportException) to set whether a CacheRuntimeException is generated during cache operations.
void	setReportException(java.lang.String reportExceptionStr) to set whether a CacheRuntimeException is generated during cache operations.
void	setReusableDeltaTime(long reusableDeltaTime) to set the reusable delta time
void	setReusableDeltaTime(java.lang.String s) to set the reusable delta time
void	setReusableTimeStamp(java.util.Date reusableTimeStamp) to set the reusable time stamp
void	setReusableTimeStamp(long reusableTimeStamp) to set the reusable time stamp
void	setReusableTimeStamp(java.lang.String s) to set the reusable time stamp
void	setScope(int scope) to set the scope of this cache policy: session or application with an integer parameter.
void	setScope(java.lang.String s) to set the scope of this cache policy: session or application with a String parameter
void	setSelectedCookies(java.lang.String selectedCookiesStr) to set the selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM
void	setSelectedCookies(java.lang.String[] selectedCookies) to set the String array of selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM
void	setSelectedParam(java.lang.String selectedParamStr) to set the selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM
void	setSelectedParam(java.lang.String[] selectedParameters) to set the selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM
static java.util.Enumeration	sortEnum(java.util.Enumeration enum) a convenient method to sort an Enumeration of Strings
java.lang.String	toString() to generate the string of description of this cache policy in XML format

Methods inherited from class java.lang.Object

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

Field Detail

SCOPE_SESSION

public static final int SCOPE_SESSION

the integer constant to specify the scope of cache as HTTP session

SCOPE_APP

public static final int SCOPE_APP

the integer constant to specify the scope of cache as application / servlet context

SCOPE_SESSION_STR

public static final java.lang.String SCOPE_SESSION_STR

the string constant to specify the scope of cache as HTTP session

SCOPE_APP_STR

public static final java.lang.String SCOPE_APP_STR

the string constant to specify the scope of cache as applcation / servlet context

TYPE_USERSPECIFIED

public static final int TYPE_USERSPECIFIED

the integer constant to specify the cache policy type as user specified naming

TYPE_URI_ONLY

public static final int TYPE_URI_ONLY

the integer constant to specify the cache policy type as URI only naming

TYPE_URI_QUERYSTR

public static final int TYPE_URI_QUERYSTR

the integer constant to specify the cache policy type as URI plus query string naming

TYPE_URI_ALLPARAM

public static final int TYPE_URI_ALLPARAM

the integer constant to specify the cache policy type as URI plus all parameters naming

TYPE_URI_SELECTEDPARAM

public static final int TYPE_URI_SELECTEDPARAM

the integer constant to specify the cache policy type as URI plus selected parameters naming

TYPE_URI_EXCLUDEDPARAM

public static final int TYPE_URI_EXCLUDEDPARAM

the integer constant to specify the cache policy type as URI plus excluded parameters naming

TYPE_STRS

public static final java.lang.String[] TYPE_STRS

the array of string constants that represents different types of cache policy

DEFAULT_REPO_NAME

public static final java.lang.String DEFAULT_REPO_NAME

the name of the default cache repository

CACHE_REPOS

public static final java.lang.String CACHE_REPOS

internal name of the table of cache repository objects used in servlet context

CACHE_POLICIES

public static final java.lang.String CACHE_POLICIES

internal name of the table of cache policy objects used in servlet context

SECTION_ID

public static final java.lang.String SECTION_ID

internal name of auto counter section id of JSP cache fragments used in pageContext

SESSION_CACHE_REPO

public static final java.lang.String SESSION_CACHE_REPO

internal name of the HTTP-session-scoped cache repository used in HTTP session

REUSABLE_ALWAYS

public static final int REUSABLE_ALWAYS

the integer constant to specify the cache is always reusable if it exists / it has not expired yet. This integer constant can be used with reusableTimeStamp or reusableDeltaTime.

REUSABLE_IGNORED

public static final java.lang.String REUSABLE_IGNORED

the String constant used to specify "ignored" values in reusableTimeStamp and reusableDeltaTime

CACHENAME_USER

public static final java.lang.String CACHENAME_USER

the internal string constant used in generating the internal name of caches which is under TYPE_USERSPECIFIED.

CACHENAME_AUTO

public static final java.lang.String CACHENAME_AUTO

the internal string constant used in generating the internal name of caches which is NOT under TYPE_USERSPECIFIED.

AUTO_INVALIDATE_UNDEFINED

public static final int AUTO_INVALIDATE_UNDEFINED

AUTO_INVALIDATE_UNDEFINED is the integer constant that represents the undefined invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

Background
With automatic cache naming (i.e. NON-TYPE_USERSPECIFIED), any cache block within a page will be stored under a hierachy. The hierarachy has levels in the following sequence:

• first level: application
• second level: page
• third level: parameter
• fourth level: cookie

For example, here is a request to a page:
http://host1:port1/myapp/dir1/dir2/abc.jsp?p1=v1&p2=v2
Cookie: cookiename1=cookievalue1; cookiename2=cookievalue2
The request is to a "/dir1/dir2/abc.jsp" page under application "myapp" at host1 machine and port1 port number. The request is made with two parameters: "p1=v1&p2=v2" and two cookies (mentioned above).

Cache blocks associated with this request will be stored under a hierarachy in the following sequence:

• first level: application "myapp"
• second level: page "/dir1/dir2/abc.jsp"
• third level: parameter "p1=v1&p2=v2"
• fourth level: cookie "cookiename1=cookievalue1; cookiename2=cookievalue2

When an invalidateCacheLike operation is performed with an automatic naming cache policy, an invalidation level can be passed as a parameter. When an invalidateCacheLike is performed with the request of the above example with the invalidation level of:

• application: all caches of all pages under this "myapp" application will be invalidated, including caches in other pages.
• page: all caches of this page "/dir1/dir2/abc.jsp" will be invalidated, including caches of requests of other parameters of this page
• parameter: all caches of all requests to this page with this parameter list "p1=v1&p2=v2" will be invalidated, including caches of requests to this page with this parameter list but with other cookie values
• cookie level: caches of this request will be invalidated; only caches of requests for the same page, same selected HTTP parameters list, same selected cookie list under the same application will be invalidated.

AUTO_INVALIDATE_APP_LEVEL

public static final int AUTO_INVALIDATE_APP_LEVEL

AUTO_INVALIDATE_APP_LEVEL is the integer constant that represents the application invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_PAGE_LEVEL

public static final int AUTO_INVALIDATE_PAGE_LEVEL

AUTO_INVALIDATE_PAGE_LEVEL is the integer constant that represents the page invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_PARAM_LEVEL

public static final int AUTO_INVALIDATE_PARAM_LEVEL

AUTO_INVALIDATE_PARAM_LEVEL is the integer constant that represents the parameter invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_COOKIE_LEVEL

public static final int AUTO_INVALIDATE_COOKIE_LEVEL

AUTO_INVALIDATE_COOKIE_LEVEL is the integer constant that represents the cookie invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_APP_LEVEL_STR

public static final java.lang.String AUTO_INVALIDATE_APP_LEVEL_STR

AUTO_INVALIDATE_APP_LEVEL_STR is the string constant that represents the application invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_PAGE_LEVEL_STR

public static final java.lang.String AUTO_INVALIDATE_PAGE_LEVEL_STR

AUTO_INVALIDATE_PAGE_LEVEL_STR is the string constant that represents the page invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_PARAM_LEVEL_STR

public static final java.lang.String AUTO_INVALIDATE_PARAM_LEVEL_STR

AUTO_INVALIDATE_PARAM_LEVEL_STR is the string constant that represents the parameter invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

AUTO_INVALIDATE_COOKIE_LEVEL_STR

public static final java.lang.String AUTO_INVALIDATE_COOKIE_LEVEL_STR

AUTO_INVALIDATE_COOKIE_LEVEL_STR is the string constant that represents the cookie invalidate level for automatic naming cache (i.e. NON-TYPE_USERSPECIFIED).

Constructor Detail

CachePolicy

public CachePolicy(javax.servlet.ServletConfig config)

Default cache policy constructor

By default, the scope is application; type is "all parameters"; always resuse cache; using default expiration policy and default cache repository; report runtime exception.

Parameters:

config - the servlet config object used in this cache policy

CachePolicy

public CachePolicy(CachePolicy cPolicy)

copy constructor of cache policy

CachePolicy

public CachePolicy(javax.servlet.ServletConfig config,
                   CachePolicy cPolicy)

copy constructor of cache policy with an overriding servlet config object.

This constructor will copy all fields of the given cache policy, except the servlet config object. This constructor will use the given servlet config object instead.

CachePolicy

protected CachePolicy(javax.servlet.ServletConfig config,
                      boolean attrChanged,
                      boolean ignoreCache,
                      int scope,
                      int autoType,
                      java.lang.String[] selectedParameters,
                      java.lang.String[] selectedCookies,
                      long reusableTimeStamp,
                      long reusableDeltaTime,
                      ExpirationPolicy expirationPolicyObj,
                      java.lang.String repoName,
                      boolean reportException)

a protected cache policy constructor that accepts each member as an individual argument. This constructor is not being used by external users directly.

Method Detail

setAttrChanged

protected void setAttrChanged()

a protected method used internally to mark an attribute of cache policy is changed since construction / creation

resetAttrChanged

protected void resetAttrChanged()

a protected method used internally to mark an attribute of cache policy is NOT changed since construction / creation

getAttrChanged

public boolean getAttrChanged()

a public method used to check whether an attribute of cache policy is changed since construction / creation

Returns:

the boolean value of whether an attribute is changed since creation

getIgnoreCache

public boolean getIgnoreCache()

to check whether cache is always ignored

Returns:

the boolean value of whether cache is always ignored

setIgnoreCache

public void setIgnoreCache(boolean ignoreCache)

to set whether cache is always ignored

Parameters:

ignoreCache - the boolean parameter of this setter method

setIgnoreCache

public void setIgnoreCache(java.lang.String v)

to set whether cache is always ignored

Parameters:

ignoreCache - the String parameter of this setter method

getScope

public int getScope()

to get the scope of the cache policy: session or application.

Please refer to the SCOPE_* constants defined in this class.

Returns:

the integer value that represents the scope of this cache policy

setScope

public void setScope(int scope)

to set the scope of this cache policy: session or application with an integer parameter.

Please refer to the SCOPE_* constants defined in this class.

Parameters:

scope - the integer parameter that set the scope of this cache policy

setScope

public void setScope(java.lang.String s)

to set the scope of this cache policy: session or application with a String parameter

Please refer to the SCOPE_* constants defined in this class.

Parameters:

scope - the String parameter that set the scope of this cache policy

getAutoType

public int getAutoType()

to get the type of this cache policy.

Please refer to the TYPE_* constants defined in this class.

Returns:

the integer value that represents the type of this cache policy.

setAutoType

public void setAutoType(int autoType)

to set the type of this cache policy with an integer parameter

Please refer to the TYPE_* constants defined in this class.

Parameters:

autoType - the integer parameter that specifies the type of this cache policy

setAutoType

public void setAutoType(java.lang.String s)

to set type of this cache policy with a String parameter

Please refer to the TYPE_* constants defined in this class.

Parameters:

s - the String parameter that specifies the type of this cache policy

parseSpaceDelimitedString

public static java.lang.String[] parseSpaceDelimitedString(java.lang.String s)

a convenient method to parse a space delimited String into a String array

getSelectedParam

public java.lang.String[] getSelectedParam()

to get the array of selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM.

Returns:

a String array of selected HTTP parameters

setSelectedParam

public void setSelectedParam(java.lang.String[] selectedParameters)

to set the selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM

Parameters:

selectedParameters - the String array that specifies HTTP parameters to set in this cache policy

setSelectedParam

public void setSelectedParam(java.lang.String selectedParamStr)

to set the selected HTTP parameters of this cache policy used in TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM

Parameters:

selectedParamStr - the space delimited String that specifies a list of HTTP parameters to set in this cache policy

getSelectedCookies

public java.lang.String[] getSelectedCookies()

to get the String array of selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM

Returns:

the String array of selected cookies of this cache policy

setSelectedCookies

public void setSelectedCookies(java.lang.String[] selectedCookies)

to set the String array of selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM

Parameters:

selectedCookies - the String array of selected cookies to set

setSelectedCookies

public void setSelectedCookies(java.lang.String selectedCookiesStr)

to set the selected cookies of this cache policy used in TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM and TYPE_URI_EXCLUDEDPARAM

Parameters:

selectedCookiesStr - the space delimited String that specifies the selected cookies to set

getReusableTimeStamp

public java.util.Date getReusableTimeStamp()

to get the reusable time stamp

Reusable time stamp is different from TTL in expiration policy. It does not affect the putCache or getCache operations. It does not affect the life span of cache. It affects the result of isRecent function, which is used in JSP Java Web Cache tags (e.g. <ojsp:cache >).

If the creation time of cache is more recent than the reusable time stamp, then that piece of cache will be recent enough (i.e. isRecent call) to be reused in JSP tags. Otherwise, when this cache policy is used as JSP tags, the logic of generating a fresh content will be re-executed. But, the newly generated content will NOT replace the existing copy of cache.

Returns:

to get the reusable time stamp in java.util.Date

setReusableTimeStamp

public void setReusableTimeStamp(java.util.Date reusableTimeStamp)

to set the reusable time stamp

For the semantics of reusable time stamp, please refer to getReusableTimeStamp

Parameters:

reusableTimeStamp - the java.util.Date parameter to set the reusable time stamp of this cache policy.

setReusableTimeStamp

public void setReusableTimeStamp(long reusableTimeStamp)

to set the reusable time stamp

For the semantics of reusable time stamp, please refer to getReusableTimeStamp

Parameters:

reusableTimeStamp - the long parameter to set the reusable time stamp of this cache policy. The long value will be converted to java.util.Date internally.

setReusableTimeStamp

public void setReusableTimeStamp(java.lang.String s)
                          throws java.text.ParseException

to set the reusable time stamp

For the semantics of reusable time stamp, please refer to getReusableTimeStamp

Parameters:

s - the String parameter to set the reusable time stamp of this cache policy. The long value will be converted to java.util.Date internally with one of the following date format strings:

• yyyy.MM.dd hh:mm:ss z
• yyyy.MM.dd hh:mm:ss
• yyyy.MM.dd

It also accepts "ignored" special string constant.

getReusableDeltaTime

public long getReusableDeltaTime()

to get the reusable delta time

Reusable delta time is similar reusable time stamp. It is different from TTL in expiration policy. It does not affect the putCache or getCache operations. It does not affect the life span of cache. It affects the result of isRecent function, which is used in JSP Java Web Cache tags (e.g. <ojsp:cache >).

If the difference between the creation time of cache and the current time is smaller than the reusable delta time, then that piece of cache will be recent enough (i.e. isRecent call) to be reused in JSP tags. Otherwise, when this cache policy is used as JSP tags, the logic of generating a fresh content will be re-executed. But, the newly generated content will NOT replace the existing copy of cache.

Returns:

to get the reusable delta time measured in seconds.

setReusableDeltaTime

public void setReusableDeltaTime(long reusableDeltaTime)

to set the reusable delta time

For the semantics of reusable delta time, please refer to getReusableDeltaTime.

Parameters:

reusableDeltaTime - the long parameter to set the reusable delta time

setReusableDeltaTime

public void setReusableDeltaTime(java.lang.String s)
                          throws java.lang.NumberFormatException

to set the reusable delta time

For the semantics of reusable delta time, please refer to getReusableDeltaTime.

Parameters:

s - the String parameter to set the reusable delta time; it will accepts the special string constant - "ignored".

getExpirationPolicy

public ExpirationPolicy getExpirationPolicy()

to get the expiration policy object

Returns:

the expiration policy of this cache policy

setExpirationPolicy

public void setExpirationPolicy(ExpirationPolicy expirationPolicyObj)

to set the expiration policy of this cache policy

Parameters:

expirationPolicyObj - the expiration policy object to set

setCacheRepositoryName

public void setCacheRepositoryName(java.lang.String repoName)

to set the cache repository name used in this cache policy (the definition of cache repository, including the name, is specified in /WEB-INF/wcache.xml)

Parameters:

repoName - the string parameter to specifiy the cache repository name used in this cache policy

getCacheRepositoryName

public java.lang.String getCacheRepositoryName()

to get the cache repository name used in this cache policy

Returns:

the cache repository name used in this cache policy

setReportException

public void setReportException(boolean reportException)

to set whether a CacheRuntimeException is generated during cache operations.

e.g., getCache, putCache and invalidateCache. If this attribute is true, an exception will be triggered. Otherwise, the operation will fail silently and the error message will be logged to the servlet context log

Parameters:

reportException - the boolean parameter to set

setReportException

public void setReportException(java.lang.String reportExceptionStr)

to set whether a CacheRuntimeException is generated during cache operations.

e.g., getCache, putCache and invalidateCache. If this attribute is true, an exception will be triggered. Otherwise, the operation will fail silently and the error message will be logged to the servlet context log

Parameters:

reportExceptionStr - the String parameter to set

getReportException

public boolean getReportException()

to get the value of reportException flag.

For the semantics of this flag, please refer to the javadoc of setReportException

Returns:

the boolean flag of reportException

toString

public java.lang.String toString()

to generate the string of description of this cache policy in XML format

Overrides:

toString in class java.lang.Object

getDebugCacheName

public java.lang.String getDebugCacheName(javax.servlet.http.HttpServletRequest req,
                                          java.lang.String specifiedName,
                                          SectionId sectionId)

to generate the internal (for advanced debug purpose) cache name (most users do not need to call this function.)

Parameters:

req - the given HTTP servlet request

specifiedName - the given user specified name, when type is TYPE_USERSPECIFIED

sectionId - the given automatic cache block ID, when type is NOT TYPE_USERSPECIFIED

Returns:

the generated string of the internal cache name

sortEnum

public static java.util.Enumeration sortEnum(java.util.Enumeration enum)

a convenient method to sort an Enumeration of Strings

getCache

public CacheBlock getCache(javax.servlet.http.HttpServletRequest req,
                           java.lang.String specifiedName,
                           SectionId sectionId)

to get the cache block (as CacheBlock) object) through this cache policy. This is the comprehensive version of getCache API.

Parameters:

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

Returns:

the cache block object

getCache

public CacheBlock getCache(javax.servlet.http.HttpServletRequest req,
                           SectionId sectionId)

to get the cache block (as CacheBlock) object) through this cache policy. This is the getCache API for NON-TYPE_USERSPECIFIED cache policies.

Parameters:

req - the current HTTP servlet request

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED

Returns:

the cache block object

getCache

public CacheBlock getCache(javax.servlet.http.HttpServletRequest req,
                           java.lang.String specifiedName)

to get the cache block (as CacheBlock) object) through this cache policy. This is the getCache API for TYPE_USERSPECIFIED cache policies.

Parameters:

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

Returns:

the cache block object

getCurrentTime

public java.util.Date getCurrentTime()

to get the current time from the cache repository specified in this cache policy. If the cache repository is not available, it will just return the current type by new java.util.Date()

Returns:

the current time

isRecent

public boolean isRecent(CacheBlock block)

to test with a cache block is recent enough to reuse according to the reusableTimeStamp and reusableDeltaTime attribute, where reusableTimeStamp takes precedence over reusableDeltaTime.

This method is called by the JSP tags to check whether the cache block is recent enough to be reused. If it is not recent enough, the JSP tags will execute the logic to generate a fresh copy of content without replacing the exising copy. The concept is different from TTL in expiration policies. Please refer the semantics of reusableTimeStamp and reusableDeltaTime.

Parameters:

block - the cache block to test

Returns:

the boolean value that says whether the block is recent enough

putCache

public void putCache(java.lang.Object obj,
                     javax.servlet.http.HttpServletRequest req,
                     java.lang.String specifiedName,
                     SectionId sectionId)

to put an object into the cache repository through this cache policy.

This is the comprehensive version of putCache API.

The actual data object (passed into this API) that needs to be stored into the cache. Caller does NOT need to create the CacheBlock wrapper object to wrap the actual data object to use this putCache API. When getCache is called, the actual data object will be returned within a CacheBlock wrapper object, which contains other meta data (e.g. creation time)

Parameters:

obj - the actual data object

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

putCache

public void putCache(java.lang.Object obj,
                     javax.servlet.http.HttpServletRequest req,
                     SectionId sectionId)

to put an object into the cache repository through this cache policy.

This is the putCache API for NON-TYPE_USERSPECIFIED cache policies.

The actual data object (passed into this API) that needs to be stored into the cache. Caller does NOT need to create the CacheBlock wrapper object to wrap the actual data object to use this putCache API. When getCache is called, the actual data object will be returned within a CacheBlock wrapper object, which contains other meta data (e.g. creation time)

Parameters:

obj - the actual data object

req - the current HTTP servlet request

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

putCache

public void putCache(java.lang.Object obj,
                     javax.servlet.http.HttpServletRequest req,
                     java.lang.String specifiedName)

to put an object into the cache repository through this cache policy.

This is the putCache API for TYPE_USERSPECIFIED cache policies.

The actual data object (passed into this API) that needs to be stored into the cache. Caller does NOT need to create the CacheBlock wrapper object to wrap the actual data object to use this putCache API. When getCache is called, the actual data object will be returned within a CacheBlock wrapper object, which contains other meta data (e.g. creation time)

Parameters:

obj - the actual data object

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

invalidateCache

public void invalidateCache(javax.servlet.http.HttpServletRequest req,
                            java.lang.String specifiedName,
                            SectionId sectionId)

to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters

This is the comprehensive version of invalidateCache API.

Parameters:

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

invalidateCache

public void invalidateCache(javax.servlet.http.HttpServletRequest req,
                            java.lang.String specifiedName)

to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters

This is the invalidateCache API for TYPE_USERSPECIFIED.

Parameters:

req - the current HTTP servlet request

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

invalidateCache

public void invalidateCache(javax.servlet.http.HttpServletRequest req,
                            SectionId sectionId)

to invalidate the cache block object in the cache repository through this cache policy; the cache block object is identified by the passed-in parameters

This is the invalidateCache API for NON-TYPE_USERSPECIFIED.

Parameters:

req - the current HTTP servlet request

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

autoInvalidateStrToLevelInt

public static int autoInvalidateStrToLevelInt(java.lang.String s)

the convenient method to convert the AUTO INVALIDATE LEVEL String to the corresponding the AUTO INVALIDATE LEVEL integer constant, which is used in invalidateCacheLike method. e.g. from AUTO_INVALIDATE_APP_LEVEL_STR to AUTO_INVALIDATE_APP_LEVEL.

Parameters:

s - the AUTO INVALIDATE LEVEL string parameter

Returns:

the AUTO INVALIDATE LEVEL integer constant

invalidateCacheLike

public void invalidateCacheLike(javax.servlet.http.HttpServletRequest req,
                                java.lang.String specifiedName,
                                int autoInvalidateLevel)

to invalidate a collection of cache blocks through this cache policy that matches with given paramaters

This is the comprehensive version of the invalidateCacheLikeAPI.

Parameters:

req - the current HTTP servlet request object

specifiedName - the user specified name used in TYPE_USERSPECIFIED cache policy; this parameter is ignored when the cache policy is NOT TYPE_USERSPECIFIED; this parameter may contain some embedded wildcard "*"; however, most of the cache repositories do not support embedded wildcard invalidation.

autoInvalidateLevel - the integer parameter that represents invalidation level; this parameter is used only with cache policies of auto types (i.e. NON-TYPE_USERSPECIFIED); this parameter is ignored, otherwise

invalidateCacheLike

public void invalidateCacheLike(javax.servlet.http.HttpServletRequest req,
                                java.lang.String specifiedName)

to invalidate a collection of cache blocks through this cache policy that matches with given paramaters

This is the invalidateCacheLikeAPI for TYPE_USERSPECIFIED cache policy.

Parameters:

req - the current HTTP servlet request object

specifiedName - the user specified name used in TYPE_USERSPECIFIED cache policy; this parameter is ignored when the cache policy is NOT TYPE_USERSPECIFIED; this parameter may contain some embedded wildcard "*"; however, most of the cache repositories do not support embedded wildcard invalidation.

invalidateCacheLike

public void invalidateCacheLike(javax.servlet.http.HttpServletRequest req,
                                int autoInvalidateLevel)

to invalidate a collection of cache blocks through this cache policy that matches with given paramaters

This is the invalidateCacheLikeAPI for NON-TYPE_USERSPECIFIED cache policy.

Parameters:

req - the current HTTP servlet request object

autoInvalidateLevel - the integer parameter that represents invalidation level; this parameter is used only with cache policies of auto types (i.e. NON-TYPE_USERSPECIFIED); this parameter is ignored, otherwise

invalidateCacheOtherPathLike

public void invalidateCacheOtherPathLike(javax.servlet.http.HttpServletRequest req,
                                         java.lang.String otherPath,
                                         javax.servlet.http.Cookie[] newCookies,
                                         int autoInvalidateLevel)

invalidate the caches of another page, not the one associated with the current request.

Parameters:

req - the current HTTP servlet request; the invalidate operation will make use of the context path and the existing cookies, if new cookes are supplied

otherPath - the path of other URI of which developers want to invalidate caches; the path includes the page name and an optional parameter list; e.g., "/dir1/dir2/a.jsp" or "/dir3/b.jsp?p1=v1&p2=v2"; The new overriding page path and parameter will be used to invalidate caches

newCookies - the array of new cookies; if developers pass in an array of new cookies to this call, then the new set of cookies will be used to invalidate caches (when the cache policy selects some cookies and the invalidation level is down to the cookie level); if developers do not pass an array of new cookies, the cookies of the current request will be used to do invalidation

autoInvalidateLevel - the level of invalidation; if the caching policy is NON-TYPE_USERSPECIFIED / automatic naming, an invalidation level can be specified to set the level of the invalidation; they are application, page, parameter and cookie; please refer to AUTO_INVALIDATE_* integer constants defined in this class.

invalidateCacheOtherPathLike

public void invalidateCacheOtherPathLike(javax.servlet.http.HttpServletRequest req,
                                         java.lang.String otherPath)

invalidate the caches of another page, not the one associated with the current request. This API is a shorthand version designed for NON-TYPEUSERSPECIFIED / automatic naming caching policy.

This shorthand version will always reuse the cookies of the current HTTP request. And, the invalidation is set to the parameter level, if the otherPath contains an HTTP parameter list and a '?' character (e.g. "/dir3/b.jsp?p1=v1&p2=v2"). Otherwise, the invalidation is set to the page level.

Parameters:

req - the current HTTP servlet request; the invalidate operation will make use of the context path and the existing cookies, if new cookes are supplied

otherPath - the path of other URI of which developers want to invalidate caches; the path includes the page name and an optional parameter list; e.g., "/dir1/dir2/a.jsp" or "/dir3/b.jsp?p1=v1&p2=v2"; The new overriding page path and parameter will be used to invalidate caches

putAutoCacheForOtherPath

public void putAutoCacheForOtherPath(java.lang.Object obj,
                                     javax.servlet.http.HttpServletRequest req,
                                     java.lang.String otherPath,
                                     StringSectionId sectionId)

put a cache entry for a specified string-based section id for the specified page path. The cache policy must NOT be TYPE_USERSPECIFIED, i.e. auto-type.

Parameters:

obj - the object being stored

req - the current HttpServletRequest

otherPath - the path of the other page where the cache entry will be attached to

sectionId - the string-based section id of which the cache entry is stored under

putAutoCacheForOtherPath

public void putAutoCacheForOtherPath(java.lang.Object obj,
                                     javax.servlet.http.HttpServletRequest req,
                                     java.lang.String otherPath,
                                     javax.servlet.http.Cookie[] newCookies,
                                     StringSectionId sectionId)

put a cache entry for a specified string-based section id for the specified page path. The cache policy must NOT be TYPE_USERSPECIFIED, i.e. auto-type.

Parameters:

obj - the object being stored

req - the current HttpServletRequest

otherPath - the path of the other page where the cache entry will be attached to

newCookies - the array of new cookies; if developers pass in an array of new cookies to this call, then the new set of cookies will be used to store the cache; otherwise, the cookies of the current request will be used

sectionId - the string-based section id of which the cache entry is stored under

getAutoCacheForOtherPath

public CacheBlock getAutoCacheForOtherPath(javax.servlet.http.HttpServletRequest req,
                                           java.lang.String otherPath,
                                           StringSectionId sectionId)

get a cache entry for a specified string-based section id for the specified page path. The cache policy must NOT be TYPE_USERSPECIFIED, i.e. auto-type.

Parameters:

obj - the object being stored

req - the current HttpServletRequest

otherPath - the path of the other page where the cache entry will be attached to

sectionId - the string-based section id of which the cache entry is stored under

getAutoCacheForOtherPath

public CacheBlock getAutoCacheForOtherPath(javax.servlet.http.HttpServletRequest req,
                                           java.lang.String otherPath,
                                           javax.servlet.http.Cookie[] newCookies,
                                           StringSectionId sectionId)

get a cache entry for a specified string-based section id for the specified page path. The cache policy must NOT be TYPE_USERSPECIFIED, i.e. auto-type.

Parameters:

obj - the object being stored

req - the current HttpServletRequest

otherPath - the path of the other page where the cache entry will be attached to

newCookies - the array of new cookies; if developers pass in an array of new cookies to this call, then the new set of cookies will be used to store the cache; otherwise, the cookies of the current request will be used

sectionId - the string-based section id of which the cache entry is stored under

markupBegin

public void markupBegin(javax.servlet.ServletContext sc,
                        javax.servlet.http.HttpServletRequest req,
                        java.io.Writer out,
                        java.lang.String specifiedName,
                        SectionId sectionId)

an API to markup the beginning of a cache block; mainly for future integration with downstream level-3 caching; not being used by external users as of this version

Parameters:

sc - the current servletcontext

req - the current HTTP servlet request

out - the current output writer

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise

markupEnd

public void markupEnd(javax.servlet.ServletContext sc,
                      javax.servlet.http.HttpServletRequest req,
                      java.io.Writer out,
                      java.lang.String specifiedName,
                      SectionId sectionId)

an API to markup the end of a cache block; mainly for future integration with downstream level-3 caching; not being used by external users as of this version

Parameters:

sc - the current servletcontext

req - the current HTTP servlet request

out - the current output writer

specifiedName - the user specified cache name used, when the type of this cache policy is TYPE_USERSPECIFIED; it can be null, otherwise

sectionId - the automatic-increment cach block id used, when the type of this cache policy is NOT TYPE_USERSPECIFIED; it can be null, otherwise