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

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

Go to download

This is the master POM file for Oracle's Implementation of the JSF 2.2 Specification.

There is a newer version: 2.2.20
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * 
 * Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.
 * 
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 * 
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 * 
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 * 
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 * 
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.

 */
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 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 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 */ 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. * * @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