Top Description Inners Fields Constructors Methods
javax.faces.component

public Class UICommand

extends UIComponentBase
implements ActionSource2
Class Inheritance
All Implemented Interfaces
javax.faces.component.ActionSource2, javax.faces.component.ActionSource
Known Direct Subclasses
javax.faces.component.html.HtmlCommandButton, javax.faces.component.html.HtmlCommandLink, javax.faces.component.html.HtmlCommandScript
Static Imports
javax.faces.event.PhaseId.APPLY_REQUEST_VALUES, .PhaseId.INVOKE_APPLICATION

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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static enum
UICommand.PropertyKeys

Properties that are tracked by state saving.

Field Summary

Modifier and TypeField and Description
public static final String
COMPONENT_FAMILY

The standard component family for this component.

public static final String
COMPONENT_TYPE

The standard component type for this component.

Constructor Summary

AccessConstructor and Description
public
UICommand()

Create a new UICommand instance with default property values.

Method Summary

Modifier and TypeMethod and Description
public void
addActionListener(ActionListener
The ActionListener to be added
listener)

Implements javax.faces.component.ActionSource.addActionListener.

Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.

public void
broadcast(FacesEvent
FacesEvent to be broadcast
event)

Overrides javax.faces.component.UIComponentBase.broadcast.

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

public MethodBinding
getAction()

Implements javax.faces.component.ActionSource.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.

public MethodExpression
getActionExpression()

Implements javax.faces.component.ActionSource2.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.

public MethodBinding
getActionListener()

Implements javax.faces.component.ActionSource.getActionListener.

Deprecated Use getActionListeners instead.

If setActionListener was not previously called for this instance, this method must return null.

public ActionListener[]
getActionListeners()

Implements javax.faces.component.ActionSource.getActionListeners.

Return the set of registered ActionListeners for this ActionSource instance.

public String
getFamily()

Implements abstract javax.faces.component.UIComponent.getFamily.

Return the identifier of the component family to which this component belongs.

public Object

Returns:

The object representing the value of this component.
getValue()

Returns the value property of the UICommand.

public boolean
isImmediate()

Implements javax.faces.component.ActionSource.isImmediate.

The immediate flag.

private void
notifySpecifiedActionListener(FacesContext context, FacesEvent event)

public void
queueEvent(FacesEvent
FacesEvent to be queued
event)

Overrides javax.faces.component.UIComponentBase.queueEvent.

Intercept queueEvent and take the following action.

public void
removeActionListener(ActionListener
The ActionListener to be removed
listener)

Implements javax.faces.component.ActionSource.removeActionListener.

Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.

public void
setAction(MethodBinding
The new MethodBinding expression
action)

Implements javax.faces.component.ActionSource.setAction.

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 javax.el.MethodExpression and call through to ActionSource2#setActionExpression, passing the wrapped action.

public void
setActionExpression(MethodExpression
The new method expression
actionExpression)

Implements javax.faces.component.ActionSource2.setActionExpression.

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.

public void
setActionListener(MethodBinding
The new method binding expression
actionListener)

Implements javax.faces.component.ActionSource.setActionListener.

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 getActionListeners method, taking care to over-write any instance that was stored by a previous call to setActionListener.

public void
setImmediate(boolean
The new immediate execution flag
immediate)

Implements javax.faces.component.ActionSource.setImmediate.

Set the "immediate execution" flag for this UIComponent.

public void
setValue(Object
the new value
value)

Sets the value property of the UICommand.

Inherited from javax.faces.component.UIComponentBase:
addClientBehavioraddFacesListenerclearInitialStatedecodeencodeBeginencodeChildrenencodeEndfindComponentgetAttributesgetChildCountgetChildrengetClientBehaviorsgetClientIdgetDefaultEventNamegetDescriptorMapgetEventNamesgetFacesContextgetFacesListenersgetFacetgetFacetCountgetFacetsgetFacetsAndChildrengetIdgetListenersForEventClassgetParentgetPassThroughAttributesgetRenderergetRendererTypegetRendersChildrengetValueBindinginvokeOnComponentisRenderedisTransientmarkInitialStateprocessDecodesprocessRestoreStateprocessSaveStateprocessUpdatesprocessValidatorsremoveFacesListenerrestoreAttachedStaterestoreStatesaveAttachedStatesaveStatesetIdsetParentsetRenderedsetRendererTypesetTransientsetValueBindingsubscribeToEventunsubscribeFromEvent

Field Detail

COMPONENT_FAMILYback to summary
public static final String COMPONENT_FAMILY

The standard component family for this component.

COMPONENT_TYPEback to summary
public static final String COMPONENT_TYPE

The standard component type for this component.

Constructor Detail

UICommandback to summary
public UICommand()

Create a new UICommand instance with default property values.

Method Detail

addActionListenerback to summary
public void addActionListener(ActionListener listener)

Implements javax.faces.component.ActionSource.addActionListener.

Doc from javax.faces.component.ActionSource.addActionListener.

Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.

Parameters
listener:ActionListener

The ActionListener to be added

Annotations
@Override
Exceptions
NullPointerException:
if listener is null
broadcastback to summary
public void broadcast(FacesEvent event) throws AbortProcessingException

Overrides javax.faces.component.UIComponentBase.broadcast.

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

Parameters
event:FacesEvent

FacesEvent to be broadcast

