StateManager (Java EE 5)

StateManager 指示在请求之间保存和恢复视图的过程。应用程序的 StateManager 实例是从 Application 实例中获取出的，因此无法了解用于呈现视图的 RenderKit 创建的标记语言的任何详细信息。StateManager 使用了帮助对象 (ResponseStateManager)，该帮助对象由 RenderKit 实现提供，因此知道标记语言的详细信息。

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 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.

英文文档：

STATE_SAVING_METHOD_PARAM_NAME

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.

See Also:

Constant Field Values

英文文档：

STATE_SAVING_METHOD_CLIENT

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.

See Also:

Constant Field Values

英文文档：

STATE_SAVING_METHOD_SERVER

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.

See Also:

Constant Field Values

public StateManager()

英文文档：

StateManager

public StateManager()

public StateManager.SerializedView saveSerializedView(FacesContext context)

将指定 FacesContext 实例中包含的视图的树结构和组件状态信息作为类型为 StateManager.SerializedView 的对象返回。如果没有保存任何状态信息，则返回 null。

通过将其 transient 属性设置为 true，组件可以选择不被包含在序列化视图中。这将导致在保存的树结构和组件状态信息中省略组件本身以及该组件的所有子组件和 facet。

此方法还必须执行以下规则：对于带有非 null id 的组件，所有属于最接近的相同 NamingContainer 的后代的组件都必须具有唯一的标识符。

context	当前请求的 FacesContext
Throws	IllegalStateException: 如果此视图中的相同 NamingContainer 内的多个组件或 facet 具有相同的非 null 组件 ID
deprecated	此方法已由 #saveView 替代。默认实现返回 null。

英文文档：

saveSerializedView

public StateManager.SerializedView saveSerializedView(FacesContext context)

Deprecated. this has been replaced by saveView(javax.faces.context.FacesContext). The default implementation 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 ids, all components that are descendants of the same nearest NamingContainer must have unique identifiers.

Parameters:

context - FacesContext for the current request

Throws:

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

public Object saveView(FacesContext context)

返回包含此相同实例的足够信息的透明 Object，以便在后续请求中恢复当前 UIViewRoot 的状态。返回的对象必须实现 java.io.Serializable。如果没有保存任何状态信息，则返回 null。

通过将其 transient 属性设置为 true，组件可以选择不被包含在序列化视图中。这将导致在保存的树结构和组件状态信息中省略组件本身以及该组件的所有子组件和 facet。

此方法还必须执行以下规则：对于带有非 null id 的组件，所有属于最接近的相同 NamingContainer 的后代的组件都必须具有唯一的标识符。

为与现有的 StateManager 实现向后兼容，此方法的默认实现调用 #saveSerializedView，并创建和返回包含两个元素的 Object 数组，其中元素 0 包含 structure 属性，而元素 1 包含 SerializedView 的 state 属性。

context	当前请求的 FacesContext
Throws	IllegalStateException: 如果此视图中的相同 NamingContainer 内的多个组件或 facet 具有相同的非 null 组件 ID
since	1.2

英文文档：

saveView

public Object saveView(FacesContext context)

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 ids, 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.

Parameters:

context - FacesContext for the current request

Throws:

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

Since:

1.2

protected Object getTreeStructureToSave(FacesContext context)

必须由 saveSerializedView() 调用的便捷方法构造并返回 Serializable 对象，该对象表示此视图的整个组件树（包括子组件和 facet）的结构。

通过将其 transient 属性设置为 true，组件可以选择不被包含在树结构中。这必将导致在保存的树结构信息中省略组件本身以及该组件的所有子组件和 facet。

context	当前请求的 FacesContext
deprecated	树结构和组件状态的区别现在属于实现详细信息。默认实现返回 null。

英文文档：

getTreeStructureToSave

protected Object getTreeStructureToSave(FacesContext context)

Deprecated. the distinction between tree structure and component state is now an implementation detail. The default implementation returns 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.

Parameters:

context - FacesContext for the current request

protected Object getComponentStateToSave(FacesContext context)

必须由 saveSerializedView() 调用的便捷方法构造并返回 Serializable 对象，该对象表示此视图的整个组件树（包括子组件和 facet）的所有组件属性和连接对象的状态。

通过将其 transient 属性设置为 true，组件可以选择不被包含在组件状态中。这必将导致在保存的组件状态信息中省略组件本身以及该组件的所有子组件和 facet。

context	当前请求的 FacesContext
deprecated	树结构和组件状态的区别现在属于实现详细信息。默认实现返回 null。

英文文档：

getComponentStateToSave

protected Object getComponentStateToSave(FacesContext context)

Deprecated. the distinction between tree structure and component state is now an implementation detail. The default implementation returns 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.

Parameters:

context - FacesContext for the current request

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

以与实现相关的方式保存指定状态 Object 实例中表示的状态。

