Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.application
Class StateManager

    java.lang.Object
      javax.faces.application.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
`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
`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` | `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
`StateManager()`

Method Summary
`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`.
`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`.
`java.lang.String` | `getViewState(FacesContext context)` Convenience method to return the view state as a `String` with no `RenderKit` specific markup.
`boolean` | `isSavingStateInClient(FacesContext context)`
`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.
`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`.
`abstract UIViewRoot` | `restoreView(FacesContext context, java.lang.String viewId, java.lang.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`.
`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 return `null`
`java.lang.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.
`void` | `writeState(FacesContext context, java.lang.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`.

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

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

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

### 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 return `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.

  Parameters:
    `context` - `FacesContext` for the current request
  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

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

  Parameters:
    `context` - `FacesContext` for the current request
  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

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

### 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`
  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`

### restoreView

    public abstract UIViewRoot restoreView(FacesContext context,
                                           java.lang.String viewId,
                                           java.lang.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_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`.
  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`.
  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)

  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:
    `java.lang.NullPointerException` - if `context` is `null`.

### getViewState

    public java.lang.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)`.

  Parameters:
    `context` - `FacesContext` for the current request
  Since:
    2.0

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.