javax.faces.application

Class StateManager

java.lang.Object

javax.faces.application.StateManager

Direct Known Subclasses:

StateManagerWrapper

public abstract class StateManager
extends Object

Responsible for storing sufficient information about a component tree so that an identical tree can later be recreated.

It is up to the concrete implementation to decide whether to use information from the "view template" that was used to first create the view, or whether to store sufficient information to enable the view to be restored without any reference to the original template. However as JSF components have mutable fields that can be set by code, and affected by user input, at least some state does need to be kept in order to recreate a previously-existing component tree.

There are two different options defined by the specification: "client" and "server" state.

When "client" state is configured, all state information required to create the tree is embedded within the data rendered to the client. Note that because data received from a remote client must always be treated as "tainted", care must be taken when using such data. Some StateManager implementations may use encryption to ensure that clients cannot modify the data, and that the data received on postback is therefore trustworthy.

When "server" state is configured, the data is saved somewhere "on the back end", and (at most) a token is embedded in the data rendered to the user.

This class is usually invoked by a concrete implementation of ViewHandler.

Note that class ViewHandler isolates JSF components from the details of the request format. This class isolates JSF components from the details of the response format. Because request and response are usually tightly coupled, the StateManager and ViewHandler implementations are also usually fairly tightly coupled (ie the ViewHandler/StateManager implementations come as pairs).

See also the JSF Specification

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	StateManager.SerializedView Deprecated.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME Indicate the viewId(s) separated by commas that should be saved and restored fully, without use Partial State Saving (PSS).
static String	IS_BUILDING_INITIAL_STATE
static String	IS_SAVING_STATE
static String	PARTIAL_STATE_SAVING_PARAM_NAME Enable or disable partial state saving algorithm.
static String	SERIALIZE_SERVER_STATE_PARAM_NAME Indicate if the state should be serialized before save it on the session.
static String	STATE_SAVING_METHOD_CLIENT
static String	STATE_SAVING_METHOD_PARAM_NAME Define the state method to be used.
static String	STATE_SAVING_METHOD_SERVER

Constructor Summary

Constructors

Constructor and Description
StateManager()

Method Summary

Modifier and Type	Method and Description
protected Object	getComponentStateToSave(FacesContext context) Deprecated.
protected Object	getTreeStructureToSave(FacesContext context) Deprecated.
String	getViewState(FacesContext context) TODO: This method should be called from somewhere when ajax response is created to update the state saving param on client.
boolean	isSavingStateInClient(FacesContext context)
protected void	restoreComponentState(FacesContext context, UIViewRoot viewRoot, String renderKitId) Deprecated.
protected UIViewRoot	restoreTreeStructure(FacesContext context, String viewId, String renderKitId) Deprecated.
abstract UIViewRoot	restoreView(FacesContext context, String viewId, String renderKitId) Deprecated.
StateManager.SerializedView	saveSerializedView(FacesContext context) Deprecated.
Object	saveView(FacesContext context) Deprecated.
void	writeState(FacesContext context, Object state) Associate the provided state object with the current response being generated.
void	writeState(FacesContext context, StateManager.SerializedView state) Deprecated.

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

@JSFWebConfigParam(defaultValue="server",
                   expectedValues="server,client",
                   since="1.1",
                   group="state",
                   tags="performance",
                   ignoreUpperLowerCase=true,
                   desc="Define the state method to be used. There are two different options defined by the specification: \'client\' and \'server\' state.")
public static final String STATE_SAVING_METHOD_PARAM_NAME

Define the state method to be used. There are two different options defined by the specification: "client" and "server" state.

When "client" state is configured, all state information required to create the tree is embedded within the data rendered to the client. Note that because data received from a remote client must always be treated as "tainted", care must be taken when using such data. Some StateManager implementations may use encryption to ensure that clients cannot modify the data, and that the data received on postback is therefore trustworthy.

When "server" state is configured, the data is saved somewhere "on the back end", and (at most) a token is embedded in the data rendered to the user.

See Also:

Constant Field Values

STATE_SAVING_METHOD_CLIENT

public static final String STATE_SAVING_METHOD_CLIENT

See Also:

Constant Field Values

STATE_SAVING_METHOD_SERVER

public static final String STATE_SAVING_METHOD_SERVER

See Also:

Constant Field Values

FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME

@JSFWebConfigParam(since="2.0",
                   group="state")
public static final String FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME

Indicate the viewId(s) separated by commas that should be saved and restored fully, without use Partial State Saving (PSS).

