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:
ActionListener
s, in the order in which they were registered.
MethodExpression
(which will cover the "actionListener" that was
set as a MethodBinding
).
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
COMPONENT_FAMILY
The standard component family for this component.
|
static java.lang.String |
COMPONENT_TYPE
The standard component type for this component.
|
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 and Description |
---|
UICommand()
Create a new
UICommand instance with default property values. |
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. |
java.lang.String |
getFamily()
Return the identifier of the component family to which this component belongs. |
java.lang.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 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(java.lang.Object value)
Sets the
value property of the UICommand . |
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
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
public static final java.lang.String COMPONENT_TYPE
The standard component type for this component.
public static final java.lang.String COMPONENT_FAMILY
The standard component family for this component.
public UICommand()
Create a new UICommand
instance with default property values.
public java.lang.String getFamily()
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
getFamily
in class UIComponent
public boolean isImmediate()
The immediate flag.
isImmediate
in interface ActionSource
true
if immediate, false
otherwise.public void setImmediate(boolean immediate)
ActionSource
Set the "immediate execution" flag for this UIComponent
.
setImmediate
in interface ActionSource
immediate
- The new immediate execution flagpublic java.lang.Object getValue()
Returns the value
property of the UICommand
. This is most often
rendered as a label.
public void setValue(java.lang.Object value)
Sets the value
property of the UICommand
. This is most often
rendered as a label.
value
- the new valuepublic MethodExpression getActionExpression()
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.
getActionExpression
in interface ActionSource2
public void setActionExpression(MethodExpression actionExpression)
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.
setActionExpression
in interface ActionSource2
actionExpression
- The new method expressionpublic void addActionListener(ActionListener listener)
ActionSource
Add a new ActionListener
to the set of listeners interested in being notified when
ActionEvent
s occur.
addActionListener
in interface ActionSource
listener
- The ActionListener
to be addedjava.lang.NullPointerException
- if listener
is null
public ActionListener[] getActionListeners()
ActionSource
Return the set of registered ActionListener
s for this ActionSource
instance.
If there are no registered listeners, a zero-length array is returned.
getActionListeners
in interface ActionSource
public void removeActionListener(ActionListener listener)
ActionSource
Remove an existing ActionListener
(if any) from the set of listeners interested in
being notified when ActionEvent
s occur.
removeActionListener
in interface ActionSource
listener
- The ActionListener
to be removedjava.lang.NullPointerException
- if listener
is null
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
.
broadcast
in class UIComponentBase
event
- FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Server Faces implementation that no further
processing on the current event should be performedjava.lang.IllegalArgumentException
- if the implementation class of this FacesEvent
is
not supported by this componentjava.lang.NullPointerException
- if event
is null
public void queueEvent(FacesEvent event)
Intercept queueEvent
and take the following action. If the event is an
, obtain the ActionEvent
UIComponent
instance from the
event. If the component is an
obtain the value of its
"immediate" property. If it is true, mark the phaseId for the event to be
ActionSource
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.
queueEvent
in class UIComponentBase
event
- FacesEvent
to be queuedpublic MethodBinding getAction()
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.
getAction
in interface ActionSource
public void setAction(MethodBinding action)
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.
setAction
in interface ActionSource
action
- The new MethodBinding expressionpublic MethodBinding getActionListener()
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.
getActionListener
in interface ActionSource
public void setActionListener(MethodBinding actionListener)
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
.
setActionListener
in interface ActionSource
actionListener
- The new method binding expression