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
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
  CachePolicy(CachePolicy cPolicy)
          copy constructor of cache policy
  CachePolicy(oracle.jsp.jwcache.ServletConfig config)
          Default cache policy constructor
protected CachePolicy(oracle.jsp.jwcache.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(oracle.jsp.jwcache.ServletConfig config, CachePolicy cPolicy)
          copy constructor of cache policy with an overriding servlet config object.
 
Method Summary
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
 int getAutoType()
          to get the type of this cache policy.
 CacheBlock getCache(oracle.jsp.jwcache.HttpServletRequest req, SectionId sectionId)
          to get the cache block (as CacheBlock) object) through this cache policy.
 CacheBlock getCache(oracle.jsp.jwcache.HttpServletRequest req, java.lang.String specifiedName)
          to get the cache block (as CacheBlock) object) through this cache policy.
 CacheBlock getCache(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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
protected  oracle.jsp.jwcache.repository.CacheRepository getRepo()
          a convenient method to retrieve the cache repository object that corresponds to the cache repository specified in this cache policy
 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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.HttpServletRequest req, int autoInvalidateLevel)
          to invalidate a collection of cache blocks through this cache policy that matches with given paramaters
 void invalidateCacheLike(oracle.jsp.jwcache.HttpServletRequest req, java.lang.String specifiedName)
          to invalidate a collection of cache blocks through this cache policy that matches with given paramaters
 void invalidateCacheLike(oracle.jsp.jwcache.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(oracle.jsp.jwcache.HttpServletRequest req, java.lang.String otherPath)
          invalidate the caches of another page, not the one associated with the current request.
 void invalidateCacheOtherPathLike(oracle.jsp.jwcache.HttpServletRequest req, java.lang.String otherPath, oracle.jsp.jwcache.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(oracle.jsp.jwcache.ServletContext sc, oracle.jsp.jwcache.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(oracle.jsp.jwcache.ServletContext sc, oracle.jsp.jwcache.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 putCache(java.lang.Object obj, oracle.jsp.jwcache.HttpServletRequest req, SectionId sectionId)
          to put an object into the cache repository through this cache policy.
 void putCache(java.lang.Object obj, oracle.jsp.jwcache.HttpServletRequest req, java.lang.String specifiedName)
          to put an object into the cache repository through this cache policy.
 void putCache(java.lang.Object obj, oracle.jsp.jwcache.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:

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:

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:

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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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

getRepo

protected oracle.jsp.jwcache.repository.CacheRepository getRepo()
                                                         throws oracle.jsp.jwcache.repository.CacheRepositoryException
a convenient method to retrieve the cache repository object that corresponds to the cache repository specified in this cache policy

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 "ignore" 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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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,
                     oracle.jsp.jwcache.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,
                     oracle.jsp.jwcache.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,
                     oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.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(oracle.jsp.jwcache.HttpServletRequest req,
                                         java.lang.String otherPath,
                                         oracle.jsp.jwcache.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(oracle.jsp.jwcache.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

markupBegin

public void markupBegin(oracle.jsp.jwcache.ServletContext sc,
                        oracle.jsp.jwcache.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(oracle.jsp.jwcache.ServletContext sc,
                      oracle.jsp.jwcache.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