javax.faces.component

## Class UIViewAction

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

- All Implemented Interfaces:
    EventListener, ActionSource, ActionSource2, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

      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 JSF 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 JSF 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 response is marked complete by the action, the lifecycle advances appropriately.

  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 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 javax.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 and Description
    `UIViewAction()` Create a new `UIViewAction` instance with default property values.

  - ### Method Summary

    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(javax.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.
    `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.
    `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's `immediate` attribute is `true`, the action will be invoked during the Apply Request Values JSF 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(javax.faces.context.FacesContext)`.
    `boolean` | `isRendered()` Return `true` if this component should take the actions specified in the `decode(javax.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` | `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(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 javax.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 javax.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`

    - ### 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 String COMPONENT_TYPE

      The standard component type for this component.

      See Also:
        Constant Field Values

    - #### COMPONENT_FAMILY

          public static final 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 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.

      Specified by:
        `getFamily` in class `UIComponent`

    - #### getAction

          @Deprecated
          public MethodBinding getAction()

      Deprecated.

      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(javax.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.

      Specified by:
        `getAction` in interface `ActionSource`
      Since:
        2.2

    - #### setAction

          @Deprecated
          public void setAction(MethodBinding action)

      Deprecated.

      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(javax.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.

      Specified by:
        `setAction` in interface `ActionSource`
      Parameters:
        `action` - The new MethodBinding expression
      Since:
        2.2

    - #### getActionListener

          @Deprecated
          public MethodBinding getActionListener()

      Deprecated.

      If `ActionSource.setActionListener(javax.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(javax.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.

      Specified by:
        `getActionListener` in interface `ActionSource`
      Since:
        2.2

    - #### setActionListener

          @Deprecated
          public void setActionListener(MethodBinding actionListener)

      Deprecated.

      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`.

      Specified by:
        `setActionListener` in interface `ActionSource`
      Parameters:
        `actionListener` - The new method binding expression
      Since:
        2.2

    - #### 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 JSF 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`
      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 String getPhase()

      Returns the name of the lifecycle phase in which the action is to be queued.

      Since:
        2.2

    - #### setPhase

          public void setPhase(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.

      - `PhaseId.APPLY_REQUEST_VALUES`

      - `PhaseId.PROCESS_VALIDATIONS`

      - `PhaseId.UPDATE_MODEL_VALUES`

      - `PhaseId.INVOKE_APPLICATION`

      If set, this value takes precedence over the immediate flag.

      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(javax.faces.context.FacesContext)`. The implementation of `broadcast(javax.faces.event.FacesEvent)` is responsible for ensuring that calls to this method accurately reflect this fact.

      Parameters:
        `context` - `FacesContext` for the current request
      Since:
        2.2

    - #### addActionListener

          public void addActionListener(ActionListener listener)

      Add a new `ActionListener` to the set of listeners interested in being notified when `ActionEvent`s 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 `ActionListener`s for this `ActionSource` instance. If there are no registered listeners, a zero-length array is returned.

      Specified by:
        `getActionListeners` in interface `ActionSource`
      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 `ActionEvent`s 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.

      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(javax.faces.el.MethodBinding)`. This makes it possible for the default `ActionListener` to continue to work properly with older components.

      Specified by:
        `getActionExpression` in interface `ActionSource2`
      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 new method expression
      Since:
        2.2

    - #### isOnPostback

          public boolean isOnPostback()

      If `true` this component will operate on postback.

      Since:
        2.2

    - #### setOnPostback

          public void setOnPostback(boolean onPostback)

      Controls whether or not this component operates on postback.

      Since:
        2.2

    - #### isRendered

          public boolean isRendered()

      Return `true` if this component should take the actions specified in the `decode(javax.faces.context.FacesContext)` method.

      Overrides:
        `isRendered` in class `UIComponentBase`
      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(javax.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(javax.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(javax.faces.event.ActionEvent)`. In a `finally` block, restore the original `FacesContext`, make it so a call to `isProcessingBroadcast(javax.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(javax.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(javax.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 JavaServer Faces implementation that no further processing on the current event should be performed
        `IllegalArgumentException` - if the implementation class of this `FacesEvent` is not supported by this component
        `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 `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(javax.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(javax.faces.event.FacesEvent)`.

      Overrides:
        `decode` in class `UIComponentBase`
      Parameters:
        `context` - `FacesContext` for the request we are processing
      Since:
        2.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.