Class Flash
- Direct Known Subclasses:
FlashWrapper
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 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].
Traversan 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 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.
- Since:
- 2.0
-
Nested Class Summary
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Becausenull
values are not allowed as the source for subclasses ofEventObject
, such asPostKeepFlashValueEvent
andPostPutFlashValueEvent
, this value is substituted fornull
as the source in the case when anull
value is put to or kept in the flash. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
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.abstract void
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.abstract boolean
Return the value of this JavaBeans property for the flash for this session.abstract boolean
Return the value of this property for the flash for this session.abstract void
Causes a value stored with a previous call toputNow(java.lang.String, java.lang.Object)
, its EL equivalent, or to the requestMap
, to be promoted to the flash so that is available on the next traversal through the lifecycle on this session.abstract void
Puts a value in the flash so that it can be accessed on this traversal of the lifecycle, rather than on the next traversal.abstract void
setKeepMessages
(boolean newValue) Setter forkeepMessages
JavaBeans property.abstract void
setRedirect
(boolean newValue) Setting this property totrue
indicates that the next request on this session will be a redirect.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.util.Map
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values
-
Field Details
-
NULL_VALUE
Because
null
values are not allowed as the source for subclasses ofEventObject
, such asPostKeepFlashValueEvent
andPostPutFlashValueEvent
, this value is substituted fornull
as the source in the case when anull
value is put to or kept in the flash.- See Also:
-
-
Constructor Details
-
Flash
public Flash()
-
-
Method Details
-
isKeepMessages
public abstract boolean isKeepMessages()Return the value of this JavaBeans property for the flash for this session. This value determines whether or not any
FacesMessage
instances queued in the currentFacesContext
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.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="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.
- Since:
- 2.0
-
setKeepMessages
public abstract void setKeepMessages(boolean newValue) Setter for
keepMessages
JavaBeans property. SeeisKeepMessages()
.- Parameters:
newValue
- the new value for this property on this session.- Since:
- 2.0
-
isRedirect
public abstract boolean isRedirect()Return the value of this property for the flash for this session. This must be
false
unless:setRedirect(boolean)
was called for the current lifecycle traversal withtrue
as the argument.The current lifecycle traversal for this session is in the “execute” phase and the previous traversal had
setRedirect(boolean)
called withtrue
as the argument.
-
setRedirect
public abstract void setRedirect(boolean newValue) 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 returntrue
.EL 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" />
- Parameters:
newValue
- the new value for this property on this session.- Since:
- 2.0
-
putNow
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.
EL 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}" />
- Parameters:
key
- the key for this entryvalue
- the value for this entry- Since:
- 2.0
-
keep
Causes a value stored with a previous call to
putNow(java.lang.String, java.lang.Object)
, its EL equivalent, or to the requestMap
, to be promoted to the flash so that is available on the next traversal through the lifecycle on this session.- Parameters:
key
- if argumentkey
is the name of an entry previously stored to the flash on this traversal through the lifecycle via a call toputNow(java.lang.String, java.lang.Object)
, or to a set to the EL expression#{flash.now.<key>}
, or to the requestMap
, to be promoted to the flash as if a call toput()
or a set to the expression#{flash.<key>}
was being called.
-
doPrePhaseActions
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.
- Parameters:
ctx
- theFacesContext
for this request.
-
doPostPhaseActions
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.
- Parameters:
ctx
- theFacesContext
for this request.
-