Module jakarta.faces

Package jakarta.faces.component

Class UICommand

java.lang.Object

jakarta.faces.component.UIComponent

jakarta.faces.component.UIComponentBase

jakarta.faces.component.UICommand

All Implemented Interfaces:

ActionSource, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener

Direct Known Subclasses:

HtmlCommandButton, HtmlCommandLink, HtmlCommandScript

public class UICommand
extends UIComponentBase
implements ActionSource

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 "jakarta.faces.Button". This value can be changed by calling the setRendererType() method.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COMPONENT_FAMILY	The standard component family for this component.
static final 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, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor	Description
UICommand()	Create a new UICommand instance with default property values.

Method Summary

Modifier and Type	Method	Description
void	addActionListener(ActionListener listener)	Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.
void	broadcast(FacesEvent event)	In addition to to the default UIComponent.broadcast(jakarta.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.
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 ActionListeners 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 event)	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 ActionEvents 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	setValue(Object value)	Sets the value property of the UICommand.

Methods inherited from class jakarta.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, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class jakarta.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 Details

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 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. Note this method should NOT return null

Specified by:

getFamily in class UIComponent

Returns:

the component family (not null).

isImmediate

public boolean isImmediate()

The immediate flag.

Specified by:

isImmediate in interface ActionSource

Returns:

true if immediate, false otherwise.

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.

Returns:

The object representing the value of this component.

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: ActionSource

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.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend ActionSource. Historically this method was declared in ActionSource2 for precisely this reason but default methods in interfaces weren't supported.

Specified by:

getActionExpression in interface ActionSource

Returns:

the action expression.

setActionExpression

public void setActionExpression(MethodExpression actionExpression)

Description copied from interface: ActionSource

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.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend ActionSource. Historically this method was declared in ActionSource2 for precisely this reason but default methods in interfaces weren't supported.

Specified by:

setActionExpression in interface ActionSource

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

Returns:

the action listeners, or a zero-length array.

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(jakarta.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 Jakarta 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 event)

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:

event - FacesEvent to be queued