com.plumtree.portaluiinfrastructure.tags.helper
Class TagState

java.lang.Object
  com.plumtree.portaluiinfrastructure.tags.helper.TagState

All Implemented Interfaces:

ITagState

public class TagState
extends java.lang.Object
implements ITagState

This class manages variable storage and retrieval for tags. It allows you to get and set variables for various contexts (session, request, tag, etc...).

Field Summary

static java.lang.String	CACHE_LIB The tag library used to store the cache map.
static java.lang.String	CACHE_MAPENTRY_NAME Name of the cache map entry.
protected static java.lang.String	COMBINED_KEY_SEPARATOR The separator between library and tag name in the combined key.
static java.lang.String	HTTP_REQUEST_DATA_KEY This key is used to store HTTP request data collections on the session using the request as a key.
protected IApplication	m_Application The HTTP Application.
protected ATag	m_CurrentTag The current tag.
protected XPHashtable	m_HTTPRequestScopeData The HTTP Request Data container.
protected int	m_nTagStackTop The index into the top of the Tag Stack.
protected ISessionManager	m_PersistentSession The persistent sub-session.
protected XPHashtable	m_PortletRequestScopeData The Portlet Request Data container.
protected ISessionManager	m_Session The sub-session.
protected XPHashtable	m_TagScopeData The Tag Data container.
protected XPArrayList	m_TagStack The Tag Stack.
protected XPArrayList	m_TagVarStack The Tag Var Stack.
protected boolean	m_useParentTagScope Whether to use parent tag scope or tag scope inside current tag when setting variables
static java.lang.String	SHARED_JS_COLLECTION This key is used to store an http request level HTMLElementCollection that contains all of the shared javascript for the tags in the HTTP request.
static java.lang.String	SHARED_JS_COLLECTION_DISPLAYED This key is used to store an http request level Boolean that marks whether or not the current shared javascript collection for this HTTP request has been retrieved for displayed or not.
static java.lang.String	SHARED_JS_VAR_LIST This key is used to store an http request level list that stores whether or not a particular class of tags has been displayed on the page yet.
static XPHashtable	TEST_PORTLET_REQUEST_DATA This static variable can be used to supply a pre-populated hashtable for the portlet request data.

Constructor Summary

TagState(IApplication _application, ISessionManager _session, ISessionManager _persistentSession, XPHashtable _httpRequestData)
Creates a TagState object.

Method Summary

