BEA Systems, Inc.
WebLogic Server 6.1 API Reference

weblogicx.jsp.tags
Class CacheTag

java.lang.Object
  |
  +--javax.servlet.jsp.tagext.TagSupport
        |
        +--javax.servlet.jsp.tagext.BodyTagSupport
              |
              +--weblogicx.jsp.tags.CacheTag
public class CacheTag
extends javax.servlet.jsp.tagext.BodyTagSupport
implements javax.servlet.jsp.tagext.TryCatchFinally

The cache tag supports caching the work that is done within the body of the tag. To this end, it supports both output (transform) data and input (calculated) data. Output caching refers to the content generated by the code within the tag. Input caching refers to the values that variables are set to by the code within the tag. Output caching is useful when the final form of the content is the important thing to cache. Input caching is important when the view of the data can vary independently of the data calculated within the tag. The caches are stored using soft references to avoid the caching system from being responsible for running the system out of memory. Unfortunately, due to incompatibilities with the HotSpot's VM and the Classic VM, we must not use soft references when we are running within HotSpot. You can override the use of soft references by setting the following global system properties in precedence order: weblogicx.jsp.tags.CacheTag.softreferences = true|false weblogicx.jsp.tags.CacheTag.nosoftreferences = true|false Use of soft references defaults to true in a classic VM and false within a HotSpot VM. You can force the refresh of a cache by setting _cache_refresh to true in the scope that you want affected. If you want all caches to always refresh, put it in the application scope. If you want all the caches for a user to be refreshed, set it in the session scope. If you want all the caches in the current request to be refreshed set it as a parameter or in the request. Note: You must have the weblogic-tags-server.jar in your weblogic.class.path for proper operation.

Author:
Copyright © 2001 BEA Systems, Inc. All Rights Reserved.
See Also:
Serialized Form

Inner Class Summary
static class CacheTag.RefWrapper
           
 
Field Summary
protected  java.lang.String actualKey
          The actual key used to lookup the cache.
protected  java.lang.String additionalKey
           
protected  java.util.Set currentLocks
           
protected  java.util.Map savedPageContextValues
           
 
Fields inherited from class javax.servlet.jsp.tagext.BodyTagSupport
bodyContent
 
Fields inherited from class javax.servlet.jsp.tagext.TagSupport
id, pageContext
 
Constructor Summary
CacheTag()
          Construction of a cache tag.
 
Method Summary
protected  void asyncForward()
           
 int doAfterBody()
           
 void doCatch(java.lang.Throwable t)
           
protected  int doEndCache()
           
protected  int doEndKeyedCache()
           
 int doEndTag()
           
 void doFinally()
           
protected  int doStartCache()
           
protected  int doStartKeyedCache()
           
 int doStartTag()
          Start the cache tag.
protected  void ensureAdmin(java.lang.String cacheKey)
           
protected  java.lang.String getAdditionalKey()
           
static boolean getAdmin()
           
 boolean getAsync()
           
static boolean getDebug()
           
 java.lang.String getFlush()
           
 java.lang.String getKey()
           
 java.lang.String getName()
           
 java.lang.String getScope()
           
protected  java.lang.Object getScopeObject(java.lang.String scope)
           
 int getSize()
           
 java.lang.String getTimeout()
           
protected  java.lang.Object getValueFromScope(java.lang.String scope, java.lang.String key)
           
 java.lang.String getVars()
           
static boolean getVerbose()
           
static void main(java.lang.String[] args)
           
 void release()
          If the tag fails in the middle or something else bad happens we need to destroy all the locks that were taken but not released to avoid deadlocking the next time we hit the cache.
protected  void releaseLock(java.lang.String scope, java.lang.String key)
           
protected  void removeValueInScope(java.lang.String scope, java.lang.String key)
           
protected  void restoreVars(CacheValue cache)
           
protected  void revertKeysAfterCacheUpdate()
           
protected  void revertKeysAfterForward()
           
protected  void revertPageContextVariables()
           
protected  void revertValues(java.util.Map revertedPageScope, java.util.Map revertedRequestScope, java.util.Map revertedSessionScope, java.util.Map revertedApplicationScope)
           
protected  void saveKeysBeforeCacheUpdate()
           
protected  void saveKeysBeforeForward()
           
protected  void saveVars(CacheValue cache)
           
static void setAdmin(boolean admin)
           
 void setAsync(boolean async)
          If the async parameter is true, the cache will be updated asynchronously, if possible.
