javax.faces.component

## Class UICommand

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

- All Implemented Interfaces:
    EventListener, ActionSource, ActionSource2, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
  Direct Known Subclasses:
    HtmlCommandButton, HtmlCommandLink

      public class UICommand
      extends UIComponentBase
      implements ActionSource2

  UICommand is a `UIComponent` that represents a user interface component which, when activated by the user, triggers an application specific "command" or "action". Such a component is typically rendered as a push button, a menu item, or a hyperlink.

  When the `decode()` method of this `UICommand`, or its corresponding `Renderer`, detects that this control has been activated, it will queue an `ActionEvent`. Later on, the `broadcast()` method will ensure that this event is broadcast to all interested listeners.

  Listeners will be invoked in the following order:

  1. `ActionListener`s, in the order in which they were registered.
  2. The "actionListener" `MethodExpression` (which will cover the "actionListener" that was set as a `MethodBinding`).
  3. The default `ActionListener`, retrieved from the `Application` - and therefore, any attached "action" `MethodExpression`.

  By default, the `rendererType` property must be set to "`javax.faces.Button`". This value can be changed by calling the `setRendererType()` method.

- - ### 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
    `UICommand()` Create a new `UICommand` 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)` In addition to to the default `UIComponent.broadcast(javax.faces.event.FacesEvent)` processing, pass the `ActionEvent` being broadcast to the method referenced by `actionListener` (if any), and to the default `ActionListener` registered on the `Application`.
    `MethodBinding` | `getAction()` Deprecated. This has been replaced by `getActionExpression()`.
    `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. Use `getActionListeners()` instead.
    `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.
    `Object` | `getValue()` Returns the `value` property of the `UICommand`.
    `boolean` | `isImmediate()` The immediate flag.
    `void` | `queueEvent(FacesEvent e)` Intercept `queueEvent` and take the following action.
    `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. This has been replaced by `setActionExpression(javax.el.MethodExpression)`.
    `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. This has been replaced by `addActionListener(javax.faces.event.ActionListener)`.
    `void` | `setImmediate(boolean immediate)` Set the "immediate execution" flag for this `UIComponent`.
    `void` | `setValue(Object value)` Sets the `value` property of the `UICommand`.

    - ### Methods inherited from class javax.faces.component.UIComponentBase

      `addClientBehavior, addFacesListener, clearInitialState, decode, 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, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, 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

    - #### UICommand

          public UICommand()

      Create a new `UICommand` 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

          public MethodBinding getAction()

      Deprecated. This has been replaced by `getActionExpression()`.

      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`

    - #### setAction

          public void setAction(MethodBinding action)

      Deprecated. This has been replaced by `setActionExpression(javax.el.MethodExpression)`.

      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

    - #### getActionListener

          public MethodBinding getActionListener()

      Deprecated. Use `getActionListeners()` instead.

      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`

    - #### setActionListener

          public void setActionListener(MethodBinding actionListener)

      Deprecated. This has been replaced by `addActionListener(javax.faces.event.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`.

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

    - #### isImmediate

          public boolean isImmediate()

      The immediate flag.

      Specified by:
        `isImmediate` in interface `ActionSource`

    - #### setImmediate

          public void setImmediate(boolean immediate)

      Description copied from interface: `ActionSource`

      Set the "immediate execution" flag for this `UIComponent`.

      Specified by:
        `setImmediate` in interface `ActionSource`
      Parameters:
        `immediate` - The new immediate execution flag

    - #### getValue

          public Object getValue()

      Returns the `value` property of the `UICommand`. This is most often rendered as a label.

    - #### setValue

          public void setValue(Object value)

      Sets the `value` property of the `UICommand`. This is most often rendered as a label.

      Parameters:
        `value` - the new value

    - #### getActionExpression

          public MethodExpression getActionExpression()

      Description copied from interface: `ActionSource2`

      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`

    - #### setActionExpression

          public void setActionExpression(MethodExpression actionExpression)

      Description copied from interface: `ActionSource2`

      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

    - #### addActionListener

          public void addActionListener(ActionListener listener)

      Description copied from interface: `ActionSource`

      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
      Throws:
        `NullPointerException` - if `listener` is `null`

    - #### getActionListeners

          public ActionListener[] getActionListeners()

      Description copied from interface: `ActionSource`

      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`

    - #### removeActionListener

          public void removeActionListener(ActionListener listener)

      Description copied from interface: `ActionSource`

      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
      Throws:
        `NullPointerException` - if `listener` is `null`

    - #### broadcast

          public void broadcast(FacesEvent event)
                         throws AbortProcessingException

      In addition to to the default `UIComponent.broadcast(javax.faces.event.FacesEvent)` processing, pass the `ActionEvent` being broadcast to the method referenced by `actionListener` (if any), and to the default `ActionListener` registered on the `Application`.

      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`

    - #### queueEvent

          public void queueEvent(FacesEvent e)

      Intercept `queueEvent` and take the following action. If the event is an ``ActionEvent``, obtain the `UIComponent` instance from the event. If the component is an ``ActionSource`` obtain the value of its "immediate" property. If it is true, mark the phaseId for the event to be `PhaseId.APPLY_REQUEST_VALUES` otherwise, mark the phaseId to be `PhaseId.INVOKE_APPLICATION`. The event must be passed on to `super.queueEvent()` before returning from this method.

      Overrides:
        `queueEvent` in class `UIComponentBase`
      Parameters:
        `e` - `FacesEvent` to be queued

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