boolean	AddCacheEntry(java.lang.String cacheKey, java.lang.Object cacheValue, Scope scope, int duration) Add a cached tag data entry Cache entries are stored in the same scope as the other tag variables, but cache entries are prefixed with a special string.
protected void	CheckValidVariableName(java.lang.String _strVariableName) This method checks that the variable name does not contain any reserved characters (".").
void	EnterTag(ATag _currentTag) The tag container calls this method every time a new tag is displayed.
void	ExitTag() The tag container calls this method when a tag is finished displaying.
java.lang.Object	GetAnyVariable(java.lang.String _strKey) Gets a variable from memory from all scopes.
IApplication	GetApplication() Return the Application for use in storing data on the HTTP Application.
java.lang.Object	GetCacheEntryData(java.lang.String cacheKey, Scope scope) Get tag data entry from cache
static XPHashtable	GetHTTPRequestData(AActivitySpace aSpace) This method extracts the HTTP request data from the Activity Space.
ISessionManager	GetPersistentSubSession() Returns the persistent subsession that can be used to store data on the HTTP Session for use across multiple login/logout cycles.
static HTMLElementCollection	GetSharedJavascriptCollection(AActivitySpace asOwner) This method gets the shared JavaScript collection for this HTTP request, and initializes it if it has not been initialized yet.
java.lang.Object	GetSharedVariable(java.lang.String _strKey, Scope _scope) Gets a shared variable from memory in the appropriate scope.
ISessionManager	GetSubSession() Returns the subsession that can be used to store data on the HTTP Session.
protected java.lang.String	GetTagName() Get the name of the current tag.
java.lang.Object	GetVariable(java.lang.String _strKey, Scope _scope) Gets a variable from memory in the appropriate scope.
protected TagCacheEntry	InternalGetCacheEntry(java.lang.String cacheKey, Scope scope) Gets cache entry from the cache map
protected XPHashtable	InternalGetCacheMap(Scope scope) Internal method to retrieve the Cache map object
java.lang.Object	InternalGetVariable(java.lang.String _strLibrary, java.lang.String _strKey, Scope _scope) Helper method to get variables in memory.
protected void	InternalRemoveVariable(java.lang.String _strCombinedKey, Scope _scope) This method removes a variable from the underlying collection.
protected void	InternalSetVariable(java.lang.String _strLibrary, java.lang.String _strKey, java.lang.Object _oValue, Scope _scope) Helper method to set variables in memory.
static void	ResetPageRequestData(AActivitySpace _aSpace) This method is called at the end of every HTTP request to reset the page request data.
void	ResetPortletRequestData() The tag container calls this method to reset the portlet request data for each portlet on a page and to verify that the TagState is in the correct state after having finished displaying all of the tags in the current portlet request.
static void	SetSharedJavascriptCollectionAsDisplayed(AActivitySpace asOwner) This method marks the shared JavaScript collection for this HTTP request as retrieved for display.
void	SetSharedVariable(java.lang.String _strKey, java.lang.Object _oValue, Scope _scope, boolean bOwnerEditOnly) Sets a variable in memory in the appropriate scope.
void	SetVariable(java.lang.String _strKey, java.lang.Object _oValue, Scope _scope) Sets a variable in memory in the appropriate scope.
void	StoreInParentTagScope(boolean useParent)

Methods inherited from class java.lang.Object

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

Field Detail

CACHE_LIB

public static final java.lang.String CACHE_LIB

The tag library used to store the cache map. Use a non-existant tag lib to avoid conflicts with regular tag variables. Public so that it is accessible from unit tests

See Also:

Constant Field Values

CACHE_MAPENTRY_NAME

public static final java.lang.String CACHE_MAPENTRY_NAME

Name of the cache map entry. Public so that it is accessible from unit tests

See Also:

Constant Field Values

SHARED_JS_VAR_LIST

public static final java.lang.String SHARED_JS_VAR_LIST

This key is used to store an http request level list that stores whether or not a particular class of tags has been displayed on the page yet.

See Also:

Constant Field Values

SHARED_JS_COLLECTION

public static final java.lang.String SHARED_JS_COLLECTION

This key is used to store an http request level HTMLElementCollection that contains all of the shared javascript for the tags in the HTTP request.

See Also:

Constant Field Values

SHARED_JS_COLLECTION_DISPLAYED

public static final java.lang.String SHARED_JS_COLLECTION_DISPLAYED

This key is used to store an http request level Boolean that marks whether or not the current shared javascript collection for this HTTP request has been retrieved for displayed or not.

See Also:

Constant Field Values

COMBINED_KEY_SEPARATOR

protected static final java.lang.String COMBINED_KEY_SEPARATOR

The separator between library and tag name in the combined key.

See Also:

Constant Field Values

HTTP_REQUEST_DATA_KEY

public static final java.lang.String HTTP_REQUEST_DATA_KEY

This key is used to store HTTP request data collections on the session using the request as a key.

See Also:

Constant Field Values

m_TagStack

protected XPArrayList m_TagStack

The Tag Stack. This keeps track of which Tags have been entered. It is a list of ATags.

m_TagVarStack

protected XPArrayList m_TagVarStack

The Tag Var Stack. This keeps track of what Data has been stored by which tag in tag scope. It is a list of XPArrayLists.

m_nTagStackTop

protected int m_nTagStackTop

The index into the top of the Tag Stack.

m_TagScopeData

protected XPHashtable m_TagScopeData

The Tag Data container. This cannot be re-used between portlet requests and must be reset.

m_PortletRequestScopeData

protected XPHashtable m_PortletRequestScopeData

The Portlet Request Data container. This cannot be re-used between portlet requests and must be reset.

m_HTTPRequestScopeData

protected XPHashtable m_HTTPRequestScopeData

The HTTP Request Data container. This hashtable is stored in the session using the request as a key and is cached in the TagState object.

m_Application

protected IApplication m_Application

The HTTP Application.

m_Session

protected ISessionManager m_Session

The sub-session.

m_PersistentSession

protected ISessionManager m_PersistentSession

The persistent sub-session.

m_CurrentTag

protected ATag m_CurrentTag

The current tag.

m_useParentTagScope

protected boolean m_useParentTagScope

Whether to use parent tag scope or tag scope inside current tag when setting variables

TEST_PORTLET_REQUEST_DATA

public static XPHashtable TEST_PORTLET_REQUEST_DATA

This static variable can be used to supply a pre-populated hashtable for the portlet request data. This will be used during TagState construction only. This should only be used in unit tests and not in production code.

Constructor Detail

TagState

public TagState(IApplication _application,
                ISessionManager _session,
                ISessionManager _persistentSession,
                XPHashtable _httpRequestData)

Creates a TagState object. The TagState object contains portlet request specific data and must either be reset between requests or re-created.

Parameters:

_application - The HTTP Application

_session - The sub-session

_persistentSession - The persistent sub-session

Method Detail

SetVariable

public void SetVariable(java.lang.String _strKey,
                        java.lang.Object _oValue,
                        Scope _scope)

Description copied from interface: ITagState

Sets a variable in memory in the appropriate scope.

The scope determines who can see this variable and how long it stays in memory.

For instance, a variable stored in Tag Scope can only be seen by children of the current tag and will be removed from memory when the tag is finished.

A variable stored in Portlet Request Scope will be visible to all tags in the same portlet as the current tag, and will be removed from memory when the portlet is finished displaying. Tags in other portlets on the same page will not be able to see the variable.

Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.

Note: Displaying an HTMLElement in a tag and then caching it so that another tag can add more HTML to the original tag later is not supported. HTMLElement trees can be generated and stored for later use, as long as they are self-contained trees and used in a read only way. It is safest to make clones of a cached HTMLElement tree before trying to display it again to make sure there are no threading problems.

Specified by:

SetVariable in interface ITagState

See Also:

ITagState.SetVariable(String, Object, Scope)

SetSharedVariable

public void SetSharedVariable(java.lang.String _strKey,
                              java.lang.Object _oValue,
                              Scope _scope,
                              boolean bOwnerEditOnly)

Description copied from interface: ITagState

Sets a variable in memory in the appropriate scope.

The scope determines who can see this variable and how long it stays in memory.

For instance, a variable stored in Tag Scope can only be seen by children of the current tag and will be removed from memory when the tag is finished.

A variable stored in Portlet Request Scope will be visible to all tags in the same portlet as the current tag, and will be removed from memory when the portlet is finished displaying. Tags in other portlets on the same page will not be able to see the variable.

Shared variables (as opposed to standard variables) can be accessed by tags from any library. If bOwnerEditOnly is set to true when a shared variable is first stored, then any tag can read the variable, but only tags from the same library as the tag that originally stored the variable can edit it (and replace the value in memory).

Note: Displaying an HTMLElement in a tag and then caching it so that another tag can add more HTML to the original tag later is not supported. HTMLElement trees can be generated and stored for later use, as long as they are self-contained trees and used in a read only way. It is safest to make clones of a cached HTMLElement tree before trying to display it again to make sure there are no threading problems.

Specified by:

SetSharedVariable in interface ITagState

