Class UICommand
- All Implemented Interfaces:
EventListener
,ActionSource
,ActionSource2
,PartialStateHolder
,StateHolder
,TransientStateHolder
,ComponentSystemEventListener
,FacesListener
,SystemEventListenerHolder
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.- The "actionListener"
MethodExpression
(which will cover the "actionListener" that was set as aMethodBinding
). - The default
ActionListener
, retrieved from theApplication
- 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
Modifier and TypeFieldDescriptionstatic final String
The standard component family for this component.static final String
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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addActionListener
(ActionListener listener) Add a newActionListener
to the set of listeners interested in being notified whenActionEvent
s occur.void
broadcast
(FacesEvent event) In addition to to the defaultUIComponent.broadcast(javax.faces.event.FacesEvent)
processing, pass theActionEvent
being broadcast to the method referenced byactionListener
(if any), and to the defaultActionListener
registered on theApplication
.Deprecated.Return theMethodExpression
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.Deprecated.UsegetActionListeners()
instead.Return the set of registeredActionListener
s for thisActionSource
instance.Return the identifier of the component family to which this component belongs.getValue()
Returns thevalue
property of theUICommand
.boolean
The immediate flag.void
InterceptqueueEvent
and take the following action.void
removeActionListener
(ActionListener listener) Remove an existingActionListener
(if any) from the set of listeners interested in being notified whenActionEvent
s occur.void
setAction
(MethodBinding action) Deprecated.This has been replaced bysetActionExpression(javax.el.MethodExpression)
.void
setActionExpression
(MethodExpression actionExpression) Set theMethodExpression
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.void
setActionListener
(MethodBinding actionListener) Deprecated.This has been replaced byaddActionListener(javax.faces.event.ActionListener)
.void
setImmediate
(boolean immediate) Set the "immediate execution" flag for thisUIComponent
.void
Sets thevalue
property of theUICommand
.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
-
Field Details
-
COMPONENT_TYPE
The standard component type for this component.
- See Also:
-
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
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 appropriateRenderer
for this component instance.- Specified by:
getFamily
in classUIComponent
-
getAction
Deprecated.This has been replaced bygetActionExpression()
.If the implementing class also implements
ActionSource2
, the implementation of this method must call through toActionSource2.getActionExpression()
and examine the result. If the result came from a previous call toActionSource.setAction(javax.faces.el.MethodBinding)
, extract theMethodBinding
from it and return it. Otherwise, wrap the returnedMethodExpression
in aMethodBinding
implementation, and return it.If the implementing class does not implement
ActionSource2
, return theMethodBinding
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.- Specified by:
getAction
in interfaceActionSource
-
setAction
Deprecated.This has been replaced bysetActionExpression(javax.el.MethodExpression)
.If the implementing class also implements
ActionSource2
, the implementation of this method must wrap the argumentaction
in a class that implementsMethodExpression
and call through toActionSource2.setActionExpression(javax.el.MethodExpression)
, passing the wrappedaction
.If the implementing class does not implement
ActionSource2
, set theMethodBinding
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
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 interfaceActionSource
- Parameters:
action
- The new MethodBinding expression
-
getActionListener
Deprecated.UsegetActionListeners()
instead.If
ActionSource.setActionListener(javax.faces.el.MethodBinding)
was not previously called for this instance, this method must returnnull
. If it was called, this method must return the exactMethodBinding
instance that was passed toActionSource.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 theimmediate
property.- Specified by:
getActionListener
in interfaceActionSource
-
setActionListener
Deprecated.This has been replaced byaddActionListener(javax.faces.event.ActionListener)
.Wrap the argument
actionListener
in an implementation ofActionListener
and store it in the internal data structure that backs theActionSource.getActionListeners()
method, taking care to over-write any instance that was stored by a previous call tosetActionListener
.Any method referenced by such an expression must be public, with a return type of
void
, and accept a single parameter of typeActionEvent
.- Specified by:
setActionListener
in interfaceActionSource
- Parameters:
actionListener
- The new method binding expression
-
isImmediate
public boolean isImmediate()The immediate flag.
- Specified by:
isImmediate
in interfaceActionSource
-
setImmediate
public void setImmediate(boolean immediate) Description copied from interface:ActionSource
Set the "immediate execution" flag for this
UIComponent
.- Specified by:
setImmediate
in interfaceActionSource
- Parameters:
immediate
- The new immediate execution flag
-
getValue
Returns the
value
property of theUICommand
. This is most often rendered as a label. -
setValue
Sets the
value
property of theUICommand
. This is most often rendered as a label.- Parameters:
value
- the new value
-
getActionExpression
Description copied from interface:ActionSource2
Return the
MethodExpression
pointing at the application action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
property.Note that it's possible that the returned
MethodExpression
is just a wrapper around aMethodBinding
instance whith was set by a call toActionSource.setAction(javax.faces.el.MethodBinding)
. This makes it possible for the defaultActionListener
to continue to work properly with older components.- Specified by:
getActionExpression
in interfaceActionSource2
-
setActionExpression
Description copied from interface:ActionSource2
Set the
MethodExpression
pointing at the appication action to be invoked, if thisUIComponent
is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of theimmediate
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 interfaceActionSource2
- Parameters:
actionExpression
- The new method expression
-
addActionListener
Description copied from interface:ActionSource
Add a new
ActionListener
to the set of listeners interested in being notified whenActionEvent
s occur.- Specified by:
addActionListener
in interfaceActionSource
- Parameters:
listener
- TheActionListener
to be added- Throws:
NullPointerException
- iflistener
isnull
-
getActionListeners
Description copied from interface:ActionSource
Return the set of registered
ActionListener
s for thisActionSource
instance. If there are no registered listeners, a zero-length array is returned.- Specified by:
getActionListeners
in interfaceActionSource
-
removeActionListener
Description copied from interface:ActionSource
Remove an existing
ActionListener
(if any) from the set of listeners interested in being notified whenActionEvent
s occur.- Specified by:
removeActionListener
in interfaceActionSource
- Parameters:
listener
- TheActionListener
to be removed- Throws:
NullPointerException
- iflistener
isnull
-
broadcast
In addition to to the default
UIComponent.broadcast(javax.faces.event.FacesEvent)
processing, pass theActionEvent
being broadcast to the method referenced byactionListener
(if any), and to the defaultActionListener
registered on theApplication
.- Overrides:
broadcast
in classUIComponentBase
- Parameters:
event
-FacesEvent
to be broadcast- Throws:
AbortProcessingException
- Signal the JavaServer Faces implementation that no further processing on the current event should be performedIllegalArgumentException
- if the implementation class of thisFacesEvent
is not supported by this componentNullPointerException
- ifevent
isnull
-
queueEvent
Intercept
queueEvent
and take the following action. If the event is an
, obtain theActionEvent
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 beActionSource
PhaseId.APPLY_REQUEST_VALUES
otherwise, mark the phaseId to bePhaseId.INVOKE_APPLICATION
. The event must be passed on tosuper.queueEvent()
before returning from this method.- Overrides:
queueEvent
in classUIComponentBase
- Parameters:
e
-FacesEvent
to be queued
-
getActionExpression()
.