UIViewAction

java.lang.Object
- jakarta.faces.component.UIComponent
- - jakarta.faces.component.UIComponentBase
  - - jakarta.faces.component.UIViewAction

All Implemented Interfaces:

ActionSource, ActionSource2, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, java.util.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 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 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 UIViewParameters.

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" of the Jakarta Faces Specification Document, for the specification 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 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.

Fields inherited from class jakarta.faces.component.UIComponent
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY

Constructor Summary

Constructors
Constructor and Description

UIViewAction()
Create a new UIViewAction instance with default property values.

Constructors
Constructor and Description
`UIViewAction()` Create a new `UIViewAction` instance with default property values.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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 `UICommand.broadcast(jakarta.faces.event.FacesEvent)`.
`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.
`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.
`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 `immediate` attribute is `true`, the action will be invoked during the Apply Request Values Jakarta Faces lifecycle phase.
`boolean`	`isOnPostback()` If `true` this component will operate on postback.
`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)`.
`boolean`	`isRendered()` Return `true` if this component should take the actions specified in the `decode(jakarta.faces.context.FacesContext)` method.
`void`	`removeActionListener(ActionListener listener)` Remove an existing `ActionListener` (if any) from the set of listeners interested in being notified when `ActionEvent`s occur.
`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`	`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 `ActionEvent`.
`void`	`setRendered(boolean condition)` Sets the `if` property of this component.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - COMPONENT_TYPE
```
public static final java.lang.String COMPONENT_TYPE
```
    The standard component type for this component.
    
    See Also:
    
    Constant Field Values
  - COMPONENT_FAMILY
```
public static final java.lang.String COMPONENT_FAMILY
```
    The standard component family for this component.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - UIViewAction
```
public UIViewAction()
```
    Create a new UIViewAction instance with default property values.
- Method Detail
  - getFamily
```
public java.lang.String 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 appropriate Renderer for this component instance. Note this method should NOT return null
    
    Specified by:
    
    getFamily in class UIComponent
    
    Returns:
    
    the component family (not null).
  - isImmediate
```
public boolean isImmediate()
```
    If the value of the component's immediate attribute is true, the action will be invoked during the Apply Request Values Jakarta 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.
    
    Specified by:
    
    isImmediate in interface ActionSource
    
    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 interface ActionSource
    
    Parameters:
    
    immediate - The new immediate execution flag
    
    Since:
    
    2.2
  - getPhase
```
public java.lang.String 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
```
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.
    Parameters:
    
    phase - the phase id (as string value).
    
    Since:
    
    2.2
  - isProcessingBroadcast
```
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.
    
    Parameters:
    
    context - FacesContext for the current request
    
    Returns:
    
    true is currently processing broadcast, false otherwise.
    
    Since:
    
    2.2
  - addActionListener
```
public void addActionListener(ActionListener listener)
```
    Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.
    
    Specified by:
    
    addActionListener in interface ActionSource
    
    Parameters:
    
    listener - The ActionListener to be added
    
    Since:
    
    2.2
  - getActionListeners
```
public ActionListener[] getActionListeners()
```
    Return the set of registered ActionListeners for this ActionSource instance. If there are no registered listeners, a zero-length array is returned.
    
    Specified by:
    
    getActionListeners in interface ActionSource
    
    Returns:
    
    the action listeners, or a zero-length array.
    
    Since:
    
    2.2
  - removeActionListener
```
public void removeActionListener(ActionListener listener)
```
    Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.
    
    Specified by:
    
    removeActionListener in interface ActionSource
    
    Parameters:
    
    listener - The ActionListener to be removed
    
    Since:
    
    2.2
  - getActionExpression
```
public 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.
    
    Specified by:
    
    getActionExpression in interface ActionSource2
    
    Returns:
    
    the action expression.
    
    Since:
    
    2.2
  - setActionExpression
```
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.
    
    Specified by:
    
    setActionExpression in interface ActionSource2
    
    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 the decode(jakarta.faces.context.FacesContext) method.
    
    Overrides:
    
    isRendered in class UIComponentBase
    
    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 class UIComponentBase
    
    Parameters:
    
    condition - the new value of the property.
    
    Since:
    
    2.2
  - broadcast
```
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.
    Overrides:
    
    broadcast in class UIComponentBase
    
    Parameters:
    
    event - FacesEvent to be broadcast
    
    Throws:
    
    AbortProcessingException - Signal the Jakarta Faces implementation that no further processing on the current event should be performed
    
    java.lang.IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component
    
    java.lang.NullPointerException - if event is null
    
    Since:
    
    2.2
  - decode
```
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 actionListeners 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).
    Overrides:
    
    decode in class UIComponentBase
    
    Parameters:
    
    context - FacesContext for the request we are processing
    
    Since:
    
    2.2

Class UIViewAction

Field Summary

Fields inherited from class jakarta.faces.component.UIComponent

Constructor Summary

Method Summary

Methods inherited from class jakarta.faces.component.UIComponentBase

Methods inherited from class jakarta.faces.component.UIComponent

Methods inherited from class java.lang.Object

Field Detail

COMPONENT_TYPE

COMPONENT_FAMILY

Constructor Detail

UIViewAction

Method Detail

getFamily

isImmediate

setImmediate

getPhase

setPhase

isProcessingBroadcast

addActionListener

getActionListeners

removeActionListener

getActionExpression

setActionExpression

isOnPostback

setOnPostback

isRendered

setRendered

broadcast

decode