static void setDebug(boolean debug)
           
 void setFlush(java.lang.String flush)
           
 void setKey(java.lang.String key)
          This is the name of the variable whose value you wish to use as a key into the cache.
 void setName(java.lang.String name)
          This is a name for the cache that you can reference in other pages in order to use the same cache across pages.
 void setScope(java.lang.String scope)
          This is the scope of the cache, i.e.
 void setSize(int size)
          For keyed caches this limits the number of keys to keep.
 void setTimeout(java.lang.String timeoutString)
          Cache timeout property.
protected  void setValueInScope(java.lang.String scope, java.lang.String key, java.lang.Object value)
           
 void setVars(java.lang.String vars)
          In addition to caching the transformed output of the cache, calculated values can also be cached within the block.
static void setVerbose(boolean verbose)
           
protected  boolean shouldRefresh()
           
protected  void storeKeyValues(java.util.Map storePageScope, java.util.Map storeRequestScope, java.util.Map storeSessionScope, java.util.Map storeApplicationScope)
           
protected  boolean takeLock(java.lang.String scope, java.lang.String key)
          Returns false if you can only read, true if you got the lock.
protected  void waitOnLock(java.lang.String scope, java.lang.String key)
          Waits until the lock is released since another thread is calculating the cache value.
 
Methods inherited from class javax.servlet.jsp.tagext.BodyTagSupport
doInitBody, getBodyContent, getPreviousOut, setBodyContent
 
Methods inherited from class javax.servlet.jsp.tagext.TagSupport
findAncestorWithClass, getId, getParent, getValue, getValues, removeValue, setId, setPageContext, setParent, setValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

actualKey

protected java.lang.String actualKey
The actual key used to lookup the cache.

currentLocks

protected java.util.Set currentLocks

additionalKey

protected java.lang.String additionalKey

savedPageContextValues

protected java.util.Map savedPageContextValues
Constructor Detail

CacheTag

public CacheTag()
Construction of a cache tag.
Method Detail

getDebug

public static boolean getDebug()

setDebug

public static void setDebug(boolean debug)

getVerbose

public static boolean getVerbose()

setVerbose

public static void setVerbose(boolean verbose)

getAdmin

public static boolean getAdmin()

setAdmin

public static void setAdmin(boolean admin)

main

public static void main(java.lang.String[] args)

setTimeout

public void setTimeout(java.lang.String timeoutString)
                throws javax.servlet.jsp.JspException
Cache timeout property. This is the number of seconds before a value needs to be refreshed. This is not proactive, it will only be refreshed if it is requested. It is also acceptable to postfix the value with units to override the default units of seconds: ms = milliseconds s = seconds (default) m = minutes h = hours d = days

getTimeout

public java.lang.String getTimeout()

setScope

public void setScope(java.lang.String scope)
This is the scope of the cache, i.e. where the cache is stored. These are the standard JSP supported scopes: application, session, request, and page. Most caches will be either session or application scope. Additionally you can specify "cluster" scope and the state will be distributed through the cluster of servers Default: application scope.

getScope

public java.lang.String getScope()

setName

public void setName(java.lang.String name)
This is a name for the cache that you can reference in other pages in order to use the same cache across pages. This is useful for textually included pages that need cache sharing. If this is not set a unique name will be chosen for the cache. It is not recommended that you manually calculate the name of the tag, the key functionality can be used equivalently in all cases. The name is calculated as "weblogic.jsp.tags.CacheTag." then the URI and finally a monotonically increasing number representing which tag in the page you are caching. If different URIs get to the same JSP page somehow the caches will not be shared in the default case. Use named caches in this case.

getName

public java.lang.String getName()

setSize

public void setSize(int size)
For keyed caches this limits the number of keys to keep. The default is an unlimited cache of keys. With a limited number of keys we use a least used system to order the cache. Changing the value of the size attribute of an already used cache will not change the size of that cache.

getSize

public int getSize()

setKey

public void setKey(java.lang.String key)
This is the name of the variable whose value you wish to use as a key into the cache. You can additionally specify a scope by prepending the name of the scope to the name: parameter.key | page.key | request.key | application.key | session.key It defaults to searching through the scopes in the order above. Each named key will be available within the cache tag as a scripting variable.

getKey

public java.lang.String getKey()

setAsync

public void setAsync(boolean async)
If the async parameter is true, the cache will be updated asynchronously, if possible. The user that initiates the cache hit will see the old data.

getAsync

public boolean getAsync()

setVars

public void setVars(java.lang.String vars)
In addition to caching the transformed output of the cache, calculated values can also be cached within the block. These variables are specified exactly the same as the cache keys. This is Input caching.

getVars

public java.lang.String getVars()

setFlush

public void setFlush(java.lang.String flush)