See Also:

Constant Field Values

PARTIAL_STATE_SAVING_PARAM_NAME

@JSFWebConfigParam(expectedValues="true,false",
                   since="2.0",
                   defaultValue="true (false with 1.2 webapps)",
                   tags="performance",
                   group="state")
public static final String PARTIAL_STATE_SAVING_PARAM_NAME

Enable or disable partial state saving algorithm.

Partial State Saving algorithm allows to reduce the size of the state required to save a view, keeping track of the "delta" or differences between the view build by first time and the current state of the view.

If the webapp faces-config file version is 2.0 or upper the default value is true, otherwise is false.

See Also:

Constant Field Values

IS_BUILDING_INITIAL_STATE

public static final String IS_BUILDING_INITIAL_STATE

See Also:

Constant Field Values

IS_SAVING_STATE

public static final String IS_SAVING_STATE

See Also:

Constant Field Values

SERIALIZE_SERVER_STATE_PARAM_NAME

@JSFWebConfigParam(since="2.2",
                   group="state",
                   tags="performance",
                   defaultValue="false",
                   expectedValues="true,false")
public static final String SERIALIZE_SERVER_STATE_PARAM_NAME

Indicate if the state should be serialized before save it on the session.

Only applicable if state saving method is "server" (= default). If true (default) the state will be serialized to a byte stream before it is written to the session. If false the state will not be serialized to a byte stream.

See Also:

Constant Field Values

Constructor Detail

StateManager

public StateManager()

Method Detail

saveSerializedView

public StateManager.SerializedView saveSerializedView(FacesContext context)

Deprecated.

Invokes getTreeStructureToSave and getComponentStateToSave, then return an object that wraps the two resulting objects. This object can then be passed to method writeState.

Deprecated; use saveView instead.

saveView

@Deprecated
public Object saveView(FacesContext context)

Deprecated.

Returns an object that is sufficient to recreate the component tree that is the viewroot of the specified context.

The return value is suitable for passing to method writeState.

Since:

1.2

getTreeStructureToSave

protected Object getTreeStructureToSave(FacesContext context)

Deprecated.

Return data that is sufficient to recreate the component tree that is the viewroot of the specified context, but without restoring the state in the components.

Using this data, a tree of components which has the same "shape" as the original component tree can be recreated. However the component instances themselves will have only their default values, ie their member fields will not have been set to the original values.

Deprecated; use saveView instead.

getComponentStateToSave

protected Object getComponentStateToSave(FacesContext context)

Deprecated.

Return data that can be applied to a component tree created using the "getTreeStructureToSave" method.

Deprecated; use saveView instead.

writeState

public void writeState(FacesContext context,
                       StateManager.SerializedView state)
                throws IOException

Deprecated.

Associate the provided state object with the current response being generated.

When client-side state is enabled, it is expected that method writes the data contained in the state parameter to the response somehow.

When server-side state is enabled, at most a "token" is expected to be written.

Deprecated; use writeState(FacesContext, Object) instead. This method was abstract in JSF1.1, but is now an empty non-abstract method so that old classes that implement this method continue to work, while new classes can just override the new writeState method rather than this one.

Throws:

IOException - never

writeState

public void writeState(FacesContext context,
                       Object state)
                throws IOException

Associate the provided state object with the current response being generated.

When client-side state is enabled, it is expected that method writes the data contained in the state parameter to the response somehow.

When server-side state is enabled, at most a "token" is expected to be written.

This method should be overridden by subclasses. It is not abstract because a default implementation is provided that forwards to the old writeState method; this allows subclasses of StateManager written using the JSF1.1 API to continue to work.

Throws:

IOException

Since:

1.2

getViewState

public String getViewState(FacesContext context)

TODO: This method should be called from somewhere when ajax response is created to update the state saving param on client. The place where this method is called is an implementation detail, so there is no references about from where in the spec javadoc.

Parameters:

context -

Returns:

Since:

2.0

restoreView

@Deprecated
public abstract UIViewRoot restoreView(FacesContext context,
                                                   String viewId,
                                                   String renderKitId)

Deprecated.

restoreTreeStructure

protected UIViewRoot restoreTreeStructure(FacesContext context,
                                          String viewId,
                                          String renderKitId)

Deprecated.

restoreComponentState

protected void restoreComponentState(FacesContext context,
                                     UIViewRoot viewRoot,
                                     String renderKitId)

Deprecated.

isSavingStateInClient

public boolean isSavingStateInClient(FacesContext context)