javax.faces.render

## Class ResponseStateManager

- java.lang.Object
- - javax.faces.render.ResponseStateManager

-     public abstract class ResponseStateManager
      extends Object

  ResponseStateManager is the helper class to `StateManager` that knows the specific rendering technology being used to generate the response. It is a singleton abstract class, vended by the `RenderKit`. This class knows the mechanics of saving state, whether it be in hidden fields, session, or some combination of the two.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CLIENT_WINDOW_PARAM` The name of the hidden field that refers to the encoded ClientWindow.
    `static String` | `CLIENT_WINDOW_URL_PARAM` The name of the URL query parameter for transmitting the client window id.
    `static String` | `NON_POSTBACK_VIEW_TOKEN_PARAM` The value of this constant is taken to be the name of a request parameter whose value is inspected to verify the safety of an incoming non-postback request with respect to the currently configured `Set` of protected views for this application.
    `static String` | `RENDER_KIT_ID_PARAM` The name of the request parameter used by the default implementation of `ViewHandler.calculateRenderKitId(javax.faces.context.FacesContext)` to derive a RenderKit ID.
    `static String` | `VIEW_STATE_PARAM` Implementations must use this constant field value as the name of the client parameter in which to save the state between requests.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResponseStateManager()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `getComponentStateToRestore(FacesContext context)` Deprecated. This method has been replaced by `getState(javax.faces.context.FacesContext, java.lang.String)`. The default implementation returns `null`.
    `String` | `getCryptographicallyStrongTokenFromSession(FacesContext context)` Compliant implementations must return a cryptographically strong token for use to protect views in this application.
    `Object` | `getState(FacesContext context, String viewId)` The implementation must inspect the current request and return an Object representing the tree structure and component state passed in to a previous invocation of `writeState(javax.faces.context.FacesContext,java.lang.Object)`.
    `Object` | `getTreeStructureToRestore(FacesContext context, String viewId)` Deprecated. This method has been replaced by `getState(javax.faces.context.FacesContext, java.lang.String)`. The default implementation returns `null`.
    `String` | `getViewState(FacesContext context, Object state)` Return the specified state as a `String` without any markup related to the rendering technology supported by this ResponseStateManager.
    `boolean` | `isPostback(FacesContext context)` Return true if the current request is a postback.
    `boolean` | `isStateless(FacesContext context, String viewId)` If the preceding call to `writeState(javax.faces.context.FacesContext, java.lang.Object)` was stateless, return `true`.
    `void` | `writeState(FacesContext context, Object state)` Take the argument `state` and write it into the output using the current `ResponseWriter`, which must be correctly positioned already.
    `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 creates a two element `Object` array with the first element being the return from calling `StateManager.SerializedView.getStructure()`, and the second being the return from `StateManager.SerializedView.getState()`. It then passes this `Object` array to `writeState(javax.faces.context.FacesContext, java.lang.Object)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### RENDER_KIT_ID_PARAM

          public static final String RENDER_KIT_ID_PARAM

      The name of the request parameter used by the default implementation of `ViewHandler.calculateRenderKitId(javax.faces.context.FacesContext)` to derive a RenderKit ID.

      See Also:
        Constant Field Values

    - #### VIEW_STATE_PARAM

          public static final String VIEW_STATE_PARAM

      Implementations must use this constant field value as the name of the client parameter in which to save the state between requests. The `id` attribute must be a concatenation of the return from `UIComponent.getContainerClientId(javax.faces.context.FacesContext)`, the return from `UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)`, this constant field value, the separator char, and a number that is guaranteed to be unique with respect to all the other instances of this kind of client parameter in the view.

      It is strongly recommend that implementations guard against cross site scripting attacks by at least making the value of this parameter difficult to predict.

      Since:
        1.2
      See Also:
        Constant Field Values

    - #### CLIENT_WINDOW_PARAM

          public static final String CLIENT_WINDOW_PARAM

      The name of the hidden field that refers to the encoded ClientWindow. This field is only used if `ClientWindow.CLIENT_WINDOW_MODE_PARAM_NAME` is not "none". The `id` attribute must be a concatenation of the return from `UIComponent.getContainerClientId(javax.faces.context.FacesContext)`, the return from `UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)`, this constant field value, the separator char, and a number that is guaranteed to be unique with respect to all the other instances of this kind of client parameter in the view. The value of this parameter is the return from `ClientWindow.getId()`.

      Since:
        2.2
      See Also:
        Constant Field Values

    - #### CLIENT_WINDOW_URL_PARAM

          public static final String CLIENT_WINDOW_URL_PARAM

      The name of the URL query parameter for transmitting the client window id. This parameter is only used if `ClientWindow.CLIENT_WINDOW_MODE_PARAM_NAME` is not "none". The name of the parameter is given by the constant value of this field. The value of this parameter is the return from `ClientWindow.getId()`.

      Since:
        2.2
      See Also:
        Constant Field Values

    - #### NON_POSTBACK_VIEW_TOKEN_PARAM

          public static final String NON_POSTBACK_VIEW_TOKEN_PARAM

      The value of this constant is taken to be the name of a request parameter whose value is inspected to verify the safety of an incoming non-postback request with respect to the currently configured `Set` of protected views for this application.

      Since:
        2.2
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ResponseStateManager

          public ResponseStateManager()

  - ### Method Detail

    - #### writeState

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

      Take the argument `state` and write it into the output using the current `ResponseWriter`, which must be correctly positioned already.

      Call `FacesContext.getViewRoot()`. If `StateHolder.isTransient()` returns `true`, take implementation specific action so that the following call to `isStateless(javax.faces.context.FacesContext, java.lang.String)` returns `true` and return. Otherwise, proceed as follows.

      If the state is to be written out to hidden fields, the implementation must take care to make all necessary character replacements to make the Strings suitable for inclusion as an HTTP request paramater.

      If the state saving method for this application is `StateManager.STATE_SAVING_METHOD_CLIENT`, the implementation must encrypt the state to be saved to the client in a tamper evident manner.

      If the state saving method for this application is `StateManager.STATE_SAVING_METHOD_SERVER`, and the current request is an `Ajax` request `PartialViewContext.isAjaxRequest()` returns `true`), use the current view state identifier if it is available (do not generate a new identifier).

      Write out the render kit identifier associated with this `ResponseStateManager` implementation with the name as the value of the `String` constant `ResponseStateManager.RENDER_KIT_ID_PARAM`. The render kit identifier must not be written if:

      - it is the default render kit identifier as returned by `Application.getDefaultRenderKitId()` or
      - the render kit identfier is the value of `javax.faces.render.RenderKitFactory.HTML_BASIC_RENDER_KIT` and `Application.getDefaultRenderKitId()` returns `null`.

      For backwards compatability with existing `ResponseStateManager` implementations, the default implementation of this method checks if the argument is an instance of `SerializedView`. If so, it calls through to `writeState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)`. If not, it expects the state to be a two element Object array. It creates an instance of `SerializedView` and stores the state as the treeStructure, and passes it to `writeState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)`.

      The `ClientWindow` must be written using these steps. Call `ExternalContext.getClientWindow()`. If the result is `null`, take no further action regarding the `ClientWindow`. If the result is non-`null`, write a hidden field whose name is `CLIENT_WINDOW_PARAM` and whose id is `<VIEW_ROOT_CONTAINER_CLIENT_ID><SEP>javax.faces.ClientWindow<SEP><UNIQUE_PER_VIEW_NUMBER>` where <SEP> is the currently configured `UINamingContainer.getSeparatorChar()`. <VIEW_ROOT_CONTAINER_CLIENT_ID> is the return from `UIViewRoot.getContainerClientId()` on the view from whence this state originated. <UNIQUE_PER_VIEW_NUMBER> is a number that must be unique within this view, but must not be included in the view state. The value of the field is implementation dependent but must uniquely identify this window within the user's session.

      Parameters:
        `context` - The `FacesContext` instance for the current request
        `state` - The serialized state information previously saved
      Throws:
        `IOException` - if the state argument is not an array of length 2.
      Since:
        1.2

    - #### 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 creates a two element `Object` array with the first element being the return from calling `StateManager.SerializedView.getStructure()`, and the second being the return from `StateManager.SerializedView.getState()`. It then passes this `Object` array to `writeState(javax.faces.context.FacesContext, java.lang.Object)`.

      Take the argument `state` and write it into the output using the current `ResponseWriter`, which must be correctly positioned already.

      If the `StateManager.SerializedView` is to be written out to hidden fields, the implementation must take care to make all necessary character replacements to make the Strings suitable for inclusion as an HTTP request paramater.

      If the state saving method for this application is `StateManager.STATE_SAVING_METHOD_CLIENT`, the implementation may encrypt the state to be saved to the client. We recommend that the state be unreadable by the client, and also be tamper evident. The reference implementation follows these recommendations.

      Parameters:
        `context` - The `FacesContext` instance for the current request
        `state` - The serialized state information previously saved
      Throws:
        `IOException`

    - #### isStateless

          public boolean isStateless(FacesContext context,
                            String viewId)

      If the preceding call to `writeState(javax.faces.context.FacesContext, java.lang.Object)` was stateless, return `true`. If the preceding call to `writeState()` was stateful, return `false`. Otherwise throw `IllegalStateException`.

      To preserve backward compatibility with custom implementations that may have extended from an earlier version of this class, an implementation is provided that returns `false`. A compliant implementation must override this method to take the specified action.

      Parameters:
        `context` - The `FacesContext` instance for the current request
        `viewId` - View identifier of the view to be restored
      Throws:
        `NullPointerException` - if the argument `context` is `null`.
        `IllegalStateException` - if this method is invoked and the statefulness of the preceding call to `writeState(javax.faces.context.FacesContext, java.lang.Object)` cannot be determined.
      Since:
        2.2

    - #### getState

          public Object getState(FacesContext context,
                        String viewId)

      The implementation must inspect the current request and return an Object representing the tree structure and component state passed in to a previous invocation of `writeState(javax.faces.context.FacesContext,java.lang.Object)`.

      If the state saving method for this application is `StateManager.STATE_SAVING_METHOD_CLIENT`, `writeState()` will have encrypted the state in a tamper evident manner. If the state fails to decrypt, or decrypts but indicates evidence of tampering, a `ProtectedViewException` must be thrown.

      For backwards compatability with existing `ResponseStateManager` implementations, the default implementation of this method calls `getTreeStructureToRestore(javax.faces.context.FacesContext, java.lang.String)` and `getComponentStateToRestore(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` - The `FacesContext` instance for the current request
        `viewId` - View identifier of the view to be restored
      Returns:
        the tree structure and component state Object passed in to `writeState`. If this is an initial request, this method returns `null`.
      Since:
        1.2

    - #### getTreeStructureToRestore

          public Object getTreeStructureToRestore(FacesContext context,
                                         String viewId)

      Deprecated. This method has been replaced by `getState(javax.faces.context.FacesContext, java.lang.String)`. The default implementation returns `null`.

      The implementation must inspect the current request and return the tree structure Object passed to it on a previous invocation of `writeState()`.

      Parameters:
        `context` - The `FacesContext` instance for the current request
        `viewId` - View identifier of the view to be restored

    - #### getComponentStateToRestore

          public Object getComponentStateToRestore(FacesContext context)

      Deprecated. This method has been replaced by `getState(javax.faces.context.FacesContext, java.lang.String)`. The default implementation returns `null`.

      The implementation must inspect the current request and return the component state Object passed to it on a previous invocation of `writeState()`.

      Parameters:
        `context` - The `FacesContext` instance for the current request

    - #### isPostback

          public boolean isPostback(FacesContext context)

      Return true if the current request is a postback. This method is leveraged from the Restore View Phase to determine if `ViewHandler.restoreView(javax.faces.context.FacesContext, java.lang.String)` or `ViewHandler.createView(javax.faces.context.FacesContext, java.lang.String)` should be called. The default implementation must return `true` if this `ResponseStateManager` instance wrote out state on a previous request to which this request is a postback, `false` otherwise.

      The implementation of this method for the Standard HTML RenderKit must consult the `ExternalContext`'s `requestParameterMap` and return `true` if and only if there is a key equal to the value of the symbolic constant `VIEW_STATE_PARAM`.

      For backwards compatability with implementations of `ResponseStateManager` prior to JSF 1.2, a default implementation is provided that consults the `ExternalContext`'s `requestParameterMap` and return `true` if its size is greater than 0.

      Since:
        1.2

    - #### getViewState

          public String getViewState(FacesContext context,
                            Object state)

      Return the specified state as a `String` without any markup related to the rendering technology supported by this ResponseStateManager.

      Parameters:
        `context` - the `FacesContext` for the current request
        `state` - the state from which the String version will be generated from
      Returns:
        the view state for this request without any markup specifics
      Since:
        2.0

    - #### getCryptographicallyStrongTokenFromSession

          public String getCryptographicallyStrongTokenFromSession(FacesContext context)

      Compliant implementations must return a cryptographically strong token for use to protect views in this application. For backwards compatability with earlier revisions, a default implementation is provided that simply returns `null`.

      Parameters:
        `context` - the `FacesContext` for the current request
      Returns:
        a cryptographically strong value
      Since:
        2.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.