getFlush

public java.lang.String getFlush()

getScopeObject

protected java.lang.Object getScopeObject(java.lang.String scope)
                                   throws javax.servlet.jsp.JspException

getValueFromScope

protected java.lang.Object getValueFromScope(java.lang.String scope,
                                             java.lang.String key)
                                      throws javax.servlet.jsp.JspException

setValueInScope

protected void setValueInScope(java.lang.String scope,
                               java.lang.String key,
                               java.lang.Object value)
                        throws javax.servlet.jsp.JspException

removeValueInScope

protected void removeValueInScope(java.lang.String scope,
                                  java.lang.String key)
                           throws javax.servlet.jsp.JspException

doStartTag

public int doStartTag()
               throws javax.servlet.jsp.JspException
Start the cache tag. If this is a POST or PUT request, ensure that we are not asynchronously updating the cache. There is no way to back up the input stream from the client.

Overrides:
doStartTag in class javax.servlet.jsp.tagext.BodyTagSupport

takeLock

protected boolean takeLock(java.lang.String scope,
                           java.lang.String key)
                    throws javax.servlet.jsp.JspException
Returns false if you can only read, true if you got the lock.

waitOnLock

protected void waitOnLock(java.lang.String scope,
                          java.lang.String key)
                   throws javax.servlet.jsp.JspException
Waits until the lock is released since another thread is calculating the cache value.

releaseLock

protected void releaseLock(java.lang.String scope,
                           java.lang.String key)
                    throws javax.servlet.jsp.JspException

shouldRefresh

protected boolean shouldRefresh()

getAdditionalKey

protected java.lang.String getAdditionalKey()
                                     throws javax.servlet.jsp.JspException

revertPageContextVariables

protected void revertPageContextVariables()

saveKeysBeforeForward

protected void saveKeysBeforeForward()
                              throws javax.servlet.jsp.JspException

revertKeysAfterForward

protected void revertKeysAfterForward()
                               throws javax.servlet.jsp.JspException

saveKeysBeforeCacheUpdate

protected void saveKeysBeforeCacheUpdate()
                                  throws javax.servlet.jsp.JspException

revertKeysAfterCacheUpdate

protected void revertKeysAfterCacheUpdate()
                                   throws javax.servlet.jsp.JspException

storeKeyValues

protected void storeKeyValues(java.util.Map storePageScope,
                              java.util.Map storeRequestScope,
                              java.util.Map storeSessionScope,
                              java.util.Map storeApplicationScope)
                       throws javax.servlet.jsp.JspException

revertValues

protected void revertValues(java.util.Map revertedPageScope,
                            java.util.Map revertedRequestScope,
                            java.util.Map revertedSessionScope,
                            java.util.Map revertedApplicationScope)
                     throws javax.servlet.jsp.JspException

asyncForward

protected void asyncForward()
                     throws javax.servlet.jsp.JspException

ensureAdmin

protected void ensureAdmin(java.lang.String cacheKey)

doStartCache

protected int doStartCache()
                    throws javax.servlet.jsp.JspException

doStartKeyedCache

protected int doStartKeyedCache()
                         throws javax.servlet.jsp.JspException

doAfterBody

public int doAfterBody()
                throws javax.servlet.jsp.JspException

Overrides:
doAfterBody in class javax.servlet.jsp.tagext.BodyTagSupport

doEndCache

protected int doEndCache()
                  throws javax.servlet.jsp.JspException

doEndKeyedCache

protected int doEndKeyedCache()
                       throws javax.servlet.jsp.JspException

doEndTag

public int doEndTag()

Overrides:
doEndTag in class javax.servlet.jsp.tagext.BodyTagSupport

doCatch

public void doCatch(java.lang.Throwable t)
             throws java.lang.Throwable
Specified by:
doCatch in interface javax.servlet.jsp.tagext.TryCatchFinally

doFinally

public void doFinally()
Specified by:
doFinally in interface javax.servlet.jsp.tagext.TryCatchFinally

release

public void release()
If the tag fails in the middle or something else bad happens we need to destroy all the locks that were taken but not released to avoid deadlocking the next time we hit the cache.

Overrides:
release in class javax.servlet.jsp.tagext.BodyTagSupport

saveVars

protected void saveVars(CacheValue cache)
                 throws javax.servlet.jsp.JspException

restoreVars

protected void restoreVars(CacheValue cache)
                    throws javax.servlet.jsp.JspException

Documentation is available at
http://download.oracle.com/docs/cd/E13222_01/wls/docs61
WebLogic classes and methods that do not appear in this reference are not public and are not supported.