All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.faces.lifecycle.ClientWindow Maven / Gradle / Ivy

There is a newer version: 3.1.0.SP02
Show newest version
/*
 * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package javax.faces.lifecycle;

import java.util.Map;
import javax.faces.context.FacesContext;
import javax.faces.render.ResponseStateManager;

/**
 * 

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 {@link * javax.faces.component.UIComponent} hierarchy rooted at a {@link * javax.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 {@link * #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 {@link * #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 Server 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 {@link Lifecycle#attachWindow} method. * This method will cause a new instance of ClientWindow to * be created, assigned an id, and passed to {@link * javax.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 {@link * javax.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 * {@link ResponseStateManager#CLIENT_WINDOW_URL_PARAM}. This * requirement is met by several of the "encode" methods on {@link * javax.faces.context.ExternalContext}. See {@link * javax.faces.context.ExternalContext#encodeActionURL(java.lang.String) * } for details.

*
*
* * @since 2.2 * */ public abstract class ClientWindow { /** *

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 = "javax.faces.CLIENT_WINDOW_MODE"; /** *

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 {@code 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.

* * * @since 2.2 * @param context the {@code FacesContext} for this request. * @return {@code null} or a map of parameters to insert into the URL query string. */ public abstract Map getQueryURLParameters(FacesContext context); /** *

Return a String value that uniquely * identifies this ClientWindow * within the scope of the current session. See {@link #decode} for the * specification of how to derive this value.

* * @since 2.2 * * @return the id of the {@code ClientWindow} */ public abstract String getId(); /** *

The implementation is responsible * for examining the incoming request and extracting the value that * must be returned from the {@link #getId} method. If {@link * #CLIENT_WINDOW_MODE_PARAM_NAME} is "none" this method must not be * invoked. If {@link #CLIENT_WINDOW_MODE_PARAM_NAME} is "url" the * implementation must first look for a request parameter under the * name given by the value of {@link * javax.faces.render.ResponseStateManager#CLIENT_WINDOW_PARAM}. If * no value is found, look for a request parameter under the name * given by the value of {@link * javax.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 * {@link #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 {@link #getId}.

* * @param context the {@link FacesContext} for this request. * * @since 2.2 */ public abstract void decode(FacesContext context); private static final String PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY = "javax.faces.lifecycle.ClientWindowRenderModeEnablement"; /** *

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 {@link #enableClientWindowRenderMode(javax.faces.context.FacesContext)} * from a finally block after rendering the URL. If * {@link #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 {@code ClientWindow} instance.

* * @param context the {@link FacesContext} for this request. * * @since 2.2 */ public void disableClientWindowRenderMode(FacesContext context) { Map attrMap = context.getAttributes(); attrMap.put(PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY, Boolean.TRUE); } /** *

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 * {@link #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 {@code ClientWindow} instance.

* * @param context the {@link FacesContext} for this request. * * @since 2.2 */ public void enableClientWindowRenderMode(FacesContext context) { Map attrMap = context.getAttributes(); attrMap.remove(PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY); } /** *

Methods that append the ClientWindow to generated * URLs must call this method to see if they are permitted to do so. If * {@link #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 {@code ClientWindow} instance.

* * @param context the {@link FacesContext} for this request. * * @return the result as specified above * * @since 2.2 */ public boolean isClientWindowRenderModeEnabled(FacesContext context) { boolean result = false; Map attrMap = context.getAttributes(); result = !attrMap.containsKey(PER_USE_CLIENT_WINDOW_URL_QUERY_PARAMETER_DISABLED_KEY); return result; } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy