Field Detail

• RENDER_KIT_ID_PARAM

  public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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,
                         java.lang.Object state)
                  throws java.io.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:

  java.io.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 java.io.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:

  java.io.IOException - if the state cannot be written for any reason

• isStateless

  public boolean isStateless(FacesContext context,
                             java.lang.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

  Returns:

  the value of the statelessness of this run through the lifecycle.

  Throws:

  java.lang.NullPointerException - if the argument context is null.

  java.lang.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 java.lang.Object getState(FacesContext context,
                                   java.lang.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 java.lang.Object getTreeStructureToRestore(FacesContext context,
                                                    java.lang.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

  Returns:

  the tree structure portion of the state

• getComponentStateToRestore

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

  Returns:

  the component state portion of the state

• 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 compatibility with implementations of ResponseStateManager prior to Jakarta Server Faces 1.2, a default implementation is provided that consults the ExternalContext's requestParameterMap and return true if its size is greater than 0.

  Parameters:

  context - the FacesContext for the current request.

  Returns:

  the value as specified above

  Since:

  1.2

• getViewState

  public java.lang.String getViewState(FacesContext context,
                                       java.lang.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 java.lang.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