Class 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. ActionListeners, 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 Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE

      The standard component type for this component.

      See Also:
    • COMPONENT_FAMILY

      public static final String COMPONENT_FAMILY

      The standard component family for this component.

      See Also:
  • Constructor Details

    • UICommand

      public UICommand()

      Create a new UICommand instance with default property values.

  • Method Details

    • 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 MethodBindingpointing 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.

      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.

      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.

      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 javax.el.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(javax.el.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 ActionEvents 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 ActionListeners 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 ActionEvents 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