Jakarta EE 11.0.0 · jakarta.faces.lifecycle.ClientWindow

This class represents a client window, which may be a browser tab, browser window, browser pop-up, portlet, or anything else that can display a jakarta.faces.component.UIComponent hierarchy rooted at a jakarta.faces.component.UIViewRoot.

Modes of Operation

none mode

The generation of ClientWindow is controlled by the value of the context-param named by the value of CLIENT_WINDOW_MODE_PARAM_NAME. If this context-param is not specified, or its value is "none", no ClientWindow instances will be generated, and the entire feature is effectively disabled for the entire application.

Other modes

To accomadate the widest possible range of implementation choices to support this feature, explicit names for modes other than "none" and "url" are not specified. However, for all values of CLIENT_WINDOW_MODE_PARAM_NAME, the lifetime of a ClientWindow starts on the first request made by a particular client window (or tab, or pop-up, etc) to the Jakarta Faces runtime and persists as long as that window remains open or the session expires, whichever comes first. A client window is always associated with exactly one UIViewRoot instance at a time, but may display many different UIViewRoots during its lifetime.

The ClientWindow instance is associated with the incoming request during the Lifecycle#attachWindow method. This method will cause a new instance of ClientWindow to be created, assigned an id, and passed to jakarta.faces.context.ExternalContext#setClientWindow.

During state saving, regardless of the window id mode, or state saving mode, for ajax and non-ajax requests, a hidden field must be written whose name, id and value are given as specified in jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_PARAM.

In addition to the hidden field already described. The runtime must ensure that any component that renders a hyperlink that causes the user agent to send a GET request to the Faces server when it is clicked has a query parameter with a name and value specified in ResponseStateManager#CLIENT_WINDOW_URL_PARAM. This requirement is met by several of the "encode" methods on jakarta.faces.context.ExternalContext. See jakarta.faces.context.ExternalContext#encodeActionURL(java.lang.String) for details.

Field Summary

Modifier and Type	Field and Description
public static final String	CLIENT_WINDOW_MODE_PARAM_NAME The context-param that controls the operation of the `ClientWindow` feature.
public static final String	NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME Indicate the max number of ClientWindows, which is used by `ClientWindowScoped`.
private static final String	PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY

Constructor Summary

Access	Constructor and Description
public	ClientWindow()

Method Summary

Modifier and Type	Method and Description
public abstract void	decode(FacesContext the `FacesContext` for this request. context) The implementation is responsible for examining the incoming request and extracting the value that must be returned from the `getId` method.
public void	disableClientWindowRenderMode(FacesContext the `FacesContext` for this request. context) Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first before rendering those URLs.
public void	enableClientWindowRenderMode(FacesContext the `FacesContext` for this request. context) Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first after rendering those URLs.
public abstract String	Returns: the id of the `ClientWindow` getId() Return a String value that uniquely identifies this `ClientWindow` within the scope of the current session.
public abstract Map<String, String>	Returns: `null` or a map of parameters to insert into the URL query string. getQueryURLParameters(FacesContext the `FacesContext` for this request. context) This method will be called whenever a URL is generated by the runtime where client window related parameters need to be inserted into the URL.
public boolean	Returns: the result as specified above isClientWindowRenderModeEnabled(FacesContext the `FacesContext` for this request. context) Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so.

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

Field Detail

CLIENT_WINDOW_MODE_PARAM_NAME back to summary

CLIENT_WINDOW_MODE_PARAM_NAME	back to summary
public static final String CLIENT_WINDOW_MODE_PARAM_NAME The context-param that controls the operation of the `ClientWindow` feature. The runtime must support the values "none" and "url", without the quotes, but other values are possible. If not specified, or the value is not understood by the implementation, "none" is assumed. Since 2.2

public static final String CLIENT_WINDOW_MODE_PARAM_NAME

The context-param that controls the operation of the ClientWindow feature. The runtime must support the values "none" and "url", without the quotes, but other values are possible. If not specified, or the value is not understood by the implementation, "none" is assumed.

Since: 2.2

NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME back to summary

NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME	back to summary
public static final String NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME Indicate the max number of ClientWindows, which is used by `ClientWindowScoped`. It is only active when jakarta.faces.CLIENT_WINDOW_MODE is enabled. Since 4.0

public static final String NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME

Indicate the max number of ClientWindows, which is used by ClientWindowScoped. It is only active when jakarta.faces.CLIENT_WINDOW_MODE is enabled.

Since: 4.0

PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY	back to summary
private static final String PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY

Constructor Detail

ClientWindow	back to summary
public ClientWindow()

Method Detail

decode back to summary

