public abstract class

AbstractWebComponent

extends AbstractTransformable
implements WebComponent
java.lang.Object
   ↳ com.microstrategy.utils.serialization.AbstractPersistable
     ↳ com.microstrategy.web.beans.AbstractTransformable
       ↳ com.microstrategy.web.beans.AbstractWebComponent
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

This class provides a skeletal implementation of the WebComponent interface to minimize the effort required to implement this interface.

A WebComponent maintains a cache of component state for itself. Any structural modification to the component should invalidate this cached state.

Summary

[Expand]
Inherited Constants
From interface com.microstrategy.utils.serialization.EnumWebPersistableState
Fields
protected WebFeatures _features Represents a WebFeatures
protected boolean _hasJustOpened
[Expand]
Inherited Fields
From class com.microstrategy.web.beans.AbstractTransformable
Public Constructors
AbstractWebComponent()
Default constructor, setting the component name to 'wc' followed a unique id.
Protected Constructors
AbstractWebComponent(boolean needEventHandler)
Public Methods
void addChild(String key, WebComponent child)
Adds a child component to the current WebComponent.
void addChildStateInfo(ParameterBuilder paramBldr, String state, int howMuchState)
Adds children state information into an existing ParameterBuilder instance.
void addChildStateInfo(ParameterBuilder paramBldr, int howMuchState)
Adds children state information into an existing ParameterBuilder instance.
void addChildStateInfo(ParameterBuilder paramBldr, String state)
void addChildStateInfo(ParameterBuilder paramBldr)
Adds children state information into an existing ParameterBuilder instance.
void clearChildren()
Removes all the child component instances from this component.
void collectData()
Triggers execution to the back end no matter whether it is synchronous or asynchronous.
void collectMinimalData()
This is similar to collectData() except data collected is minimal.
WebComponent getChild(int index)
Returns the child WebComponent specified by the index.
WebComponent getChild(String path)
Returns the bottom child component at the specified path.
WebComponent getChildByClass(Class classInstance)
Returns the child WebComponent instance specified by the class.
WebComponent getChildByType(int childType)
Returns the child WebComponent instance specified by the type.
int getChildCount()
Returns the total number of child component in the current WebComponent.
void getChildrenByClass(Class classInstance, HashList retList, boolean recursive)
Returns the child WebComponent instance specified by the class.
int getDefaultStateLevel()
Returns the default state level.
WebFeatures getFeaturesManager()
Return the WebFeatures implementation associated with this WebComponent
int getMaximumStateLevel()
Returns either the default state level of the current component or the maximum state level among the current component and its child components, whichever is greater.
String getName()
Returns the name of the current component.
int getOutputFormat()
Returns the output format of EnumBeanOutputFormat of the current WebComponent.
WebComponent getParent()
Returns the parent component of this component.
String getPath()
Returns the path, starting from the root component to this component.
int getPersistMode()
Returns the persist flag (EnumBeanPersistMode) of the current WebComponent.
Set getRenderingFilter()
returns the rendering filter.
WebComponent getRoot()
Returns the root component reachable from the current component.
WebComponent getTargetBean()
Get the target bean associated with this instance
String getTargetBeanPath()
WebEvent getWebEvent(int eventID, boolean recurse)
Returns the WebEvent denoted by the event ID.
WebEvent getWebEvent(int eventID)
Returns the WebEvent denoted by the event ID.
WebEventHandler getWebEventHandler()
Returns the WebEventHandler instance associated with this component.
boolean handleRequest(RequestKeys keys)
Handles the request specified by the RequestKeys instance.
boolean hasChanged()
Verifies the state of the component has changed
boolean hasJustOpened()
Verifies if the component has just been opened.
void initBean()
Initialize the component after it's created and its properties initialized
void invalidateChildrenState()
Invalidates the cached state of a component and its children.
boolean isBeanContextEmpty()
Verifies if a bean context exists for the current WebComponent.
boolean isFeatureAvailable(String featureList)

Verifies if the corresponding feature(s) is accesible based on the properties of this WebComponent.

