Jakarta EE 11.0.0 · jakarta.faces.render.ResponseStateManager

Modifier and Type	Field and Description
public static final String	CLIENT_WINDOW_PARAM The name of the hidden field that refers to the encoded ClientWindow.
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 `jakarta.faces.lifecycle.ClientWindow#CLIENT_WINDOW_MODE_PARAM_NAME` is not "none".
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.
public static final String	RENDER_KIT_ID_PARAM The name of the request parameter used by the default implementation of `jakarta.faces.application.ViewHandler#calculateRenderKitId` to derive a RenderKit ID.
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.

Access	Constructor and Description
public	ResponseStateManager()

Method Summary

Modifier and Type	Method and Description
public String	Returns: a cryptographically strong value getCryptographicallyStrongTokenFromSession(FacesContext the `FacesContext` for the current request context) Compliant implementations must return a cryptographically strong token for use to protect views in this application.
public Object	Returns: the tree structure and component state Object passed in to `writeState`. If this is an initial request, this method returns `null`. getState(FacesContext The `FacesContext` instance for the current request context, String View identifier of the view to be restored 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(jakarta.faces.context.FacesContext, java.lang.Object)`.
public String	Returns: the view state for this request without any markup specifics getViewState(FacesContext the `FacesContext` for the current request context, Object the state from which the String version will be generated from state) Return the specified state as a `String` without any markup related to the rendering technology supported by this ResponseStateManager.
public boolean	Returns: the value as specified above isPostback(FacesContext the `FacesContext` for the current request. context) Return true if the current request is a postback.
public boolean	Returns: the value of the statelessness of this run through the lifecycle. isStateless(FacesContext The `FacesContext` instance for the current request context, String View identifier of the view to be restored viewId) If the preceding call to `writeState(jakarta.faces.context.FacesContext, java.lang.Object)` was stateless, return `true`.
public void	writeState(FacesContext The `FacesContext` instance for the current request context, Object The serialized state information previously saved state) Take the argument `state` and write it into the output using the current `ResponseWriter`, which must be correctly positioned already.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CLIENT_WINDOW_PARAM back to summary

CLIENT_WINDOW_PARAM	back to summary
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 `jakarta.faces.lifecycle.ClientWindow#CLIENT_WINDOW_MODE_PARAM_NAME` is not "none". The `id` attribute must be a concatenation of the return from `jakarta.faces.component.UIViewRoot#getContainerClientId`, the return from `jakarta.faces.component.UINamingContainer#getSeparatorChar`, 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 `jakarta.faces.lifecycle.ClientWindow#getId`. Since 2.2

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 jakarta.faces.lifecycle.ClientWindow#CLIENT_WINDOW_MODE_PARAM_NAME is not "none". The id attribute must be a concatenation of the return from jakarta.faces.component.UIViewRoot#getContainerClientId, the return from jakarta.faces.component.UINamingContainer#getSeparatorChar, 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 jakarta.faces.lifecycle.ClientWindow#getId.

Since: 2.2

CLIENT_WINDOW_URL_PARAM back to summary

CLIENT_WINDOW_URL_PARAM	back to summary
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 `jakarta.faces.lifecycle.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 `jakarta.faces.lifecycle.ClientWindow#getId`. Since 2.2

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 jakarta.faces.lifecycle.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 jakarta.faces.lifecycle.ClientWindow#getId.

Since: 2.2

NON_POSTBACK_VIEW_TOKEN_PARAM back to summary

NON_POSTBACK_VIEW_TOKEN_PARAM	back to summary
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

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

RENDER_KIT_ID_PARAM	back to summary
public static final String RENDER_KIT_ID_PARAM The name of the request parameter used by the default implementation of `jakarta.faces.application.ViewHandler#calculateRenderKitId` to derive a RenderKit ID.

VIEW_STATE_PARAM back to summary

VIEW_STATE_PARAM	back to summary
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 `jakarta.faces.component.UIViewRoot#getContainerClientId`, the return from `jakarta.faces.component.UINamingContainer#getSeparatorChar`, 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

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 jakarta.faces.component.UIViewRoot#getContainerClientId, the return from jakarta.faces.component.UINamingContainer#getSeparatorChar, 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

Constructor Detail

ResponseStateManager	back to summary
public ResponseStateManager()

Method Detail

getCryptographicallyStrongTokenFromSession back to summary

getCryptographicallyStrongTokenFromSession	back to summary
public String getCryptographicallyStrongTokenFromSession(FacesContext context) Compliant implementations must return a cryptographically strong token for use to protect views in this application. For backwards compatibility with earlier revisions, a default implementation is provided that simply returns `null`. Parameters context:FacesContext the `FacesContext` for the current request Returns:String a cryptographically strong value Since 2.2

public String getCryptographicallyStrongTokenFromSession(FacesContext context)

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

Parameters

context:FacesContext: the FacesContext for the current request

Returns:String

a cryptographically strong value

Since

2.2

getState back to summary

getState	back to summary
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(jakarta.faces.context.FacesContext, java.lang.Object)`. If the state saving method for this application is `jakarta.faces.application.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 `jakarta.faces.application.ProtectedViewException` must be thrown. Parameters context:FacesContext The `FacesContext` instance for the current request viewId:String View identifier of the view to be restored Returns:Object the tree structure and component state Object passed in to `writeState`. If this is an initial request, this method returns `null`. Since 1.2

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(jakarta.faces.context.FacesContext, java.lang.Object).

If the state saving method for this application is jakarta.faces.application.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 jakarta.faces.application.ProtectedViewException must be thrown.

Parameters

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

Returns:Object

the tree structure and component state Object passed in to writeState. If this is an initial request, this method returns null.

Since

1.2

getViewState back to summary

getViewState	back to summary
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:FacesContext the `FacesContext` for the current request state:Object the state from which the String version will be generated from Returns:String the view state for this request without any markup specifics Since 2.0

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:FacesContext: the FacesContext for the current request
state:Object: the state from which the String version will be generated from

Returns:String

the view state for this request without any markup specifics

Since

2.0

isPostback back to summary

isPostback	back to summary
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 `jakarta.faces.application.ViewHandler#restoreView` or `jakarta.faces.application.ViewHandler#createView` 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 `jakarta.faces.context.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 Faces 1.2, a default implementation is provided that consults the `jakarta.faces.context.ExternalContext`'s `requestParameterMap` and return `true` if its size is greater than 0. Parameters context:FacesContext the `FacesContext` for the current request. Returns:boolean the value as specified above Since 1.2

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 jakarta.faces.application.ViewHandler#restoreView or jakarta.faces.application.ViewHandler#createView 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 jakarta.faces.context.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 Faces 1.2, a default implementation is provided that consults the jakarta.faces.context.ExternalContext's requestParameterMap and return true if its size is greater than 0.

Parameters

context:FacesContext: the FacesContext for the current request.

Returns:boolean

the value as specified above

Since

1.2

isStateless back to summary

isStateless	back to summary
public boolean isStateless(FacesContext context, String viewId) If the preceding call to `writeState(jakarta.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:FacesContext The `FacesContext` instance for the current request viewId:String View identifier of the view to be restored Returns:boolean the value of the statelessness of this run through the lifecycle. Exceptions NullPointerException: if the argument `context` is `null`. IllegalStateException: if this method is invoked and the statefulness of the preceding call to `writeState(jakarta.faces.context.FacesContext, java.lang.Object)` cannot be determined. Since 2.2

public boolean isStateless(FacesContext context, String viewId)

If the preceding call to writeState(jakarta.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:FacesContext: The FacesContext instance for the current request
viewId:String: View identifier of the view to be restored

Returns:boolean

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

Exceptions

NullPointerException:: if the argument context is null.
IllegalStateException:: if this method is invoked and the statefulness of the preceding call to writeState(jakarta.faces.context.FacesContext, java.lang.Object) cannot be determined.

Since

2.2

writeState back to summary

writeState	back to summary
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 `jakarta.faces.component.UIComponent#isTransient()` returns `true`, take implementation specific action so that the following call to `isStateless` 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 `jakarta.faces.application.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 `jakarta.faces.application.StateManager#STATE_SAVING_METHOD_SERVER`, and the current request is an `Ajax` request `jakarta.faces.context.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 `jakarta.faces.application.Application#getDefaultRenderKitId()` or the render kit identfier is the value of `jakarta.faces.render.RenderKitFactory.HTML_BASIC_RENDER_KIT` and `jakarta.faces.application.Application#getDefaultRenderKitId()` returns `null`. The `jakarta.faces.lifecycle.ClientWindow` must be written using these steps. Call `jakarta.faces.context.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>jakarta.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:FacesContext The `FacesContext` instance for the current request state:Object The serialized state information previously saved Exceptions IOException: if the state argument is not an array of length 2. Since 1.2

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 jakarta.faces.component.UIComponent#isTransient() returns true, take implementation specific action so that the following call to isStateless 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 jakarta.faces.application.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 jakarta.faces.application.StateManager#STATE_SAVING_METHOD_SERVER, and the current request is an Ajax request jakarta.faces.context.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 jakarta.faces.application.Application#getDefaultRenderKitId() or
the render kit identfier is the value of jakarta.faces.render.RenderKitFactory.HTML_BASIC_RENDER_KIT and jakarta.faces.application.Application#getDefaultRenderKitId() returns null.

The jakarta.faces.lifecycle.ClientWindow must be written using these steps. Call jakarta.faces.context.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>jakarta.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:FacesContext: The FacesContext instance for the current request
state:Object: The serialized state information previously saved

Exceptions

IOException:: if the state argument is not an array of length 2.

Since

1.2

public abstract Class ResponseStateManager

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail