Class StateManager
- Direct Known Subclasses:
StateManagerWrapper
StateManager
directs the process of saving and
restoring the view between requests. An
implementation
of this class must be thread-safe. The StateManager
instance for an application is retrieved from the Application
instance, and thus cannot know any details of the markup language
created by the RenderKit
being used to render a view. 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
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The runtime must interpret the value of this parameter as a comma separated list of view IDs, each of which must have their state saved using the state saving mechanism specified in JSF 1.2.static final String
Marker within theFacesContext
attributes map to indicate we are marking initial state, so themarkInitialState()
method of iterating components such asUIData
could recognize this fact and save the initial state of descendents.static final String
Marker within theFacesContext
attributes map to indicate we are saving state.static final String
TheServletContext
init parameter consulted by the runtime to determine if the partial state saving mechanism should be used.static final String
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, and the javax.faces.STATE_SAVING_METHOD is set to "server" (as indicated below), the server state must be guaranteed to be Serializable such that the aggregate state implements java.io.Serializable.static final String
Constant value for the initialization parameter named by theSTATE_SAVING_METHOD_PARAM_NAME
that indicates state saving should take place on the client.static final String
TheServletContext
init parameter consulted by theStateManager
to tell where the state should be saved.static final String
Constant value for the initialization parameter named by theSTATE_SAVING_METHOD_PARAM_NAME
that indicates state saving should take place on the server. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected Object
getComponentStateToSave
(FacesContext context) Deprecated.the distinction between tree structure and component state is now an implementation detail.protected Object
getTreeStructureToSave
(FacesContext context) Deprecated.the distinction between tree structure and component state is now an implementation detail.getViewState
(FacesContext context) Convenience method to return the view state as aString
with noRenderKit
specific markup.boolean
isSavingStateInClient
(FacesContext context) protected void
restoreComponentState
(FacesContext context, UIViewRoot viewRoot, String renderKitId) Deprecated.the distinction between tree structure and component state is now an implementation detail.protected UIViewRoot
restoreTreeStructure
(FacesContext context, String viewId, String renderKitId) Deprecated.the distinction between tree structure and component state is now an implementation detail.abstract UIViewRoot
restoreView
(FacesContext context, String viewId, String renderKitId) Deprecated.saveSerializedView
(FacesContext context) Deprecated.this has been replaced bysaveView(javax.faces.context.FacesContext)
.saveView
(FacesContext context) Deprecated.void
writeState
(FacesContext context, Object state) Save the state represented in the specified stateObject
instance, in an implementation dependent manner.void
writeState
(FacesContext context, StateManager.SerializedView state) Deprecated.This method has been replaced bywriteState(javax.faces.context.FacesContext,java.lang.Object)
.
-
Field Details
-
STATE_SAVING_METHOD_PARAM_NAME
The
ServletContext
init parameter consulted by theStateManager
to tell where the state should be saved. Valid values are given as the values of the constants:STATE_SAVING_METHOD_CLIENT
orSTATE_SAVING_METHOD_SERVER
.If this parameter is not specified, the default value is the value of the constant
STATE_SAVING_METHOD_CLIENT
.- See Also:
-
PARTIAL_STATE_SAVING_PARAM_NAME
The
ServletContext
init parameter consulted by the runtime to determine if the partial state saving mechanism should be used.If undefined, the runtime must determine the version level of the application.
For applications versioned at 1.2 and under, the runtime must not use the partial state saving mechanism.
For applications versioned at 2.0 and above, the runtime must use the partial state saving mechanism.
If this parameter is defined, and the application is versioned at 1.2 and under, the runtime must not use the partial state saving mechanism. Otherwise, If this param is defined, and calling
toLowerCase().equals("true")
on aString
representation of its value returnstrue
, the runtime must use partial state mechanism. Otherwise the partial state saving mechanism must not be used.- Since:
- 2.0
- See Also:
-
FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME
The runtime must interpret the value of this parameter as a comma separated list of view IDs, each of which must have their state saved using the state saving mechanism specified in JSF 1.2.
- See Also:
-
IS_SAVING_STATE
Marker within the
FacesContext
attributes map to indicate we are saving state. The implementation must set this marker into the map before starting the state saving traversal and the marker must be cleared, in a finally block, after the traversal is complete.- See Also:
-
IS_BUILDING_INITIAL_STATE
Marker within the
FacesContext
attributes map to indicate we are marking initial state, so themarkInitialState()
method of iterating components such asUIData
could recognize this fact and save the initial state of descendents.- Since:
- 2.1
- See Also:
-
SERIALIZE_SERVER_STATE_PARAM_NAME
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, and the javax.faces.STATE_SAVING_METHOD is set to "server" (as indicated below), the server state must be guaranteed to be Serializable such that the aggregate state implements java.io.Serializable. The intent of this parameter is to ensure that the act of writing out the state to an ObjectOutputStream would not throw a NotSerializableException, but the runtime is not required verify this before saving the state.
- Since:
- 2.2
- See Also:
-
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:
-
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:
-
-
Constructor Details
-
StateManager
public StateManager()
-
-
Method Details
-
saveSerializedView
Deprecated.this has been replaced bysaveView(javax.faces.context.FacesContext)
. The default implementation callssaveView
and inspects the return. If the return is anObject []
, it casts the result to anObject []
wrapping the first and second elements in an instance ofStateManager.SerializedView
, which it then returns. Otherwise, it returnsnull
Return the tree structure and component state information for the view contained in the specified
FacesContext
instance as an object of typeStateManager.SerializedView
. If there is no state information to be saved, returnnull
instead.Components may opt out of being included in the serialized view by setting their
transient
property totrue
. 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
id
s, all components that are descendants of the same nearestNamingContainer
must have unique identifiers.- Parameters:
context
-FacesContext
for the current request- Throws:
IllegalStateException
- if more than one component or facet within the sameNamingContainer
in this view has the same non-null
component id
-
saveView
Deprecated.The functionality of this method is now handled by
StateManagementStrategy.saveView(javax.faces.context.FacesContext)
. Return an opaqueObject
containing sufficient information for this same instance to restore the state of the currentUIViewRoot
on a subsequent request. The returned object must implementjava.io.Serializable
. If there is no state information to be saved, returnnull
instead.Components may opt out of being included in the serialized view by setting their
transient
property totrue
. 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
id
s, all components that are descendants of the same nearestNamingContainer
must have unique identifiers.For backwards compatability with existing
StateManager
implementations, the default implementation of this method callssaveSerializedView(javax.faces.context.FacesContext)
and creates and returns a two elementObject
array with element zero containing thestructure
property and element one containing thestate
property of theSerializedView
.- Parameters:
context
-FacesContext
for the current request- Throws:
IllegalStateException
- if more than one component or facet within the sameNamingContainer
in this view has the same non-null
component id- Since:
- 1.2
-
getTreeStructureToSave
Deprecated.the distinction between tree structure and component state is now an implementation detail. The default implementation returnsnull
.Convenience method, which must be called by
saveSerializedView()
, to construct and return aSerializable
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 totrue
. 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.- Parameters:
context
-FacesContext
for the current request
-
getComponentStateToSave
Deprecated.the distinction between tree structure and component state is now an implementation detail. The default implementation returnsnull
.Convenience method, which must be called by
saveSerializedView()
, to construct and return aSerializable
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 totrue
. 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.- Parameters:
context
-FacesContext
for the current request
-
writeState
Save the state represented in the specified state
Object
instance, in an implementation dependent manner.This method will typically simply delegate the actual writing to the
writeState()
method of theResponseStateManager
instance provided by theRenderKit
being used to render this view. This method assumes that the caller has positioned theResponseWriter
at the correct position for the saved state to be written.For backwards compatability with existing
StateManager
implementations, the default implementation of this method checks if the argument is an instance ofObject []
of length greater than or equal to two. If so, it creates aSerializedView
instance with the tree structure coming from element zero and the component state coming from element one and calls through towriteState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)
. If not, does nothing.- Parameters:
context
-FacesContext
for the current requeststate
- the Serializable state to be written, as returned bysaveSerializedView(javax.faces.context.FacesContext)
- Throws:
IOException
- Since:
- 1.2
-
writeState
Deprecated.This method has been replaced bywriteState(javax.faces.context.FacesContext,java.lang.Object)
. The default implementation calls the non-deprecated variant of the method passing anObject []
as the second argument, where the first element of the array is the return fromgetStructure()
and the second is the return fromgetState()
on the argumentstate
.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_PARAM_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 theResponseStateManager
instance provided by theRenderKit
being used to render this view. This method assumes that the caller has positioned theResponseWriter
at the correct position for the saved state to be written.- Parameters:
context
-FacesContext
for the current requeststate
- the serialized state to be written- Throws:
IOException
-
restoreView
@Deprecated public abstract UIViewRoot restoreView(FacesContext context, String viewId, String renderKitId) Deprecated.The functionality of this method is now handled by
StateManagementStrategy.restoreView(javax.faces.context.FacesContext, java.lang.String, java.lang.String)
. Restore the tree structure and the component state of the view for the specifiedviewId
, in an implementation dependent manner, and return the restoredUIViewRoot
. If there is no saved state information available for thisviewId
, returnnull
instead.This method must consult the context initialization parameter named by the symbolic constant
StateManager.STATE_SAVING_METHOD_PARAM_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 theResponseStateManager
instance provided by theRenderKit
responsible for this view.- Parameters:
context
-FacesContext
for the current requestviewId
- View identifier of the view to be restoredrenderKitId
- the renderKitId used to render this response. Must not benull
.- Throws:
IllegalArgumentException
- ifrenderKitId
isnull
.
-
restoreTreeStructure
Deprecated.the distinction between tree structure and component state is now an implementation detail. The default implementation returnsnull
.Convenience method, which must be called by
restoreView()
, to construct and return aUIViewRoot
instance (populated with children and facets) representing the tree structure of the component tree being restored. If no saved state information is available, returnnull
instead.- Parameters:
context
-FacesContext
for the current requestviewId
- View identifier of the view to be restoredrenderKitId
- the renderKitId used to render this response. Must not benull
.- Throws:
IllegalArgumentException
- ifrenderKitId
isnull
.
-
restoreComponentState
Deprecated.the distinction between tree structure and component state is now an implementation detail. The default implementation does nothing.Convenience method, which must be called by
restoreView()
, to restore the attributes, properties, and attached objects of all components in the restored component tree.- Parameters:
context
-FacesContext
for the current requestviewRoot
-UIViewRoot
returned by a previous call torestoreTreeStructure()
renderKitId
- the renderKitId used to render this response. Must not benull
.- Throws:
IllegalArgumentException
- ifrenderKitId
isnull
.
-
isSavingStateInClient
- Returns:
true
if and only if the value of theServletContext
init parameter named by the value of the constantSTATE_SAVING_METHOD_PARAM_NAME
is equal to the value of the constantSTATE_SAVING_METHOD_CLIENT
.false
otherwise.- Throws:
NullPointerException
- ifcontext
isnull
.
-
getViewState
Convenience method to return the view state as a
String
with noRenderKit
specific markup. This default implementation of this method will callsaveView(javax.faces.context.FacesContext)
and passing the result to and returning the resulting value fromResponseStateManager.getViewState(javax.faces.context.FacesContext, Object)
.- Parameters:
context
-FacesContext
for the current request- Since:
- 2.0
-
Serializable
in the 1.0 version of the spec.