Class UIViewAction
- All Implemented Interfaces:
ActionSource
,ActionSource2
,PartialStateHolder
,StateHolder
,TransientStateHolder
,ComponentSystemEventListener
,FacesListener
,SystemEventListenerHolder
,EventListener
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.
- Since:
- 2.2
-
Field Summary
Fields Modifier and Type Field Description static String
COMPONENT_FAMILY
The standard component family for this component.static String
COMPONENT_TYPE
The standard component type for this component.Fields inherited from class jakarta.faces.component.UIComponent
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 Summary
Constructors Constructor Description UIViewAction()
Create a newUIViewAction
instance with default property values. -
Method Summary
Modifier and Type Method Description void
addActionListener(ActionListener listener)
Add a newActionListener
to the set of listeners interested in being notified whenActionEvent
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 toUICommand.broadcast(jakarta.faces.event.FacesEvent)
.void
decode(FacesContext context)
Override behavior from the superclass to queue anActionEvent
that may result in the invocation of theaction
or anyactionListener
s that may be associated with this instance.MethodBinding
getAction()
Deprecated.jakarta.el.MethodExpression
getActionExpression()
Return theMethodExpression
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.MethodBinding
getActionListener()
Deprecated.ActionListener[]
getActionListeners()
Return the set of registeredActionListener
s for thisActionSource
instance.String
getFamily()
Return the identifier of the component family to which this component belongs.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'simmediate
attribute istrue
, the action will be invoked during the Apply Request Values Jakarta Server Faces lifecycle phase.boolean
isOnPostback()
Iftrue
this component will operate on postback.static boolean
isProcessingBroadcast(FacesContext context)
Returnstrue
if the current request processing lifecycle is in the midst of processing the broadcast of an event queued during a call todecode(jakarta.faces.context.FacesContext)
.boolean
isRendered()
Returntrue
if this component should take the actions specified in thedecode(jakarta.faces.context.FacesContext)
method.void
removeActionListener(ActionListener listener)
Remove an existingActionListener
(if any) from the set of listeners interested in being notified whenActionEvent
s occur.void
setAction(MethodBinding action)
Deprecated.void
setActionExpression(jakarta.el.MethodExpression actionExpression)
Set theMethodExpression
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.void
setActionListener(MethodBinding actionListener)
Deprecated.void
setImmediate(boolean immediate)
Set the "immediate execution" flag for thisUIComponent
.void
setOnPostback(boolean onPostback)
Controls whether or not this component operates on postback.void
setPhase(String phase)
Attempt to set the lifecycle phase in which this instance will queue itsActionEvent
.void
setRendered(boolean condition)
Sets theif
property of this component.Methods inherited from class jakarta.faces.component.UIComponentBase
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
Methods inherited from class jakarta.faces.component.UIComponent
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
-
Field Details
-
COMPONENT_TYPE
The standard component type for this component.
- See Also:
- Constant Field Values
-
COMPONENT_FAMILY
The standard component family for this component.
- See Also:
- Constant Field Values
-
-
Constructor Details
-
UIViewAction
public UIViewAction()Create a new
UIViewAction
instance with default property values.
-
-
Method Details
-
getFamily
Description copied from class: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 appropriateRenderer
for this component instance. Note this method should NOT returnnull
- Specified by:
getFamily
in classUIComponent
- Returns:
- the component family (not null).
-
getAction
Deprecated.If the implementing class also implements
ActionSource2
, the implementation of this method must call through toActionSource2.getActionExpression()
and examine the result. If the result came from a previous call toActionSource.setAction(jakarta.faces.el.MethodBinding)
, extract theMethodBinding
from it and return it. Otherwise, wrap the returnedMethodExpression
in aMethodBinding
implementation, and return it.If the implementing class does not implement
ActionSource2
, return theMethodBinding
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.- Specified by:
getAction
in interfaceActionSource
- Returns:
- the action.
- Since:
- 2.2
-
setAction
Deprecated.If the implementing class also implements
ActionSource2
, the implementation of this method must wrap the argumentaction
in a class that implementsMethodExpression
and call through toActionSource2.setActionExpression(jakarta.el.MethodExpression)
, passing the wrappedaction
.If the implementing class does not implement
ActionSource2
, set theMethodBinding
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.Any method referenced by such an expression must be public, with a return type of
String
, and accept no parameters.- Specified by:
setAction
in interfaceActionSource
- Parameters:
action
- The new MethodBinding expression- Since:
- 2.2
-
getActionListener
Deprecated.If
ActionSource.setActionListener(jakarta.faces.el.MethodBinding)
was not previously called for this instance, this method must returnnull
. If it was called, this method must return the exactMethodBinding
instance that was passed toActionSource.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 theimmediate
property.- Specified by:
getActionListener
in interfaceActionSource
- Returns:
- the action listener.
- Since:
- 2.2
-
setActionListener
Deprecated.Wrap the argument
actionListener
in an implementation ofActionListener
and store it in the internal data structure that backs theActionSource.getActionListeners()
method, taking care to over-write any instance that was stored by a previous call tosetActionListener
.Any method referenced by such an expression must be public, with a return type of
void
, and accept a single parameter of typeActionEvent
.- Specified by:
setActionListener
in interfaceActionSource
- Parameters:
actionListener
- The new method binding expression- Since:
- 2.2
-
isImmediate
public boolean isImmediate()If the value of the component's
immediate
attribute istrue
, 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 thephase
attribute, which takes precedence over theimmediate
attribute.- Specified by:
isImmediate
in interfaceActionSource
- Returns:
true
if immediate,false
otherwise.- Since:
- 2.2
-
setImmediate
public void setImmediate(boolean immediate)Set the "immediate execution" flag for this
UIComponent
.- Specified by:
setImmediate
in interfaceActionSource
- Parameters:
immediate
- The new immediate execution flag- Since:
- 2.2
-
getPhase
Returns the name of the lifecycle phase in which the action is to be queued.
- Returns:
- the phase (as string).
- Since:
- 2.2
-
setPhase
Attempt to set the lifecycle phase in which this instance will queue its
ActionEvent
. Pass the argumentphase
toPhaseId.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.
- Parameters:
phase
- the phase id (as string value).- Since:
- 2.2
-
isProcessingBroadcast
Returns
true
if the current request processing lifecycle is in the midst of processing the broadcast of an event queued during a call todecode(jakarta.faces.context.FacesContext)
. The implementation ofbroadcast(jakarta.faces.event.FacesEvent)
is responsible for ensuring that calls to this method accurately reflect this fact.- Parameters:
context
-FacesContext
for the current request- Returns:
true
is currently processing broadcast,false
otherwise.- Since:
- 2.2
-
addActionListener
Add a new
ActionListener
to the set of listeners interested in being notified whenActionEvent
s occur.- Specified by:
addActionListener
in interfaceActionSource
- Parameters:
listener
- TheActionListener
to be added- Since:
- 2.2
-
getActionListeners
Return the set of registered
ActionListener
s for thisActionSource
instance. If there are no registered listeners, a zero-length array is returned.- Specified by:
getActionListeners
in interfaceActionSource
- Returns:
- the action listeners, or a zero-length array.
- Since:
- 2.2
-
removeActionListener
Remove an existing
ActionListener
(if any) from the set of listeners interested in being notified whenActionEvent
s occur.- Specified by:
removeActionListener
in interfaceActionSource
- Parameters:
listener
- TheActionListener
to be removed- Since:
- 2.2
-
getActionExpression
public jakarta.el.MethodExpression getActionExpression()Return the
MethodExpression
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.Note that it's possible that the returned
MethodExpression
is just a wrapper around aMethodBinding
instance whith was set by a call toActionSource.setAction(jakarta.faces.el.MethodBinding)
. This makes it possible for the defaultActionListener
to continue to work properly with older components.- Specified by:
getActionExpression
in interfaceActionSource2
- Returns:
- the action expression.
- Since:
- 2.2
-
setActionExpression
public void setActionExpression(jakarta.el.MethodExpression actionExpression)Set the
MethodExpression
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.Any method referenced by such an expression must be public, with a return type of
String
, and accept no parameters.- Specified by:
setActionExpression
in interfaceActionSource2
- Parameters:
actionExpression
- the action expression.- Since:
- 2.2
-
isOnPostback
public boolean isOnPostback()If
true
this component will operate on postback.- Returns:
true
if operating upon postback,false
otherwise.- Since:
- 2.2
-
setOnPostback
public void setOnPostback(boolean onPostback)Controls whether or not this component operates on postback.
- Parameters:
onPostback
- the onPostback flag.- Since:
- 2.2
-
isRendered
public boolean isRendered()Return
true
if this component should take the actions specified in thedecode(jakarta.faces.context.FacesContext)
method.- Overrides:
isRendered
in classUIComponentBase
- Returns:
true
if it should be rendered,false
otherwise.- Since:
- 2.2
-
setRendered
public void setRendered(boolean condition)Sets the
if
property of this component.- Overrides:
setRendered
in classUIComponentBase
- Parameters:
condition
- the new value of the property.- Since:
- 2.2
-
broadcast
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'sUIViewRoot
.
Save a local reference to the viewId of the current
UIViewRoot
. For discussion, let this reference be viewIdBeforeAction.Obtain the
ActionListener
from theApplication
. Wrap the currentFacesContext
in an implementation ofFacesContextWrapper
that overrides theFacesContext.renderResponse()
method such that it takes no action. Set the currentFacesContext
to be theFacesContextWrapper
instance. Make it so a call toisProcessingBroadcast(jakarta.faces.context.FacesContext)
on the current FacesContext will returntrue
. This is necessary because theNavigationHandler
will call this method to determine if the navigation is happening as the result of aUIViewAction
. InvokeActionListener.processAction(jakarta.faces.event.ActionEvent)
. In afinally
block, restore the originalFacesContext
, make it so a call toisProcessingBroadcast(jakarta.faces.context.FacesContext)
on the current context will returnfalse
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 theUIViewRoot
on theFacesContext
after the invocation ofprocessAction()
. If the two viewIds are the same and no moreUIViewAction
events have been queued by a call todecode(jakarta.faces.context.FacesContext)
, callFacesContext.renderResponse()
and return. It is possible to detect the case where no moreUIViewAction
events have been queued because the number of such events queued has been noted in the specification fordecode(jakarta.faces.context.FacesContext)
. Otherwise, execute the lifecycle on the newUIViewRoot
.- Overrides:
broadcast
in classUIComponentBase
- Parameters:
event
-FacesEvent
to be broadcast- Throws:
AbortProcessingException
- Signal the Jakarta Server Faces implementation that no further processing on the current event should be performedIllegalArgumentException
- if the implementation class of thisFacesEvent
is not supported by this componentNullPointerException
- ifevent
isnull
- Since:
- 2.2
-
-
decode
Override behavior from the superclass to queue an
ActionEvent
that may result in the invocation of theaction
or anyactionListener
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 tofalse
. SeeisRendered()
Instantiate an
ActionEvent
, passing this component instance as the source. Set thephaseId
property of theActionEvent
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 thephaseId
-
If the value of the
immediate
property is true, usePhaseId.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 inbroadcast(jakarta.faces.event.FacesEvent)
.- Overrides:
decode
in classUIComponentBase
- Parameters:
context
-FacesContext
for the request we are processing- Since:
- 2.2
-
-