bOwnerEditOnly - True implies that only tags from the same tag library should be able to store the value for this tag. If this variable has already been saved, then the original bOwnerEditOnly value will be retained and this argument will be ignored.

See Also:

ITagState.SetSharedVariable(String, Object, Scope, boolean)

CheckValidVariableName

protected void CheckValidVariableName(java.lang.String _strVariableName)

This method checks that the variable name does not contain any reserved characters (".").

Parameters:

String - _strVariableName The variable name to be checked.

Throws:

XPIllegalArgumentException - if the variable name contains illegal characters (".").

InternalSetVariable

protected void InternalSetVariable(java.lang.String _strLibrary,
                                   java.lang.String _strKey,
                                   java.lang.Object _oValue,
                                   Scope _scope)

Helper method to set variables in memory.

Parameters:

_strLibrary - The current library. May be null.

_strKey - The key used to store the variable.

_oValue - The variable.

_scope - The scope used to store the variable.

InternalRemoveVariable

protected void InternalRemoveVariable(java.lang.String _strCombinedKey,
                                      Scope _scope)

This method removes a variable from the underlying collection.

Parameters:

_strCombinedKey - The key used to access the variable.

_scope - The scope used to store the variable. Assumed to be non-null.

GetVariable

public java.lang.Object GetVariable(java.lang.String _strKey,
                                    Scope _scope)

Description copied from interface: ITagState

Gets a variable from memory in the appropriate scope.

The scope determines who can see this variable and how long it stays in memory.

For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.

A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.

Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.

Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.

Specified by:

GetVariable in interface ITagState

Returns:

Object The requested data. Null if the variable has never been set.

See Also:

ITagState.GetVariable(String, Scope)

GetSharedVariable

public java.lang.Object GetSharedVariable(java.lang.String _strKey,
                                          Scope _scope)

Description copied from interface: ITagState

Gets a shared variable from memory in the appropriate scope.

The scope determines who can see this variable and how long it stays in memory.

For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.

A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.

Shared variables can be accessed by tags from any tag library (as opposed to standard variables, which can only be accessed by tags from the same tag library).

Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.

Specified by:

GetSharedVariable in interface ITagState

Returns:

Object The requested data. Null if the variable has never been set.

See Also:

ITagState.GetSharedVariable(String, Scope)

GetAnyVariable

public java.lang.Object GetAnyVariable(java.lang.String _strKey)

Description copied from interface: ITagState

Gets a variable from memory from all scopes.

The scope determines who can see this variable and how long it stays in memory.

For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.

A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.

Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.

This method will first look for standard variables, and if not found will then look for shared variables.

Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.

Specified by:

GetAnyVariable in interface ITagState

Returns:

Object The requested data. Null if the variable has never been set.

See Also:

com.plumtree.portaluiinfrastructure.tags.ITagState#GetAnyVariableFromAllScopes(String, Scope)

InternalGetVariable

public java.lang.Object InternalGetVariable(java.lang.String _strLibrary,
                                            java.lang.String _strKey,
                                            Scope _scope)

Helper method to get variables in memory.

Parameters:

_strLibrary - The current library. May be null.

_strKey - The key used to store the variable.

_scope - The scope used to store the variable.

Returns:

Object the requested variable (may be a SharedStateVariable object that needs to be processed before being returned to the tag.

AddCacheEntry

public boolean AddCacheEntry(java.lang.String cacheKey,
                             java.lang.Object cacheValue,
                             Scope scope,
                             int duration)

Add a cached tag data entry Cache entries are stored in the same scope as the other tag variables, but cache entries are prefixed with a special string.

Specified by:

AddCacheEntry in interface ITagState

Parameters:

cacheKey -

cacheValue -

scope -

duration - number of minutes the cache entry is valid

Returns:

GetCacheEntryData

public java.lang.Object GetCacheEntryData(java.lang.String cacheKey,
                                          Scope scope)

Get tag data entry from cache

Specified by:

GetCacheEntryData in interface ITagState

Parameters:

cacheKey -

scope - Scope.APPLICATION or Scope.Session

Returns:

The cached entry or null if no entry was found or the entry expired.

InternalGetCacheMap

protected XPHashtable InternalGetCacheMap(Scope scope)

Internal method to retrieve the Cache map object

Parameters:

scope -

Returns:

InternalGetCacheEntry

protected TagCacheEntry InternalGetCacheEntry(java.lang.String cacheKey,
                                              Scope scope)

Gets cache entry from the cache map

Parameters:

cacheKey -

scope -

Returns:

GetApplication

public IApplication GetApplication()

Description copied from interface: ITagState

Return the Application for use in storing data on the HTTP Application.

Most developers should use the Get/SetVariable methods instead.

Specified by:

GetApplication in interface ITagState

Returns:

The application

See Also:

ITagState.GetApplication()

GetSubSession

public ISessionManager GetSubSession()

Description copied from interface: ITagState

Returns the subsession that can be used to store data on the HTTP Session.

This SubSession is cleared of all data on logout.

Most developers should use the Get/SetVariable methods instead.

Specified by:

GetSubSession in interface ITagState

Returns:

ISessionManager The subsession that can be used to store data on the HTTP Session.

See Also:

ITagState.GetSubSession()

GetPersistentSubSession

public ISessionManager GetPersistentSubSession()

Description copied from interface: ITagState

Returns the persistent subsession that can be used to store data on the HTTP Session for use across multiple login/logout cycles.

This SubSession is not cleared of its data on user logout, so be sure not to cache anything on this session that could be considered a security risk if it was leaked to another user.

Most developers should use the normal subsession (GetSubSession()) for HTTP Session data storage, and the Get/SetVariable methods instead.

Specified by:

GetPersistentSubSession in interface ITagState

Returns:

ISessionManager The persistent subsession that can be used to store data on the HTTP Session across multiple login/logout cycles.

See Also:

ITagState.GetPersistentSubSession()

EnterTag

public void EnterTag(ATag _currentTag)

The tag container calls this method every time a new tag is displayed.

ExitTag

public void ExitTag()

The tag container calls this method when a tag is finished displaying. This will clean up data stored in the tag scope.

ResetPageRequestData

public static void ResetPageRequestData(AActivitySpace _aSpace)

This method is called at the end of every HTTP request to reset the page request data. This is a framework method and should not be called by tag developers.

Parameters:

ISessionManager - the current session manager.

ResetPortletRequestData

public void ResetPortletRequestData()

The tag container calls this method to reset the portlet request data for each portlet on a page and to verify that the TagState is in the correct state after having finished displaying all of the tags in the current portlet request.

GetHTTPRequestData

public static XPHashtable GetHTTPRequestData(AActivitySpace aSpace)

This method extracts the HTTP request data from the Activity Space.

Parameters:

aSpace - The current AActivitySpace.

Returns:

the current HTTP Request data object.

GetSharedJavascriptCollection

public static HTMLElementCollection GetSharedJavascriptCollection(AActivitySpace asOwner)

This method gets the shared JavaScript collection for this HTTP request, and initializes it if it has not been initialized yet.

Parameters:

asOwner - The current Activity Space.

Returns:

The shared JavaScript collection for this HTTP request.

SetSharedJavascriptCollectionAsDisplayed

public static void SetSharedJavascriptCollectionAsDisplayed(AActivitySpace asOwner)

This method marks the shared JavaScript collection for this HTTP request as retrieved for display.

Parameters:

asOwner - The current Activity Space.

Throws:

XPException - if this method is called more than once in an HTTP request.

GetTagName

protected java.lang.String GetTagName()

Get the name of the current tag.

Returns:

String the name of the current tag

StoreInParentTagScope

public void StoreInParentTagScope(boolean useParent)

Specified by:

StoreInParentTagScope in interface ITagState