Annotations
@Override
Exceptions
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
getActionback to summary
public MethodBinding getAction()

Implements javax.faces.component.ActionSource.getAction.

Doc from javax.faces.component.ActionSource.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 setAction, extract the MethodBinding from it and return it. Otherwise, wrap the returned javax.el.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.

Returns:MethodBinding

the action.

Annotations
@Override
getActionExpressionback to summary
public MethodExpression getActionExpression()

Implements javax.faces.component.ActionSource2.getActionExpression.

Doc from javax.faces.component.ActionSource2.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. This makes it possible for the default ActionListener to continue to work properly with older components.

Returns:MethodExpression

the action expression.

Annotations
@Override
getActionListenerback to summary
public MethodBinding getActionListener()

Implements javax.faces.component.ActionSource.getActionListener.

Doc from javax.faces.component.ActionSource.getActionListener.

Deprecated

Use getActionListeners instead.

If setActionListener 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 setActionListener.

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.

Returns:MethodBinding

the action listener.

Annotations
@Override
getActionListenersback to summary
public ActionListener[] getActionListeners()

Implements javax.faces.component.ActionSource.getActionListeners.

Doc from javax.faces.component.ActionSource.getActionListeners.

Return the set of registered ActionListeners for this ActionSource instance. If there are no registered listeners, a zero-length array is returned.

Returns:ActionListener[]

the action listeners, or a zero-length array.

Annotations
@Override
getFamilyback to summary
public String getFamily()

Implements abstract javax.faces.component.UIComponent.getFamily.

Doc from javax.faces.component.UIComponent.getFamily.

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

Returns:String

the component family (not null).

Annotations
@Override
getValueback to summary
public Object getValue()

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

Returns:Object

The object representing the value of this component.

isImmediateback to summary
public boolean isImmediate()

Implements javax.faces.component.ActionSource.isImmediate.

The immediate flag.

Returns:boolean

Doc from javax.faces.component.ActionSource.isImmediate.

true if immediate, false otherwise.

Annotations
@Override
notifySpecifiedActionListenerback to summary
private void notifySpecifiedActionListener(FacesContext context, FacesEvent event)
queueEventback to summary
public void queueEvent(FacesEvent event)

Overrides javax.faces.component.UIComponentBase.queueEvent.

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.

Parameters
event:FacesEvent

Doc from javax.faces.component.UIComponent.queueEvent.

FacesEvent to be queued

Annotations
@Override
removeActionListenerback to summary
public void removeActionListener(ActionListener listener)

Implements javax.faces.component.ActionSource.removeActionListener.

Doc from javax.faces.component.ActionSource.removeActionListener.

Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.

Parameters
listener:ActionListener

The ActionListener to be removed

Annotations
@Override
Exceptions
NullPointerException:
if listener is null
setActionback to summary
public void setAction(MethodBinding action)

Implements javax.faces.component.ActionSource.setAction.

Doc from javax.faces.component.ActionSource.setAction.

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 javax.el.MethodExpression and call through to ActionSource2#setActionExpression, 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.

Parameters
action:MethodBinding

The new MethodBinding expression

Annotations
@Override
setActionExpressionback to summary
public void setActionExpression(MethodExpression actionExpression)

Implements javax.faces.component.ActionSource2.setActionExpression.

Doc from javax.faces.component.ActionSource2.setActionExpression.

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.

Parameters
actionExpression:MethodExpression

The new method expression

Annotations
@Override
setActionListenerback to summary
public void setActionListener(MethodBinding actionListener)

Implements javax.faces.component.ActionSource.setActionListener.

Doc from javax.faces.component.ActionSource.setActionListener.

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

Parameters
actionListener:MethodBinding

The new method binding expression

Annotations
@Override
setImmediateback to summary
public void setImmediate(boolean immediate)

Implements javax.faces.component.ActionSource.setImmediate.

Doc from javax.faces.component.ActionSource.setImmediate.

Set the "immediate execution" flag for this UIComponent.

Parameters
immediate:boolean

The new immediate execution flag

Annotations
@Override
setValueback to summary
public void setValue(Object value)

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

Parameters
value:Object

the new value

javax.faces.component back to summary

pack-priv final Enum UICommand.PropertyKeys

extends Enum<UICommand.PropertyKeys>
Class Inheritance
Properties that are tracked by state saving.

Field Summary

Modifier and TypeField and Description
public static final UICommand.PropertyKeys
actionExpression

public static final UICommand.PropertyKeys
immediate

public static final UICommand.PropertyKeys
methodBindingActionListener

public static final UICommand.PropertyKeys
value

Constructor Summary

AccessConstructor and Description
private
PropertyKeys()

Method Summary

Modifier and TypeMethod and Description
public static UICommand.PropertyKeys
valueOf(String name)

public static UICommand.PropertyKeys[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

actionExpressionback to summary
public static final UICommand.PropertyKeys actionExpression
immediateback to summary
public static final UICommand.PropertyKeys immediate
methodBindingActionListenerback to summary
public static final UICommand.PropertyKeys methodBindingActionListener
valueback to summary
public static final UICommand.PropertyKeys value

Constructor Detail

PropertyKeysback to summary
private PropertyKeys()

Method Detail

valueOfback to summary
public static UICommand.PropertyKeys valueOf(String name)
valuesback to summary
public static UICommand.PropertyKeys[] values()