public abstract class StateManager extends Object
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.
Modifier and Type | Class and Description |
---|---|
class |
StateManager.SerializedView
Deprecated.
This class was not marked
Serializable
in the 1.0 version of the spec. It was also not a static inner
class, so it can't be made to be Serializable .
Therefore, it is being deprecated in version 1.2 of the spec.
The replacement is to use an implementation dependent
Object . |
Modifier and Type | Field and Description |
---|---|
static String |
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. |
static String |
IS_BUILDING_INITIAL_STATE
Marker within the
|
static String |
IS_SAVING_STATE
Marker within the
|
static String |
PARTIAL_STATE_SAVING_PARAM_NAME
The |
static String |
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. |
static 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 String |
STATE_SAVING_METHOD_PARAM_NAME
The
ServletContext init parameter consulted by
the StateManager to tell where the state should be
saved. |
static 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 and Description |
---|
StateManager() |
Modifier and Type | Method and Description |
---|---|
protected Object |
getComponentStateToSave(FacesContext context)
Deprecated.
the distinction between tree structure and component
state is now an implementation detail. The default
implementation returns
null . |
protected Object |
getTreeStructureToSave(FacesContext context)
Deprecated.
the distinction between tree structure and component
state is now an implementation detail. The default
implementation returns
null . |
String |
getViewState(FacesContext context)
Convenience method to return the view state as a |
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. The default
implementation does nothing.
|
protected UIViewRoot |
restoreTreeStructure(FacesContext context,
String viewId,
String renderKitId)
Deprecated.
the distinction between tree structure and component
state is now an implementation detail. The default
implementation returns
null . |
abstract UIViewRoot |
restoreView(FacesContext context,
String viewId,
String renderKitId)
Deprecated.
|
StateManager.SerializedView |
saveSerializedView(FacesContext context)
Deprecated.
this has been replaced by
saveView(javax.faces.context.FacesContext) . The
default implementation calls saveView and inspects the
return. If the return is an Object [] , it casts the
result to an Object [] wrapping the first and second
elements in an instance of StateManager.SerializedView , which it then
returns. Otherwise, it returns null |
Object |
saveView(FacesContext context)
Deprecated.
|
void |
writeState(FacesContext context,
Object state)
Save the state represented in the specified state
Object instance, in an implementation dependent
manner. |
void |
writeState(FacesContext context,
StateManager.SerializedView state)
Deprecated.
This method has been replaced by
writeState(javax.faces.context.FacesContext,java.lang.Object) .
The default implementation calls the non-deprecated variant
of the method passing an Object [] as the second
argument, where the first element of the array is the return from
getStructure() and the second is the return from
getState() on the argument state . |
public static final 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
.
public static final String 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 a
String
representation of its value returns
true
, the runtime must use partial state mechanism.
Otherwise the partial state saving mechanism must not be
used.
public static final String 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.
public static final String 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.
public static final String IS_BUILDING_INITIAL_STATE
Marker within the
FacesContext
attributes map to indicate we are
marking initial state, so the markInitialState()
method of iterating components such as UIData
could recognize this fact and save
the initial state of descendents.
public static final String 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.
public static final 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.
public static final 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.
public StateManager.SerializedView saveSerializedView(FacesContext context)
saveView(javax.faces.context.FacesContext)
. The
default implementation calls saveView
and inspects the
return. If the return is an Object []
, it casts the
result to an Object []
wrapping the first and second
elements in an instance of StateManager.SerializedView
, which it then
returns. Otherwise, it returns null
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 id
s, all components that are descendants of the
same nearest NamingContainer
must have unique identifiers.
context
- FacesContext
for the current requestIllegalStateException
- if more than one component or
facet within the same NamingContainer
in this view has
the same non-null
component id@Deprecated public Object saveView(FacesContext context)
The functionality of this method
is now handled by StateManagementStrategy.saveView(javax.faces.context.FacesContext)
.
Return an opaque Object
containing sufficient
information for this same instance to restore the state of the
current UIViewRoot
on a subsequent request. The returned
object must implement java.io.Serializable
. 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 id
s, all components that are descendants of the
same nearest NamingContainer
must have unique identifiers.
For backwards compatability with existing
StateManager
implementations, the default
implementation of this method calls saveSerializedView(javax.faces.context.FacesContext)
and creates and returns a two element Object
array
with element zero containing the structure
property
and element one containing the state
property of the
SerializedView
.
context
- FacesContext
for the current requestIllegalStateException
- if more than one component or
facet within the same NamingContainer
in this view has
the same non-null
component idprotected Object getTreeStructureToSave(FacesContext context)
null
.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.
context
- FacesContext
for the current requestprotected Object getComponentStateToSave(FacesContext context)
null
.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.
context
- FacesContext
for the current requestpublic void writeState(FacesContext context, Object state) throws IOException
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 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.
For backwards compatability with existing
StateManager
implementations, the default
implementation of this method checks if the argument is an
instance of Object []
of length greater than or
equal to two. If so, it creates a SerializedView
instance with the tree structure coming from element zero and
the component state coming from element one and calls through to
writeState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)
.
If not, does nothing.
context
- FacesContext
for the current requeststate
- the Serializable state to be written,
as returned by saveSerializedView(javax.faces.context.FacesContext)
IOException
public void writeState(FacesContext context, StateManager.SerializedView state) throws IOException
writeState(javax.faces.context.FacesContext,java.lang.Object)
.
The default implementation calls the non-deprecated variant
of the method passing an Object []
as the second
argument, where the first element of the array is the return from
getStructure()
and the second is the return from
getState()
on the argument state
.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 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.
context
- FacesContext
for the current requeststate
- the serialized state to be writtenIOException
@Deprecated public abstract UIViewRoot restoreView(FacesContext context, String viewId, String renderKitId)
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 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_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 the ResponseStateManager
instance provided by the
RenderKit
responsible for this view.
context
- FacesContext
for the current requestviewId
- View identifier of the view to be restoredrenderKitId
- the renderKitId used to render this response.
Must not be null
.IllegalArgumentException
- if renderKitId
is null
.protected UIViewRoot restoreTreeStructure(FacesContext context, String viewId, String renderKitId)
null
.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.
context
- FacesContext
for the current requestviewId
- View identifier of the view to be restoredrenderKitId
- the renderKitId used to render this response.
Must not be null
.IllegalArgumentException
- if renderKitId
is null
.protected void restoreComponentState(FacesContext context, UIViewRoot viewRoot, 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.
context
- FacesContext
for the current requestviewRoot
- UIViewRoot
returned by a previous call
to restoreTreeStructure()
renderKitId
- the renderKitId used to render this response.
Must not be null
.IllegalArgumentException
- if renderKitId
is null
.public boolean isSavingStateInClient(FacesContext context)
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.NullPointerException
- if context
is
null
.public String getViewState(FacesContext context)
Convenience method to return the view state as a String
with
no RenderKit
specific markup.
This default implementation of this method will call saveView(javax.faces.context.FacesContext)
and passing the result to and returning the resulting value from
ResponseStateManager.getViewState(javax.faces.context.FacesContext, Object)
.
context
- FacesContext
for the current requestCopyright © 2017 JBoss by Red Hat. All rights reserved.