void prepareForReuse()
If a Web Component instance is going to be reused across different requests, this API serves as a notifier to the component to do the necessary cleanup.
WebComponent removeChild(WebComponent component)
Removes the specified child component from the current component.
WebComponent removeChild(String key)
Removes the specified child component from the current component.
boolean restoreState(String state)
Restores a component based on its saved state.
boolean restoreStateFromRequest(RequestKeys rk)
Restores this component from the saved state keyed by this component's name in the RequestKeys object.
boolean restoreStateFromRequest(RequestKeys rk, String keyName)
Restores this component from the saved state keyed by keyName in the RequestKeys object.
WebComponent searchChild(String key)
Searches whole hierarchy rooted at the current component for the child component specified the key and returns the search result.
void setBeanContext(BeanContext beanContext, boolean forceUpdateChildren)
Sets an instance of BeanContext on the current WebBean.
void setBeanContext(BeanContext beanContext)
Sets an instance of BeanContext on the current WebBean.
void setChanged(boolean value, boolean recurse)
Sets the changed state of the component
void setChanged(boolean value)
Sets the changed state of the component
void setDefaultStateLevel(int stateLevel)
Set the default state level.
void setFeaturesManager(WebFeatures featuresManager)
Associates a WebFeatures implementation with this WebComponent
void setName(String name)
Sets the name for the current component.
void setOutputFormat(int outputFormat)
Sets the output format of EnumBeanOutputFormat for the current WebComponent.
void setParent(WebComponent parentComponent)
Sets the parent component for the current component
void setPersistMode(int persistFlag)
Sets the persist flag (EnumBeanPersistMode) of the current WebComponent.
void setRenderingFilter(Set renderingFilter)
Sets the list of beans to render.
void setTargetBean(WebComponent bean)
Set the target bean that will be associated with this instance.
void setTargetBeanPath(String beanName)
Define the base bean for this instance.
void setWebEventHandler(WebEventHandler eventHandler)
Associate with this component a WebEventHandler instance.
Protected Methods
void addChildStateInfo(ParameterBuilder paramBldr, WebComponent wc)
void addStateInfo(ParameterBuilder paramBldr, int howMuchState)
Collection childValues()
void clearStateCache(int howMuchToClear)
Clears the cached state for the current component only, without touching any child component's state.
String getCachedState(int whatState)
Return the cached state specified by the whatState.
boolean haveChildrenChanged()
boolean isChangeComparisonFlagSet(int stateFlag)
WebEventHandler newDefaultEventHandler()
StyleRequestContext newStyleRequestContext()
void saveXMLState(XMLStateSerializer builder, int howMuchState, int stateFlag)
Saves the component state
void saveXMLState(StringBuffer buf, int howMuchState, int stateFlag)
Saves the component state in the provided StringBuffer
void saveXMLState(XMLStateSerializer builder, int howMuchState)
Saves the component state
void setStateCache(int whatState, String stateToSave)
Caches the state specified by whatState.
[Expand]
Inherited Methods
From class com.microstrategy.web.beans.AbstractTransformable
From class com.microstrategy.utils.serialization.AbstractPersistable
From class java.lang.Object
From interface com.microstrategy.utils.serialization.Persistable
From interface com.microstrategy.web.beans.Transformable
From interface com.microstrategy.web.beans.WebComponent

Fields

protected WebFeatures _features

Represents a WebFeatures

protected boolean _hasJustOpened

Public Constructors

public AbstractWebComponent ()

Default constructor, setting the component name to 'wc' followed a unique id.

Protected Constructors

protected AbstractWebComponent (boolean needEventHandler)

Public Methods

public void addChild (String key, WebComponent child)

Adds a child component to the current WebComponent. This call invalidates the cached states.

Parameters
key the key mapped to the child component.
child the child component to add.

public void addChildStateInfo (ParameterBuilder paramBldr, String state, int howMuchState)

Adds children state information into an existing ParameterBuilder instance. It is up to the supplied ParameterBuilder to determine how this information is serialized.

Parameters
paramBldr The ParameterBuilder instance which has child state information added to it.
state The actual state string to add for this component.
howMuchState The amount of state to add for each child component. to return from its children.

public void addChildStateInfo (ParameterBuilder paramBldr, int howMuchState)

Adds children state information into an existing ParameterBuilder instance. It is up to the supplied ParameterBuilder to determine how this information is serialized.

Parameters
paramBldr The ParameterBuilder instance which has child state information added to it.
howMuchState How much state is added. (see EnumWebPersistableState for details).

public void addChildStateInfo (ParameterBuilder paramBldr, String state)

public void addChildStateInfo (ParameterBuilder paramBldr)

Adds children state information into an existing ParameterBuilder instance. It is up to the supplied ParameterBuilder to determine how this information is serialized. Each WebComponent the hierarchy serializes its state according to its own getDefaultStateLevel().

