javax.faces.application
Class StateManager

java.lang.Object
  |
  +--javax.faces.application.StateManager

public abstract class StateManager

extends java.lang.Object

StateManager directs the process of saving and restoring the view between requests. The StateManager instance for an application is retrieved from the Application instance, and therefore cannot know any details of the markup language created by the RenderKit being used to render a view. Therefore, the StateManager utilizes a helper object (ResponseStateManager), that is provided by the RenderKit implementation and is therefore aware of the markup language details.

Nested Class Summary

class

StateManager.SerializedView Convenience struct for encapsulating tree structure and component state.

Field Summary

static java.lang.String	STATE_SAVING_METHOD_CLIENT Constant value for the initialization parameter named by the STATE_SAVING_METHOD_PARAM_NAME that indicates state saving should take place on the client.
static java.lang.String	STATE_SAVING_METHOD_PARAM_NAME The ServletContext init parameter consulted by the StateManager to tell where the state should be saved.
static java.lang.String	STATE_SAVING_METHOD_SERVER Constant value for the initialization parameter named by the STATE_SAVING_METHOD_PARAM_NAME that indicates state saving should take place on the server.

Constructor Summary

StateManager()

Method Summary

protected abstract java.lang.Object	getComponentStateToSave(javax.faces.context.FacesContext context) Convenience method, which must be called by saveSerializedView(), to construct and return a Serializable object that represents the state of all component properties, attributes, and attached objects, for the entire component tree (including children and facets) of this view.
protected abstract java.lang.Object	getTreeStructureToSave(javax.faces.context.FacesContext context) Convenience method, which must be called by saveSerializedView(), to construct and return a Serializable object that represents the structure of the entire component tree (including children and facets) of this view.
boolean	isSavingStateInClient(javax.faces.context.FacesContext context)
protected abstract void	restoreComponentState(javax.faces.context.FacesContext context, javax.faces.component.UIViewRoot viewRoot, java.lang.String renderKitId) Convenience method, which must be called by restoreView(), to restore the attributes, properties, and attached objects of all components in the restored component tree.
protected abstract javax.faces.component.UIViewRoot	restoreTreeStructure(javax.faces.context.FacesContext context, java.lang.String viewId, java.lang.String renderKitId) Convenience method, which must be called by restoreView(), to construct and return a UIViewRoot instance (populated with children and facets) representing the tree structure of the component tree being restored.
abstract javax.faces.component.UIViewRoot	restoreView(javax.faces.context.FacesContext context, java.lang.String viewId, java.lang.String renderKitId) Restore the tree structure and the component state of the view for the specified viewId, in an implementation dependent manner, and return the restored UIViewRoot.
abstract StateManager.SerializedView	saveSerializedView(javax.faces.context.FacesContext context) Return the tree structure and component state information for the view contained in the specified FacesContext instance as an object of type StateManager.SerializedView.
abstract void	writeState(javax.faces.context.FacesContext context, StateManager.SerializedView state) Save the state represented in the specified SerializedView isntance, in an implementation dependent manner.

Methods inherited from class java.lang.Object

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

Field Detail

STATE_SAVING_METHOD_PARAM_NAME

public static final java.lang.String STATE_SAVING_METHOD_PARAM_NAME

The ServletContext init parameter consulted by the StateManager to tell where the state should be saved. Valid values are given as the values of the constants: STATE_SAVING_METHOD_CLIENT or STATE_SAVING_METHOD_SERVER.

If this parameter is not specified, the default value is the value of the constant STATE_SAVING_METHOD_CLIENT.

See Also:

Constant Field Values

STATE_SAVING_METHOD_CLIENT

public static final java.lang.String STATE_SAVING_METHOD_CLIENT

Constant value for the initialization parameter named by the STATE_SAVING_METHOD_PARAM_NAME that indicates state saving should take place on the client.

See Also:

Constant Field Values

STATE_SAVING_METHOD_SERVER

public static final java.lang.String STATE_SAVING_METHOD_SERVER

Constant value for the initialization parameter named by the STATE_SAVING_METHOD_PARAM_NAME that indicates state saving should take place on the server.

See Also:

Constant Field Values

Constructor Detail

StateManager

public StateManager()

Method Detail

saveSerializedView

public abstract StateManager.SerializedView saveSerializedView(javax.faces.context.FacesContext context)

Return the tree structure and component state information for the view contained in the specified FacesContext instance as an object of type StateManager.SerializedView. If there is no state information to be saved, return null instead.

Components may opt out of being included in the serialized view by setting their transient property to true. This must cause the component itself, as well as all of that component's children and facets, to be omitted from the saved tree structure and component state information.

This method must also enforce the rule that, for components with non-null ids, all components that are descendants of the same nearest NamingContainer must have unique identifiers.

Parameters:

context - FacesContext for the current request

Throws:

java.lang.IllegalStateException - if more than one component or facet within the same NamingContainer in this view has the same non-null component id

getTreeStructureToSave

protected abstract java.lang.Object getTreeStructureToSave(javax.faces.context.FacesContext context)

Convenience method, which must be called by saveSerializedView(), to construct and return a Serializable object that represents the structure of the entire component tree (including children and facets) of this view.

Components may opt-out of being included in the tree structure by setting their transient property to true. This must cause the component itself, as well as all of that component's children and facets, to be omitted from the saved tree structure information.

PENDING(craigmcc) - Does this method need to be in the public APIs?

Parameters:

context - FacesContext for the current request

getComponentStateToSave

protected abstract java.lang.Object getComponentStateToSave(javax.faces.context.FacesContext context)

Convenience method, which must be called by saveSerializedView(), to construct and return a Serializable object that represents the state of all component properties, attributes, and attached objects, for the entire component tree (including children and facets) of this view.

Components may opt-out of being included in the component state by setting their transient property to true. This must cause the component itself, as well as all of that component's children and facets, to be omitted from the saved component state information.

PENDING(craigmcc) - Does this method need to be in the public APIs?

Parameters:

context - FacesContext for the current request

writeState

public abstract void writeState(javax.faces.context.FacesContext context,
                                StateManager.SerializedView state)
                         throws java.io.IOException

Save the state represented in the specified SerializedView isntance, in an implementation dependent manner.

This method must consult the context initialization parameter named by the symbolic constant StateManager.STATE_SAVING_METHOD_PARAMETER_NAME to determine whether state should be saved on the client or the server. If not present, client side state saving is assumed.

If the init parameter indicates that client side state saving should be used, this method must delegate the actual writing to the writeState() method of the ResponseStateManager instance provided by the RenderKit being used to render this view. This method assumes that the caller has positioned the ResponseWriter at the correct position for the saved state to be written.

If the init parameter indicates that server side state saving should be used, this method must save the state in such a manner that it may be retrieved using only the viewId.

Parameters:

context - FacesContext for the current request

state - the serialized state to be written

java.io.IOException

restoreView

public abstract javax.faces.component.UIViewRoot restoreView(javax.faces.context.FacesContext context,
                                                             java.lang.String viewId,
                                                             java.lang.String renderKitId)

Restore the tree structure and the component state of the view for the specified viewId, in an implementation dependent manner, and return the restored UIViewRoot. If there is no saved state information available for this viewId, return null instead.

This method must consult the context initialization parameter named by the symbolic constant StateManager.STATE_SAVING_METHOD_PARAMETER_NAME to determine whether state should be saved on the client or the server. If not present, client side state saving is assumed.

If the init parameter indicates that client side state saving should be used, this method must call the getTreeStructureToRestore() and (if the previous method call returned a non-null value) getComponentStateToRestore() methods of the ResponseStateManager instance provided by the RenderKit responsible for this view.

Parameters:

context - FacesContext for the current request

viewId - View identifier of the view to be restored

renderKitId - the renderKitId used to render this response. Must not be null.

Throws:

java.lang.IllegalArgumentException - if renderKitId is null.

restoreTreeStructure

protected abstract javax.faces.component.UIViewRoot restoreTreeStructure(javax.faces.context.FacesContext context,
                                                                         java.lang.String viewId,
                                                                         java.lang.String renderKitId)

Convenience method, which must be called by restoreView(), to construct and return a UIViewRoot instance (populated with children and facets) representing the tree structure of the component tree being restored. If no saved state information is available, return null instead.

PENDING(craigmcc) - Does this method need to be in the public APIs?

Parameters:

context - FacesContext for the current request

viewId - View identifier of the view to be restored

renderKitId - the renderKitId used to render this response. Must not be null.

Throws:

java.lang.IllegalArgumentException - if renderKitId is null.

restoreComponentState

protected abstract void restoreComponentState(javax.faces.context.FacesContext context,
                                              javax.faces.component.UIViewRoot viewRoot,
                                              java.lang.String renderKitId)

Convenience method, which must be called by restoreView(), to restore the attributes, properties, and attached objects of all components in the restored component tree.

PENDING(craigmcc) - Does this method need to be in the public APIs?

Parameters:

context - FacesContext for the current request

viewRoot - UIViewRoot returned by a previous call to restoreTreeStructure()

renderKitId - the renderKitId used to render this response. Must not be null.

Throws:

java.lang.IllegalArgumentException - if renderKitId is null.

isSavingStateInClient

public boolean isSavingStateInClient(javax.faces.context.FacesContext context)

Returns:

true if and only if the value of the ServletContext init parameter named by the value of the constant STATE_SAVING_METHOD_PARAM_NAME is equal to the value of the constant STATE_SAVING_METHOD_CLIENT. false otherwise.

Throws:

java.lang.NullPointerException - if context is null.