Class ClientWindow
- Direct Known Subclasses:
ClientWindowWrapper
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 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 JSF 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 UIViewRoot
s during its
lifetime.
The ClientWindow
instance is associated with the
incoming request during the Lifecycle.attachWindow(javax.faces.context.FacesContext)
method.
This method will cause a new instance of ClientWindow
to
be created, assigned an id, and passed to ExternalContext.setClientWindow(javax.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 on ExternalContext
. See ExternalContext.encodeActionURL(java.lang.String)
for details.
- Since:
- 2.2
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The context-param that controls the operation of theClientWindow
feature. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
decode
(FacesContext context) The implementation is responsible for examining the incoming request and extracting the value that must be returned from thegetId()
method.void
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 String
getId()
Return a String value that uniquely identifies thisClientWindow
within the scope of the current session.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
Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so.
-
Field Details
-
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
- See Also:
-
-
Constructor Details
-
ClientWindow
public ClientWindow()
-
-
Method Details
-
getQueryURLParameters
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
- theFacesContext
for this request.- Returns:
null
or a map of parameters to insert into the URL query string.- Since:
- 2.2
-
getId
Return a String value that uniquely identifies this
ClientWindow
within the scope of the current session. Seedecode(javax.faces.context.FacesContext)
for the specification of how to derive this value.- Since:
- 2.2
-
decode
The implementation is responsible for examining the incoming request and extracting the value that must be returned from the
getId()
method. IfCLIENT_WINDOW_MODE_PARAM_NAME
is "none" this method must not be invoked. IfCLIENT_WINDOW_MODE_PARAM_NAME
is "url" the implementation must first look for a request parameter under the name given by the value ofResponseStateManager.CLIENT_WINDOW_PARAM
. If no value is found, look for a request parameter under the name given by the value ofResponseStateManager.CLIENT_WINDOW_URL_PARAM
. If no value is found, fabricate an id that uniquely identifies thisClientWindow
within the scope of the current session. This value must be made available to return from thegetId()
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 fromgetId()
.- Parameters:
context
- theFacesContext
for this request.- Since:
- 2.2
-
disableClientWindowRenderMode
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(javax.faces.context.FacesContext)
from afinally
block after rendering the URL. IfCLIENT_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 actualClientWindow
instance.- Parameters:
context
- theFacesContext
for this request.- Since:
- 2.2
-
enableClientWindowRenderMode
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 actualClientWindow
instance.- Parameters:
context
- theFacesContext
for this request.- Since:
- 2.2
-
isClientWindowRenderModeEnabled
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 actualClientWindow
instance.- Parameters:
context
- theFacesContext
for this request.- Since:
- 2.2
-