public abstract Class Flash

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 JSF 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 EL implicit object flash and also via javax.faces.context.ExternalContext#getFlash. The implementation must ensure that the flash is usable from both JSP and from Facelets for JSF 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 the EL as well, as described in the javadocs.

EL 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 JSP.

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.