com.plumtree.portaluiinfrastructure.tags
Interface ITagState

All Known Implementing Classes:

TagState

public interface 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...).

Method Summary

boolean	AddCacheEntry(java.lang.String cacheKey, java.lang.Object cacheValue, Scope scope, int duration)
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)
ISessionManager	GetPersistentSubSession() Deprecated. The Persistent Session is no longer available in tags. The normal Session scope should be used instead.
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.
java.lang.Object	GetVariable(java.lang.String _strKey, Scope _scope) Gets a variable from memory in the appropriate scope.
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)

Method Detail

SetVariable

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

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.

Parameters:

String - _strKey The key used to store the data. The key cannot contain the reserved character '.'.

Object - _oValue The data to be stored. Note: setting the value to null is the same as never having set the variable.

Scope - _scope The scope to store the data in.

Throws:

XPIllegalArgumentException - if the key is null or contains the reserved character '.', or if the scope is null or unknown.

SetSharedVariable

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

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.

Parameters:

String - _strKey The key used to store the data. The key cannot contain the reserved character '.'.

Object - _oValue The data to be stored. Note: setting the value to null is the same as never having set the variable.

Scope - _scope The scope to store the data in.

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.

Throws:

XPIllegalArgumentException - if the key is null or contains the reserved character '.', or if the scope is null or unknown.

XPIllegalAccessException - if the variable is being set by a tag from a different library than the original tag that stored the variable with bOwnerEditOnly set to true.

GetVariable

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

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.

Parameters:

String - _strKey The key used to store the data. The key cannot contain the reserved character '.'.

Scope - _scope The scope used to store the data.

Returns:

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

Throws:

XPIllegalArgumentException - if the key is null or contains the reserved character '.', or if the scope is null or unknown.

GetSharedVariable

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

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.

Parameters:

String - _strKey The key used to store the data. The key cannot contain the reserved character '.'.

Scope - _scope The scope used to store the data.

Returns:

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

Throws:

XPIllegalArgumentException - if the key is null or contains the reserved character '.', or if the scope is null or unknown.

GetAnyVariable

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

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.

Parameters:

String - _strKey The key used to store the data.

Returns:

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

Throws:

XPIllegalArgumentException - if the key is null.

GetApplication

IApplication GetApplication()

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

Most developers should use the Get/SetVariable methods instead.

Returns:

The application

GetSubSession

ISessionManager GetSubSession()

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.

Returns:

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

GetPersistentSubSession

ISessionManager GetPersistentSubSession()

Deprecated. The Persistent Session is no longer available in tags. The normal Session scope should be used instead.

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.

Returns:

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

AddCacheEntry

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

GetCacheEntryData

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

StoreInParentTagScope

void StoreInParentTagScope(boolean useParent)