decode	back to summary
public abstract void decode(FacesContext context) The implementation is responsible for examining the incoming request and extracting the value that must be returned from the `getId` method. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "none" this method must not be invoked. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" the implementation must first look for a request parameter under the name given by the value of `jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_PARAM`. If no value is found, look for a request parameter under the name given by the value of `jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_URL_PARAM`. If no value is found, fabricate an id that uniquely identifies this `ClientWindow` within the scope of the current session. This value must be made available to return from the `getId` method. The value must be suitable for inclusion as a hidden field or query parameter. If a value is found, decrypt it using the key from the session and make it available for return from `getId`. Parameters context:FacesContext the `FacesContext` for this request. Since 2.2

public abstract void decode(FacesContext context)

The implementation is responsible for examining the incoming request and extracting the value that must be returned from the getId method. If CLIENT_WINDOW_MODE_PARAM_NAME is "none" this method must not be invoked. If CLIENT_WINDOW_MODE_PARAM_NAME is "url" the implementation must first look for a request parameter under the name given by the value of jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_PARAM. If no value is found, look for a request parameter under the name given by the value of jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_URL_PARAM. If no value is found, fabricate an id that uniquely identifies this ClientWindow within the scope of the current session. This value must be made available to return from the getId method. The value must be suitable for inclusion as a hidden field or query parameter. If a value is found, decrypt it using the key from the session and make it available for return from getId.

Parameters

context:FacesContext: the FacesContext for this request.

Since

2.2

disableClientWindowRenderMode back to summary

disableClientWindowRenderMode	back to summary
public void disableClientWindowRenderMode(FacesContext context) Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first before rendering those URLs. The caller must call `enableClientWindowRenderMode(jakarta.faces.context.FacesContext)` from a `finally` block after rendering the URL. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance. Parameters context:FacesContext the `FacesContext` for this request. Since 2.2

public void disableClientWindowRenderMode(FacesContext context)

Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first before rendering those URLs. The caller must call enableClientWindowRenderMode(jakarta.faces.context.FacesContext) from a finally block after rendering the URL. If CLIENT_WINDOW_MODE_PARAM_NAME is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual ClientWindow instance.

Parameters

context:FacesContext: the FacesContext for this request.

Since

2.2

enableClientWindowRenderMode back to summary

enableClientWindowRenderMode	back to summary
public void enableClientWindowRenderMode(FacesContext context) Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first after rendering those URLs. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance. Parameters context:FacesContext the `FacesContext` for this request. Since 2.2

public void enableClientWindowRenderMode(FacesContext context)

Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first after rendering those URLs. If CLIENT_WINDOW_MODE_PARAM_NAME is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual ClientWindow instance.

Parameters

context:FacesContext: the FacesContext for this request.

Since

2.2

getId back to summary

getId	back to summary
public abstract String getId() Return a String value that uniquely identifies this `ClientWindow` within the scope of the current session. See `decode` for the specification of how to derive this value. Returns:String the id of the `ClientWindow` Since 2.2

public abstract String getId()

Return a String value that uniquely identifies this ClientWindow within the scope of the current session. See decode for the specification of how to derive this value.

Returns:String: the id of the ClientWindow
Since: 2.2

getQueryURLParameters back to summary

getQueryURLParameters	back to summary
public abstract Map<String, String> getQueryURLParameters(FacesContext context) This method will be called whenever a URL is generated by the runtime where client window related parameters need to be inserted into the URL. This guarantees custom `ClientWindow` implementations that they will have the opportunity to insert any additional client window specific information in any case where a URL is generated, such as the rendering of hyperlinks. The returned map must be immutable. The default implementation of this method returns the empty map. Parameters context:FacesContext the `FacesContext` for this request. Returns:Map<String, String> `null` or a map of parameters to insert into the URL query string. Since 2.2

public abstract Map<String, String> getQueryURLParameters(FacesContext context)

This method will be called whenever a URL is generated by the runtime where client window related parameters need to be inserted into the URL. This guarantees custom ClientWindow implementations that they will have the opportunity to insert any additional client window specific information in any case where a URL is generated, such as the rendering of hyperlinks. The returned map must be immutable. The default implementation of this method returns the empty map.

Parameters

context:FacesContext: the FacesContext for this request.

Returns:Map<String, String>

null or a map of parameters to insert into the URL query string.

Since

2.2

isClientWindowRenderModeEnabled back to summary

isClientWindowRenderModeEnabled	back to summary
public boolean isClientWindowRenderModeEnabled(FacesContext context) Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance. Parameters context:FacesContext the `FacesContext` for this request. Returns:boolean the result as specified above Since 2.2

public boolean isClientWindowRenderModeEnabled(FacesContext context)

Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so. If CLIENT_WINDOW_MODE_PARAM_NAME is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual ClientWindow instance.

Parameters

context:FacesContext: the FacesContext for this request.

Returns:boolean

the result as specified above

Since

2.2

public abstract Class ClientWindow

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail