public abstract class ClientWindow
extends java.lang.Object
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 UIComponent hierarchy rooted at a
UIViewRoot.
Modes of Operation
none mode
The generation of
ClientWindowis controlled by the value of thecontext-paramnamed by the value ofCLIENT_WINDOW_MODE_PARAM_NAME. If thiscontext-paramis not specified, or its value is "none", noClientWindowinstances 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 aClientWindowstarts 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 oneUIViewRootinstance at a time, but may display many differentUIViewRoots during its lifetime.The
ClientWindowinstance is associated with the incoming request during theLifecycle.attachWindow(jakarta.faces.context.FacesContext)method. This method will cause a new instance ofClientWindowto be created, assigned an id, and passed toExternalContext.setClientWindow(jakarta.faces.lifecycle.ClientWindow).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
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 onExternalContext. SeeExternalContext.encodeActionURL(java.lang.String)for details.
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
CLIENT_WINDOW_MODE_PARAM_NAME
The context-param that controls the operation of the |
static java.lang.String |
NUMBER_OF_CLIENT_WINDOWS_PARAM_NAME
Indicate the max number of ClientWindows, which is used by |
| Constructor and Description |
|---|
ClientWindow() |
| Modifier and Type | Method and Description |
|---|---|
abstract void |
decode(FacesContext context)
The implementation is responsible for examining the incoming request and extracting the value that must be returned
from the |
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. |
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. |
abstract java.lang.String |
getId()
Return a String value that uniquely identifies this |
abstract java.util.Map<java.lang.String,java.lang.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. |
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. |
public static final java.lang.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.
public static final java.lang.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.
public abstract java.util.Map<java.lang.String,java.lang.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.
context - the FacesContext for this request.null or a map of parameters to insert into the URL query string.public abstract java.lang.String getId()
Return a String value that uniquely identifies this ClientWindow within the scope of the current
session. See decode(jakarta.faces.context.FacesContext) for the specification of how to derive this value.
ClientWindowpublic 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 ResponseStateManager.CLIENT_WINDOW_PARAM. If no value is
found, look for a request parameter under the name given by the value of
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().
context - the FacesContext for this request.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.
context - the FacesContext for this request.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.
context - the FacesContext for this request.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.
context - the FacesContext for this request.