Parameters
paramBldr The ParameterBuilder instance which has child state information added to it.

public void clearChildren ()

Removes all the child component instances from this component. This call invalidates the cached states.

public void collectData ()

Triggers execution to the back end no matter whether it is synchronous or asynchronous. If this method fails to collect data, an exception is raised and saved in a WebBeanError instance.

Throws
WebBeanException thrown if there is any exception

public void collectMinimalData ()

This is similar to collectData() except data collected is minimal. This is essentially a check to ensure everything is ok, but that we don't need any data. After invoking this operation, see getXMLStatus() and getErrorInfo() for details.

Throws
WebBeanException

public WebComponent getChild (int index)

Returns the child WebComponent specified by the index.

Parameters
index position of the child component in the current component.
Returns
  • the child component at the specified position; null if the index is out of bounds.

public WebComponent getChild (String path)

Returns the bottom child component at the specified path. The path starts from the root WebComponent all the way down the bottom child in the hierarchy. Each component appearing in the path is represented by its name and all components are separated by the character dot. For example, the path key1.key2.key3 says that the root component is key1 and component key3 is one of the grand children of key1.

Parameters
path the path to the child WebComponent.
Returns
  • the bottom child component along the path; null if the child is not found.

public WebComponent getChildByClass (Class classInstance)

Returns the child WebComponent instance specified by the class.

Parameters
classInstance the classInstance mapped to the WebComponent class instance.
Returns
  • the child WebComponent instance; null if the classInstance is not mapped to any child WebComponent.

public WebComponent getChildByType (int childType)

Returns the child WebComponent instance specified by the type.

Parameters
childType the childType mapped to the WebComponent child type.
Returns
  • the child WebComponent instance; null if the childType is not mapped to any child WebComponent.

public int getChildCount ()

Returns the total number of child component in the current WebComponent.

Returns
  • the number of children.

public void getChildrenByClass (Class classInstance, HashList retList, boolean recursive)

Returns the child WebComponent instance specified by the class. If recursive is true, recursively searchs for children components.

Parameters
classInstance the Class instance mapped to the WebComponent class instance.
retList a HashList to store the result
recursive true means searching recursively.

public int getDefaultStateLevel ()

Returns the default state level. If not set, the default state level is EnumWebPersistableState.MINIMAL_STATE_INFO.

Returns
  • the defautl state level.

public WebFeatures getFeaturesManager ()

Return the WebFeatures implementation associated with this WebComponent

Returns
  • a WebFeatures instance

public int getMaximumStateLevel ()

Returns either the default state level of the current component or the maximum state level among the current component and its child components, whichever is greater.

Returns
  • the maximum state level.

public String getName ()

Returns the name of the current component.

Returns
  • the name of this component.

public int getOutputFormat ()

Returns the output format of EnumBeanOutputFormat of the current WebComponent.

Returns
  • the output format of this component.

public WebComponent getParent ()

Returns the parent component of this component.

Returns
  • the parent component.

public String getPath ()

Returns the path, starting from the root component to this component. The path is reprensented by component names and separated by the character dot.

Returns
  • the path to the current component, reachable from the root component.

public int getPersistMode ()

Returns the persist flag (EnumBeanPersistMode) of the current WebComponent.

Returns
  • the persist flag of the current WebComponent.

public Set getRenderingFilter ()

returns the rendering filter.

Returns
  • rendering filter.

public WebComponent getRoot ()

Returns the root component reachable from the current component. This method returns itself if it does not have any parent.

Returns
  • the root component; itself if there is not parent.

public WebComponent getTargetBean ()

Get the target bean associated with this instance

Returns
  • WebComponent instance associated with this bean. By default if the base bean property has been defined, the target bean to return is the corresponding instance associated with the name and path specified. If nothing has been specified then it will return the first WEB_BEAN_REPORT, WEB_BEAN_DOCUMENT or WEB_BEAN_RW instance found.

public String getTargetBeanPath ()

Returns
  • a String value with the name of the bean defined to be associated with this instance, if any.

public WebEvent getWebEvent (int eventID, boolean recurse)

Returns the WebEvent denoted by the event ID. This method queries the current component first, and then turns to ask for its parent component if the current component does not support the specified event, until it reaches the root component. If the event is still not found and the parameter recurse is true, then it starts to search the whole hierarchy in depth-first pattern.

Parameters
eventID the event id to search.
recurse true if the search is recursive.
Returns
  • the specified WebEvent; null if there is no such an event existing.

public WebEvent getWebEvent (int eventID)

Returns the WebEvent denoted by the event ID. This method queries the current component first, and then turns to ask for its parent component if the current component does not support the specified event, until it reaches the root component.

Parameters
eventID the event ID associated with a WebEvent.
Returns
  • a WebEvent denoted by the event ID. null if there is no such an event.

public WebEventHandler getWebEventHandler ()

Returns the WebEventHandler instance associated with this component.

Returns
  • the WebEventHandler; null if it does not exist.

public boolean handleRequest (RequestKeys keys)

Handles the request specified by the RequestKeys instance. The RequestKeys object might contain all information sent from the Web browser along with any cookies, session variables, etc. Most importantly, it contains WebEvent related information. If this instance in the namespace of the src request key attribute, it will forward the request to its associated event handler.

Parameters
keys the RequestKeys object.
Returns
  • true if the request is successfully handled; false if the request or event is not supported.
Throws
WebException thrown if there is any error occurred when handling the request.

public boolean hasChanged ()

Verifies the state of the component has changed

Returns
  • true if the component is changed

public boolean hasJustOpened ()

Verifies if the component has just been opened. This would mean that the current event processed would be an event to open this component.

Returns
  • true if the component has just been opened.

public void initBean ()

Initialize the component after it's created and its properties initialized

public void invalidateChildrenState ()

Invalidates the cached state of a component and its children.

public boolean isBeanContextEmpty ()

Verifies if a bean context exists for the current WebComponent. This method exists because getBeanContext will automatically create a default bean context. Hence we cannot getBeanContext check if it is null

See Also

public boolean isFeatureAvailable (String featureList)

Verifies if the corresponding feature(s) is accesible based on the properties of this WebComponent.

This method receives a semi-colon (i.e. FeatureArray#FEATURE_ARRAY_DELIMITER_STRING) separated list of features to validate. Each feature can be prefixed with "!" to indicate the return value should be negated. For example, if the following value is received as argument:

a;!b;c
will return true if and only if:
  1. a is available
  2. b is not available
  3. c is available.
For each feature in the list to be available, this method first will check if its available in the Global Features. If available there, then it will check with its parent WebComponent (if any).

Parameters
featureList a semi-colon separated list of feature ids to check.
Returns
  • true indicating if the compound feature is accesible or not

public void prepareForReuse ()

If a Web Component instance is going to be reused across different requests, this API serves as a notifier to the component to do the necessary cleanup.

public WebComponent removeChild (WebComponent component)

Removes the specified child component from the current component.

Parameters
component the child component to be removed.
Returns
  • the removed child component.

public WebComponent removeChild (String key)

Removes the specified child component from the current component. This call invalidates the cached states.

Parameters
key the key mapped to the child component.
Returns
  • the removed child component.

public boolean restoreState (String state)

Restores a component based on its saved state.

Parameters
state the state of a component
Returns
  • true if restoration succeeds.

public boolean restoreStateFromRequest (RequestKeys rk)

Restores this component from the saved state keyed by this component's name in the RequestKeys object. When restoring its own state, this component may delegate restoration to its child components. This method is equivalent to call restoreStateFromRequest(rk, getName()).

Parameters
rk the RequestKeys object containing the saved state of this component.
Returns
  • true if restoration is successful; false otherwise.

public boolean restoreStateFromRequest (RequestKeys rk, String keyName)

Restores this component from the saved state keyed by keyName in the RequestKeys object. When restoring its own state, this component may delegate restoration to its child components.

Parameters
rk the RequestKeys object containing the saved state of this component.
keyName the key whose corresponding value contains the saved state of this component.
Returns
  • true if restoration is successful; false otherwise.

public WebComponent searchChild (String key)

Searches whole hierarchy rooted at the current component for the child component specified the key and returns the search result. The search starts with the immediate children of the current component, if not found, then it propagate to its grand children in depth-first manner.

Parameters
key the key mapped to the child component to be searched.
Returns
  • the child WebComponent; null if there is no such a component existing in the hierarchy.

public void setBeanContext (BeanContext beanContext, boolean forceUpdateChildren)

Sets an instance of BeanContext on the current WebBean.

Parameters
beanContext the BeanContext instance to set.
forceUpdateChildren if true, the same context is set on the bean's children, if false, the context is set only if a child bean's context is empty

public void setBeanContext (BeanContext beanContext)

Sets an instance of BeanContext on the current WebBean.

Parameters
beanContext the BeanContext instance to set.
See Also

public void setChanged (boolean value, boolean recurse)

Sets the changed state of the component

Parameters
value a boolean value indicating whether the component is changed
recurse boolean to indicate whether the value needs to be propogated to child components.

public void setChanged (boolean value)

Sets the changed state of the component

Parameters
value a boolean value indicating whether the component is changed.

public void setDefaultStateLevel (int stateLevel)

Set the default state level. If not set, the default state level is EnumWebPersistableState.MINIMAL_STATE_INFO.

Parameters
stateLevel A value from EnumWebPersistableState which indicates the default state level to use.

public void setFeaturesManager (WebFeatures featuresManager)

Associates a WebFeatures implementation with this WebComponent

Parameters
featuresManager a WebFeatures object.

public void setName (String name)

Sets the name for the current component.

Parameters
name the name of the current component.

public void setOutputFormat (int outputFormat)

Sets the output format of EnumBeanOutputFormat for the current WebComponent.

Parameters
outputFormat the output format of EnumBeanOutputFormat.

public void setParent (WebComponent parentComponent)

Sets the parent component for the current component

Parameters
parentComponent the parent component.

public void setPersistMode (int persistFlag)

Sets the persist flag (EnumBeanPersistMode) of the current WebComponent.

Parameters
persistFlag the persist flag (EnumBeanPersistMode).

public void setRenderingFilter (Set renderingFilter)

Sets the list of beans to render. The idea here is that, sometimes during an iframe request even though a bean has changed, there might be some beans (e.g. Toolbar) who should'nt need to render themselves just because they have this component as their targetBeanPath. renderingFilter should help control that.

Parameters
renderingFilter a Set of Strings representing beanNames

public void setTargetBean (WebComponent bean)

Set the target bean that will be associated with this instance.

Parameters
bean WebComponent instance to be associated with this bean.

public void setTargetBeanPath (String beanName)

Define the base bean for this instance.

Parameters
beanName String with the name of the bean (with path information if necessary) to be set as the base bean for this instance.

public void setWebEventHandler (WebEventHandler eventHandler)

Associate with this component a WebEventHandler instance.

A WebComponent has one to one relationship with a WebEventHandler instance. This method first removes any existing handler associated with this component, and then sets the new one on it.

This method calls the method setWebComponent(WebComponent). Therefore, the WebEventHandler implementator should be careful to avoid cyclic reference to each other between this component and the event handler.

Parameters
eventHandler the WebEventHandler instance to set.

Protected Methods

protected void addChildStateInfo (ParameterBuilder paramBldr, WebComponent wc)

protected void addStateInfo (ParameterBuilder paramBldr, int howMuchState)

protected Collection childValues ()

protected void clearStateCache (int howMuchToClear)

Clears the cached state for the current component only, without touching any child component's state.

Since typical state usually contains information saved in the minimum state, clearing minimum state should invalidate the cached typical state too, but not vice versa.

Parameters
howMuchToClear a flag of EnumWebPersistableState indicating how much state to clear.

protected String getCachedState (int whatState)

Return the cached state specified by the whatState. Only typical and minimum states are cached.

Parameters
whatState a value from the EnumWebPersistableState indicating what state to return.
Returns
  • the cached state. null if the cache is invalid.

protected boolean haveChildrenChanged ()

protected boolean isChangeComparisonFlagSet (int stateFlag)

protected WebEventHandler newDefaultEventHandler ()

protected StyleRequestContext newStyleRequestContext ()

protected void saveXMLState (XMLStateSerializer builder, int howMuchState, int stateFlag)

Saves the component state

Parameters
builder a XMLStateSerializer object
howMuchState how much state to save (EnumWebPersistableState)
stateFlag TODO

protected void saveXMLState (StringBuffer buf, int howMuchState, int stateFlag)

Saves the component state in the provided StringBuffer

Parameters
buf a StringBuffer object
howMuchState how much state to save (EnumWebPersistableState)

protected void saveXMLState (XMLStateSerializer builder, int howMuchState)

Saves the component state

Parameters
builder a XMLStateSerializer object
howMuchState how much state to save (EnumWebPersistableState)

protected void setStateCache (int whatState, String stateToSave)

Caches the state specified by whatState.

Parameters
whatState a value from the EnumWebPersistableState indicating what state to return.
stateToSave the component's state to be cached