jakarta.faces.context.Flash Maven / Gradle / Ivy
Show all versions of jakarta.faces-api Show documentation
/*
* Copyright (c) 1997, 2020 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 jakarta.faces.context;
import java.util.Map;
import jakarta.faces.event.PostKeepFlashValueEvent;
import jakarta.faces.event.PostPutFlashValueEvent;
/**
*
* The Flash concept is taken from Ruby on Rails and provides
* a way to pass temporary objects between the user views generated by the faces lifecycle. As in Rails, anything one
* places in the flash will be exposed to the next view encountered by the same user session and then cleared out. It is
* important to note that “next view” may have the same view id as the previous view.
*
*
*
*
*
* Implementation Requirements
*
*
*
* The flash is a session scoped object that must be thread safe.
*
*
*
* The implementation requirements will be described in terms of the runtime traversing the Jakarta Server Faces
* lifecycle. The flash exposes a Map interface over two logical maps. The choice of which logical map is
* accessed depends on the current faces lifecycle phase. One logical map is for the current traversal and the other is
* for the next traversal. During the execute portion of the lifecycle, all flash accesses are sent to the current
* traversal map. During the render portion of the lifecycle, all flash accesses are sent to the next traversal map. On
* the next traversal through the lifecycle, the implementation must ensure that the current traversal map is the next
* traversal map of the previous traversal. Here is an example for illustration purposes only.
*
*
*
*
*
* Consider an initial request to the faces lifecycle
*
*
*
* Traversal N, execute phase: skipped on initial request.
*
*
*
* Traversal N, render phase: flash access goes to flash[N].
*
*
*
* Traversal N+1, execute phase: flash access goes to flash[N].
*
*
*
* Traversal N+1, render phase: flash access goes to flash[N+1].
*
*
*
*
*
* The implementation must ensure the proper behaviour of the flash is preserved even in the case of a
* <navigation-case> that contains a <redirect />. The implementation must ensure
* the proper behavior of the flash is preserved even in the case of adjacent GET requests on the same session. This
* allows Faces applications to fully utilize the “Post/Redirect/Get” design pattern.
*
*
*
* The implementation must allow the user to access the flash via the Jakarta Expression Language implicit object
* flash and also via {@link jakarta.faces.context.ExternalContext#getFlash}. The implementation must
* ensure that the flash is usable from both Jakarta Server Pages and from Facelets for Jakarta Server Faces 2. In
* addition to exposing the Map interface, there are several features exposed as methods on the
* Flash itself. Each of these features may be accessed via Jakarta Expression Language as well, as
* described in the javadocs.
*
*
*
* Jakarta Expression Language Usage Example
*
*
*
*
*
* First page
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:c="http://xmlns.jcp.org/jsp/jstl/core">
<!-- extra code removed -->
<c:set target="#{flash}" property="foo" value="fooValue" />
*
*
*
* Next page
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://xmlns.jcp.org/jsf/html">
<!-- extra code removed -->
<h:outputText value="#{flash.foo}" /> will be "fooValue"
without the quotes.
*
*
*
*
*
* The same usage syntax must be available in Jakarta Server Pages.
*
*
*
* Note that extra action must be taken when using the flash in concert with output components that cause the browser to
* issue a GET request when clicked, such as h:button and h:link. The following example
* illustrates one way to use the flash in such circumstances.
*
*
*
*
*
* First page
*
*
*
*
<h:button id="nextButton" value="Next (button)" outcome="next.xhtml">
<f:param name="foo" value="bar"/>
</h:button>
*
*
*
* Next page
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://xmlns.jcp.org/jsf/core"
xmlns:h="http://xmlns.jcp.org/jsf/html">
<f:metadata>
<f:viewParam name="foo" id="foo" value="#{flash.now.foo}" />
</f:metadata>
<head /><body>
foo = #{flash.foo}
</body>
</html>
*
*
*
*
*
* Note that this example uses #{flash.now} on the second page. This is because the value doesn't actuall
* enter the flash until the server is processing the GET request sent by the browser due to the button being clicked.
*
*
*
*
* @since 2.0
*
*/
public abstract class Flash implements Map {
/**
*
* Because null values are not allowed as the source for subclasses of EventObject, such as
* {@link PostKeepFlashValueEvent} and {@link PostPutFlashValueEvent}, this value is substituted for null
* as the source in the case when a null value is put to or kept in the flash.
*/
public static final String NULL_VALUE = "jakarta.faces.context.Flash.NULL_VALUE";
/**
*
* Return the value of this JavaBeans property for the flash for this session. This value determines whether or not any
* {@link jakarta.faces.application.FacesMessage} instances queued in the current
* {@link jakarta.faces.context.FacesContext} must be preserved so they are accessible on the next traversal of the
* lifecycle on this session, regardless of the request being a redirect after post, or a normal postback.
* Map accesses for the special key “keepMessages” must return the value of this
* JavaBeans property.
*
*
*
*
*
*
* Jakarta Expression Language Usage Example
*
*
*
*
*
* First page
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:c="http://xmlns.jcp.org/jsp/jstl/core">
<!-- extra code removed -->
<c:set target="#{flash}" property="keepMessages" value="true" />
*
*
*
* Next page
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://xmlns.jcp.org/jsf/html">
<!-- extra code removed -->
<h:messages /> Any messages present on the first page must be displayed on
this page.
*
*
*
*
*
*
* @return the boolean flag whether keeping messages or not.
*
* @since 2.0
*
*/
public abstract boolean isKeepMessages();
/**
*
* Setter for keepMessages JavaBeans property. See {@link #isKeepMessages}.
*
*
* @param newValue the new value for this property on this session.
*
* @since 2.0
*/
public abstract void setKeepMessages(boolean newValue);
/**
*
* Return the value of this property for the flash for this session. This must be false unless:
*
*
*
*
*
*
*
* -
*
* {@link #setRedirect} was called for the current lifecycle traversal with true as the argument.
*
*
*
* -
*
* The current lifecycle traversal for this session is in the “execute” phase and the previous traversal had
* {@link #setRedirect} called with true as the argument.
*
*
*
*
*
* @return the value of this property for the flash for this session.
*
*/
public abstract boolean isRedirect();
/**
*
* Setting this property to true indicates that the next request on this session will be a redirect. Recall
* that on a redirect, the server sends a special response to the client instructing it to issue a new request to a
* specific URI. The implementation must insure that reading the value of this property on that request will return
* true.
*
*
*
*
*
* Jakarta Expression Language Usage Example
*
*
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:c="http://xmlns.jcp.org/jsp/jstl/core">
<!-- extra code removed -->
<c:set target="#{flash}" property="redirect" value="true" />
*
*
*
*
*
*
*
* @param newValue the new value for this property on this session.
*
* @since 2.0
*
*/
public abstract void setRedirect(boolean newValue);
/**
*
* Puts a value in the flash so that it can be accessed on this traversal of the lifecycle, rather than on the next
* traversal. This is simply an alias for putting a value in the request map.
*
*
*
*
*
* Jakarta Expression Language Usage Example
*
*
*
*
*
*
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:c="http://xmlns.jcp.org/jsp/jstl/core">
<!-- extra code removed -->
<c:set target="#{flash.now}" property="bar" value="barValue" />
<p>Value of \#{flash.now.bar}, should be barValue.</p>
<h:outputText value="#{flash.now.bar}" />
*
*
*
*
*
*
* @param key the key for this entry
*
* @param value the value for this entry
*
* @since 2.0
*
*/
public abstract void putNow(String key, Object value);
/**
*
* Causes a value stored with a previous call to {@link #putNow}, its Jakarta Expression Language equivalent, or to the
* request Map, to be promoted to the flash so that is available on the next traversal through the
* lifecycle on this session.
*
*
* @param key if argument key is the name of an entry previously stored to the flash on this traversal
* through the lifecycle via a call to {@link #putNow}, or to a set to the EL expression
* #{flash.now.<key>}, or to the request Map, to be promoted to the flash as if a
* call to put() or a set to the expression #{flash.<key>} was being called.
*/
public abstract void keep(String key);
/**
*
* Called before the execution of every lifecycle phase, this method allows implementations to take the necessary
* actions to provide the Flash scope contract as it applies to the request procesing lifecycle.
*
*
* @param ctx the FacesContext for this request.
*/
public abstract void doPrePhaseActions(FacesContext ctx);
/**
*
* Called after the execution of every lifecycle phase, this method allows implementations to take the necessary actions
* to provide the Flash scope contract as it applies to the request procesing lifecycle.
*
*
* @param ctx the FacesContext for this request.
*/
public abstract void doPostPhaseActions(FacesContext ctx);
}