此方法通常只将实际写入操作委托给 ResponseStateManager 实例的 writeState() 方法，该实例由用于呈现此视图的 RenderKit 提供。此方法假设调用者已经将 ResponseWriter 放在正确的地方，以写入保存的状态。

为与现有的 StateManager 实现向后兼容，此方法的默认实现会检查参数是否是长度超过或等于二的 Object [] 的实例。如果是，它将创建一个 SerializedView 实例，其中树结构来自元素 0，而组件状态来自元素 1，并调用 #writeState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)。如果不是，则不执行任何操作。

context	当前请求的 FacesContext
state	要写入的 Serializable 状态，由 #saveSerializedView 返回
since	1.2

英文文档：

writeState

public 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.

Parameters:

context - FacesContext for the current request

state - the Serializable state to be written, as returned by saveSerializedView(javax.faces.context.FacesContext)

Throws:

IOException

Since:

1.2

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

以与实现相关的方式保存指定 SerializedView 实例中表示的状态。

此方法必须参考符号常量 StateManager.STATE_SAVING_METHOD_PARAMETER_NAME 指定的上下文初始化参数来确定状态应保存在客户端还是服务器上。如果不存在，则假定为客户端状态保存。

如果 init 参数指示应使用客户端状态保存，则此方法必须将实际写入操作委托给 ResponseStateManager 实例的 writeState() 方法，该实例由用于呈现此视图的 RenderKit 提供。此方法假设调用者已经将 ResponseWriter 放在正确的地方，以写入保存的状态。

context	当前请求的 FacesContext
state	要写入的序列化状态
deprecated	此方法已由 #writeState(javax.faces.context.FacesContext,java.lang.Object) 替代。此方法的默认实现不执行任何操作。

英文文档：

writeState

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

Deprecated. This method has been replaced by writeState(javax.faces.context.FacesContext,java.lang.Object). The default implementation of this method does nothing.

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.

Parameters:

context - FacesContext for the current request

state - the serialized state to be written

Throws:

IOException

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

以与实现相关的方式恢复指定 viewId 的视图的树结构和组件状态，并返回已恢复的 UIViewRoot。如果此 viewId 没有可用的保存的状态信息，则返回 null。

此方法必须参考符号常量 StateManager.STATE_SAVING_METHOD_PARAMETER_NAME 指定的上下文初始化参数来确定状态应保存在客户端还是服务器上。如果不存在，则假定为客户端状态保存。

如果 init 参数指示应使用客户端状态保存，则此方法必须调用 ResponseStateManager 实例的 getTreeStructureToRestore() 和（如果以前的方法调用返回了非 null 值）getComponentStateToRestore() 方法，该实例由负责此视图的 RenderKit 提供。

context	当前请求的 FacesContext
viewId	要恢复的视图的视图标识符
renderKitId	用于呈现此响应的 renderKitId。不得为 null。
Throws	IllegalArgumentException: 如果 renderKitId 为 null。

英文文档：

restoreView

public abstract UIViewRoot restoreView(FacesContext context,
                                       String viewId,
                                       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:

IllegalArgumentException - if renderKitId is null.

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

必须由 restoreView() 调用的便捷方法，用于构造和返回 UIViewRoot 实例（填充有子实例和 facet），该实例表示正在恢复的组件树的树结构。如果没有可用的保存的状态信息，则返回 null。

context	当前请求的 FacesContext
viewId	要恢复的视图的视图标识符
renderKitId	用于呈现此响应的 renderKitId。不得为 null。
Throws	IllegalArgumentException: 如果 renderKitId 为 null。
deprecated	树结构和组件状态的区别现在属于实现详细信息。默认实现返回 null。

英文文档：

restoreTreeStructure

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.

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.

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:

IllegalArgumentException - if renderKitId is null.

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

必须由 restoreView() 调用的便捷方法，用于恢复已恢复组件树中所有组件的属性和连接对象。

context	当前请求的 FacesContext
viewRoot	以前调用 restoreTreeStructure() 返回的 UIViewRoot
renderKitId	用于呈现此响应的 renderKitId。不得为 null。
Throws	IllegalArgumentException: 如果 renderKitId 为 null。
deprecated	树结构和组件状态的区别现在属于实现详细信息。默认实现不执行任何操作。

英文文档：

restoreComponentState

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.

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 request

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

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

Throws:

IllegalArgumentException - if renderKitId is null.

public boolean isSavingStateInClient(FacesContext context)

return	当且仅当常量 #STATE_SAVING_METHOD_PARAM_NAME 的值指定的 ServletContext init 参数的值等于常量 #STATE_SAVING_METHOD_CLIENT 的值时，返回 true。否则，返回 false。
Throws	NullPointerException: 如果 context 为 null。

英文文档：

isSavingStateInClient

public boolean isSavingStateInClient(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:

NullPointerException - if context is null.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.