Package javax.faces.application

Class StateManager

  • Direct Known Subclasses:
    StateManagerWrapper

    public abstract class StateManager
extends java.lang.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.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class 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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.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 java.lang.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.
      static java.lang.String IS_SAVING_STATE
      Marker within the FacesContext attributes map to indicate we are saving state.
      static java.lang.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.
      static java.lang.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 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

      Constructors 
      Constructor Description
      StateManager​()  

    • Field Detail

      • PARTIAL_STATE_SAVING_PARAM_NAME

        public static final java.lang.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.

        Since:
        2.0
        See Also:
        Constant Field Values

      • FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME

        public static final java.lang.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.

        See Also:
        Constant Field Values

      • IS_SAVING_STATE

        public static final java.lang.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.

        See Also:
        Constant Field Values

      • IS_BUILDING_INITIAL_STATE

        public static final java.lang.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.

        Since:
        2.1
        See Also:
        Constant Field Values

      • SERIALIZE_SERVER_STATE_PARAM_NAME

        public static final java.lang.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.

        Since:
        2.2
        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 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

        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
        Returns:
        the serialized view, or null.
        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

      • saveView

        @Deprecated
public java.lang.Object saveView​(FacesContext context)
        Deprecated. 

        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 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
        Returns:
        the saved view.
        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
        Since:
        1.2

      • getTreeStructureToSave

        protected java.lang.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
        Returns:
        the tree structure, or null.

      • getComponentStateToSave

        protected java.lang.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
        Returns:
        the component state, or null.

      • writeState

        public void writeState​(FacesContext context,
                       java.lang.Object state)
                throws java.io.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:
        java.io.IOException - when an I/O error occurs.
        Since:
        1.2

      • writeState

        public void writeState​(FacesContext context,
                       StateManager.SerializedView state)
                throws java.io.IOException
        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.

        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.

        Parameters:
        context - FacesContext for the current request
        state - the serialized state to be written
        Throws:
        java.io.IOException - when an I/O error occurs.

      • restoreView

        @Deprecated
public abstract UIViewRoot restoreView​(FacesContext context,
                                       java.lang.String viewId,
                                       java.lang.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 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.

        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.
        Returns:
        the view root, or null.
        Throws:
        java.lang.IllegalArgumentException - if renderKitId is null.

      • restoreTreeStructure

        protected UIViewRoot restoreTreeStructure​(FacesContext context,
                                          java.lang.String viewId,
                                          java.lang.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.
        Returns:
        the view root, or null.
        Throws:
        java.lang.IllegalArgumentException - if renderKitId is null.

      • restoreComponentState

        protected void restoreComponentState​(FacesContext context,
                                     UIViewRoot viewRoot,
                                     java.lang.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:
        java.lang.IllegalArgumentException - if renderKitId is null.

      • isSavingStateInClient

        public boolean isSavingStateInClient​(FacesContext context)

        Method to determine if the state is saved on the client.

        Parameters:
        context - the Faces 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 (ignoring case) to the value of the constant STATE_SAVING_METHOD_CLIENT. false otherwise.
        Throws:
        java.lang.NullPointerException - if context is null.