public class UIViewAction extends UIComponentBase implements ActionSource2
UIViewAction represents a method invocation that occurs during the request processing lifecycle, usually in response to an initial request, as opposed to a postback.
The ViewDeclarationLanguage
implementation must cause an instance of this component to be
placed in the view for each occurrence of an <f:viewAction
/>
element placed inside of an <f:metadata
/>
element. The user must place <f:metadata
/>
as a direct child of the UIViewRoot
.
Because this class implements ActionSource2
, any actions that one would normally take on a component that
implements ActionSource2
, such as UICommand
, are valid for instances of this class. Instances of
this class participate in the regular Jakarta Server Faces lifecycle, including on Ajax requests.
The purpose of this component is to provide a light-weight front-controller solution for executing code upon the loading of a Jakarta Server Faces view to support the integration of system services, content retrieval, view management, and navigation. This functionality is especially useful for non-faces (initial) requests.
The most common use case for this component is to take actions necessary for a particular view, often with the help
of one or more UIViewParameter
s.
The NavigationHandler
is consulted after the action is invoked to carry out the navigation case that matches
the action signature and outcome. If a navigation case is matched that causes the new viewId to be different from the
current viewId, the runtime must force a redirect to that matched navigation case with different viewId, regardless
of whether or not the matched navigation case with different viewId called for a redirect.
If the navigation will result in a flow transition, the appropriate metadata must be
included in the query string for the redirect. See section 7.4.2 Default NavigationHandler Algorithm, for the
discussion of how to handle <redirect />
cases.
It's important to note that the full component tree is not built before the UIViewAction components are processed on
an non-faces (initial) request. Rather, the component tree only contains the ViewMetadata
, an important part
of the optimization of this component and what sets it apart from a PreRenderViewEvent
listener.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
COMPONENT_FAMILY
The standard component family for this component.
|
static java.lang.String |
COMPONENT_TYPE
The standard component type for this component.
|
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY
Constructor and Description |
---|
UIViewAction()
Create a new
UIViewAction instance with default property values. |
Modifier and Type | Method and Description |
---|---|
void |
addActionListener(ActionListener listener)
Add a new
ActionListener to the set of listeners interested in being notified when ActionEvent s
occur. |
void |
broadcast(FacesEvent event)
Enable the method invocation specified by this component instance to return a value that performs navigation, similar
in spirit to |
void |
decode(FacesContext context)
Override behavior from the superclass to queue an |
MethodBinding |
getAction()
Deprecated.
|
MethodExpression |
getActionExpression()
Return the
MethodExpression pointing at the application action to be invoked, if this UIComponent is
activated by the user, during the Apply Request Values or Invoke Application phase of the request
processing lifecycle, depending on the value of the immediate property. |
MethodBinding |
getActionListener()
Deprecated.
|
ActionListener[] |
getActionListeners()
Return the set of registered
ActionListener s for this ActionSource instance. |
java.lang.String |
getFamily()
Return the identifier of the component family to which this component belongs. |
java.lang.String |
getPhase()
Returns the name of the lifecycle phase in which the action is to be queued. |
boolean |
isImmediate()
If the value of the component's |
boolean |
isOnPostback()
If |
static boolean |
isProcessingBroadcast(FacesContext context)
Returns |
boolean |
isRendered()
Return |
void |
removeActionListener(ActionListener listener)
Remove an existing
ActionListener (if any) from the set of listeners interested in being notified when
ActionEvent s occur. |
void |
setAction(MethodBinding action)
Deprecated.
|
void |
setActionExpression(MethodExpression actionExpression)
Set the
MethodExpression pointing at the appication action to be invoked, if this UIComponent is
activated by the user, during the Apply Request Values or Invoke Application phase of the request
processing lifecycle, depending on the value of the immediate property. |
void |
setActionListener(MethodBinding actionListener)
Deprecated.
|
void |
setImmediate(boolean immediate)
Set the "immediate execution" flag for this
UIComponent . |
void |
setOnPostback(boolean onPostback)
Controls whether or not this component operates on postback. |
void |
setPhase(java.lang.String phase)
Attempt to set the lifecycle phase in which this instance will queue its |
void |
setRendered(boolean condition)
Sets the |
addClientBehavior, addFacesListener, clearInitialState, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent
encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree
public static final java.lang.String COMPONENT_TYPE
The standard component type for this component.
public static final java.lang.String COMPONENT_FAMILY
The standard component family for this component.
public UIViewAction()
Create a new UIViewAction
instance with default property values.
public java.lang.String getFamily()
UIComponent
Return the identifier of the component family to which this component belongs. This identifier, in conjunction with
the value of the rendererType
property, may be used to select the appropriate Renderer
for this
component instance. Note this method should NOT return null
getFamily
in class UIComponent
@Deprecated public MethodBinding getAction()
If the implementing class also implements ActionSource2
, the implementation of this method must call through
to ActionSource2.getActionExpression()
and examine the result. If the result came from a previous call to
ActionSource.setAction(jakarta.faces.el.MethodBinding)
, extract the MethodBinding
from it and return it. Otherwise, wrap the returned
MethodExpression
in a MethodBinding
implementation, and return it.
If the implementing class does not implement ActionSource2
, return the MethodBinding
pointing at
the application action to be invoked, if this UIComponent
is activated by the user, during the Apply
Request Values or Invoke Application phase of the request processing lifecycle, depending on the value
of the immediate
property.
getAction
in interface ActionSource
@Deprecated public void setAction(MethodBinding action)
If the implementing class also implements ActionSource2
, the implementation of this method must wrap the
argument action
in a class that implements MethodExpression
and call through to
ActionSource2.setActionExpression(jakarta.el.MethodExpression)
, passing the wrapped action
.
If the implementing class does not implement ActionSource2
, set the MethodBinding
pointing at
the appication action to be invoked, if this UIComponent
is activated by the user, during the Apply
Request Values or Invoke Application phase of the request processing lifecycle, depending on the value
of the immediate
property.
Any method referenced by such an expression must be public, with a return type of String
, and accept no
parameters.
setAction
in interface ActionSource
action
- The new MethodBinding expression@Deprecated public MethodBinding getActionListener()
If ActionSource.setActionListener(jakarta.faces.el.MethodBinding)
was not previously called for this instance, this method must return null
.
If it was called, this method must return the exact MethodBinding
instance that was passed to
ActionSource.setActionListener(jakarta.faces.el.MethodBinding)
.
The method to be invoked, if this UIComponent
is activated by the user, will be called during the Apply
Request Values or Invoke Application phase of the request processing lifecycle, depending upon the
value of the immediate
property.
getActionListener
in interface ActionSource
@Deprecated public void setActionListener(MethodBinding actionListener)
Wrap the argument actionListener
in an implementation of ActionListener
and store it in the
internal data structure that backs the ActionSource.getActionListeners()
method, taking care to over-write any instance
that was stored by a previous call to setActionListener
.
Any method referenced by such an expression must be public, with a return type of void
, and accept a
single parameter of type ActionEvent
.
setActionListener
in interface ActionSource
actionListener
- The new method binding expressionpublic boolean isImmediate()
If the value of the component's immediate
attribute is true
, the action will be invoked
during the Apply Request Values Jakarta Server Faces lifecycle phase. Otherwise, the action will be invoked
during the Invoke Application phase, the default behavior. The phase can be set explicitly in the
phase
attribute, which takes precedence over the immediate
attribute.
isImmediate
in interface ActionSource
true
if immediate, false
otherwise.public void setImmediate(boolean immediate)
Set the "immediate execution" flag for this UIComponent
.
setImmediate
in interface ActionSource
immediate
- The new immediate execution flagpublic java.lang.String getPhase()
Returns the name of the lifecycle phase in which the action is to be queued.
public void setPhase(java.lang.String phase)
Attempt to set the lifecycle phase in which this instance will queue its ActionEvent
. Pass the argument
phase
to PhaseId.phaseIdValueOf(java.lang.String)
. If the result is not one of the following values,
FacesException
must be thrown.
If set, this value takes precedence over the immediate flag.
phase
- the phase id (as string value).public static boolean isProcessingBroadcast(FacesContext context)
Returns true
if the current request processing lifecycle is in the midst of processing the broadcast of
an event queued during a call to decode(jakarta.faces.context.FacesContext)
. The implementation of broadcast(jakarta.faces.event.FacesEvent)
is responsible for
ensuring that calls to this method accurately reflect this fact.
context
- FacesContext
for the current requesttrue
is currently processing broadcast, false
otherwise.public void addActionListener(ActionListener listener)
Add a new ActionListener
to the set of listeners interested in being notified when ActionEvent
s
occur.
addActionListener
in interface ActionSource
listener
- The ActionListener
to be addedpublic ActionListener[] getActionListeners()
Return the set of registered ActionListener
s for this ActionSource
instance. If there are no
registered listeners, a zero-length array is returned.
getActionListeners
in interface ActionSource
public void removeActionListener(ActionListener listener)
Remove an existing ActionListener
(if any) from the set of listeners interested in being notified when
ActionEvent
s occur.
removeActionListener
in interface ActionSource
listener
- The ActionListener
to be removedpublic MethodExpression getActionExpression()
Return the MethodExpression
pointing at the application action to be invoked, if this UIComponent
is
activated by the user, during the Apply Request Values or Invoke Application phase of the request
processing lifecycle, depending on the value of the immediate
property.
Note that it's possible that the returned MethodExpression
is just a wrapper around a
MethodBinding
instance whith was set by a call to ActionSource.setAction(jakarta.faces.el.MethodBinding)
. This makes it possible
for the default ActionListener
to continue to work properly with older components.
getActionExpression
in interface ActionSource2
public void setActionExpression(MethodExpression actionExpression)
Set the MethodExpression
pointing at the appication action to be invoked, if this UIComponent
is
activated by the user, during the Apply Request Values or Invoke Application phase of the request
processing lifecycle, depending on the value of the immediate
property.
Any method referenced by such an expression must be public, with a return type of String
, and accept no
parameters.
setActionExpression
in interface ActionSource2
actionExpression
- the action expression.public boolean isOnPostback()
If true
this component will operate on postback.
true
if operating upon postback, false
otherwise.public void setOnPostback(boolean onPostback)
Controls whether or not this component operates on postback.
onPostback
- the onPostback flag.public boolean isRendered()
Return true
if this component should take the actions specified in the decode(jakarta.faces.context.FacesContext)
method.
isRendered
in class UIComponentBase
true
if it should be rendered, false
otherwise.public void setRendered(boolean condition)
Sets the if
property of this component.
setRendered
in class UIComponentBase
condition
- the new value of the property.public void broadcast(FacesEvent event) throws AbortProcessingException
Enable the method invocation specified by this component instance to return a value that performs navigation, similar
in spirit to UICommand.broadcast(jakarta.faces.event.FacesEvent)
.
Take no action and return immediately if any of the following conditions are true.
The response has already been marked as complete.
The current UIViewRoot
is different from the event's source's UIViewRoot
.
Save a local reference to the viewId of the current UIViewRoot
. For discussion, let this reference be
viewIdBeforeAction.
Obtain the ActionListener
from the Application
. Wrap the current
FacesContext
in an implementation of FacesContextWrapper
that overrides the
FacesContext.renderResponse()
method such that it takes no action. Set the current FacesContext
to
be the FacesContextWrapper
instance. Make it so a call to isProcessingBroadcast(jakarta.faces.context.FacesContext)
on the current
FacesContext will return true
. This is necessary because the
NavigationHandler
will call this method to determine if the navigation is happening
as the result of a UIViewAction
. Invoke ActionListener.processAction(jakarta.faces.event.ActionEvent)
. In a finally
block, restore the original FacesContext
, make it so a call to isProcessingBroadcast(jakarta.faces.context.FacesContext)
on the
current context will return false
and discard the wrapper.
If the response has been marked as complete during the invocation of processAction()
, take no further
action and return. Otherwise, compare viewIdBeforeAction with the viewId of the UIViewRoot
on
the FacesContext
after the invocation of processAction()
. If the two viewIds are the same
and no more UIViewAction
events have been queued by a call to decode(jakarta.faces.context.FacesContext)
, call
FacesContext.renderResponse()
and return. It is possible to detect the case where no more
UIViewAction
events have been queued because the number of such events queued has been noted in the
specification for decode(jakarta.faces.context.FacesContext)
. Otherwise, execute the lifecycle on the new UIViewRoot
.
broadcast
in class UIComponentBase
event
- FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Server Faces implementation that no further processing on the
current event should be performedjava.lang.IllegalArgumentException
- if the implementation class of this FacesEvent
is not supported by this
componentjava.lang.NullPointerException
- if event
is null
public void decode(FacesContext context)
Override behavior from the superclass to queue an ActionEvent
that may result in the invocation of the
action
or any actionListener
s that may be associated with this instance.
Take no action if any of the following conditions are true:
The current request is a postback and the instance has been configured to not operate on postback. See
isOnPostback()
.
The condition stated in the if
property evaluates to false
. See isRendered()
Instantiate an ActionEvent
, passing this component instance as the source. Set the phaseId
property of the ActionEvent
as follows.
If this component instance has been configured with a specific lifecycle phase with a call to setPhase(java.lang.String)
use
that as the phaseId
If the value of the immediate
property is true, use PhaseId.APPLY_REQUEST_VALUES
.
Otherwise, use PhaseId.INVOKE_APPLICATION
.
Queue the event with a call to UIComponentBase.queueEvent(jakarta.faces.event.FacesEvent)
. Keep track of the number of events that are queued in this way on
this run through the lifecycle. This information is necessary during processing in broadcast(jakarta.faces.event.FacesEvent)
.
decode
in class UIComponentBase
context
- FacesContext
for the request we are processing