javax.faces.component
Class UICommand

java.lang.Object
  javax.faces.component.UIComponentBase
      javax.faces.component.UICommand

All Implemented Interfaces:

java.io.Serializable, UIComponent

public class UICommand

extends UIComponentBase

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.

By default, the rendererType property is set to "Button". This value can be changed by calling the setRendererType() method.

See Also:

Serialized Form

Field Summary

protected java.util.List[]

listeners Array of Lists of ActionListeners registered for particular phases.

Fields inherited from interface javax.faces.component.UIComponent

SEPARATOR_CHAR

Constructor Summary

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

Method Summary

void	addActionListener(ActionListener listener) Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.
protected void	broadcast(ActionEvent event, java.util.List list) Broadcast the specified ActionEvent to the ActionListeners on the specified list (if any)
boolean	broadcast(FacesEvent event, PhaseId phaseId) Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type, for the specified PhaseId.
void	fireActionEvent(FacesContext context) Queue an ActionEvent for processing during the next event processing cycle.
java.lang.String	getAction() Return the literal action outcome value to be returned to the ActionListener processing application level events for this application.
java.lang.String	getActionRef() Return the action reference expression pointing at the Action to be invoked, if this component is activated by the user, during Invoke Application phase of the request processing lifecycle.
java.lang.String	getCommandName() Return the command name for this UICommand.
void	removeActionListener(ActionListener listener) Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.
void	setAction(java.lang.String action) Set the literal action outcome value for this component.
void	setActionRef(java.lang.String actionRef) Set the action reference expression pointing at the Action to be invoked, if this component is activated by the user, during Invoke Application phase of the request processing lifecycle.
void	setCommandName(java.lang.String commandName) Set the command name for this UICommand.
void	updateModel(FacesContext context) Override the default behavior and perform no model update.

Methods inherited from class javax.faces.component.UIComponentBase

addChild, addChild, addFacet, addValidator, clearChildren, clearFacets, clearValidators, containsChild, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttribute, getAttributeNames, getChild, getChildCount, getChildren, getClientId, getComponentId, getConverter, getFacet, getFacetNames, getFacetsAndChildren, getParent, getRendererType, getRendersChildren, getRendersSelf, getValidators, isRendered, isValid, processDecodes, processReconstitutes, processUpdates, processValidators, reconstitute, removeChild, removeChild, removeFacet, removeValidator, setAttribute, setComponentId, setConverter, setParent, setRendered, setRendererType, setValid, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

listeners

protected java.util.List[] listeners

Array of Lists of ActionListeners registered for particular phases. The array, as well as the individual elements, are lazily instantiated as necessary.

Constructor Detail

UICommand

public UICommand()

Create a new UICommand instance with default property values.

Method Detail

getAction

public java.lang.String getAction()

Return the literal action outcome value to be returned to the ActionListener processing application level events for this application.

setAction

public void setAction(java.lang.String action)

Set the literal action outcome value for this component.

Parameters:

action - The new outcome value

getActionRef

public java.lang.String getActionRef()

Return the action reference expression pointing at the Action to be invoked, if this component is activated by the user, during Invoke Application phase of the request processing lifecycle.

setActionRef

public void setActionRef(java.lang.String actionRef)

Set the action reference expression pointing at the Action to be invoked, if this component is activated by the user, during Invoke Application phase of the request processing lifecycle.

Parameters:

actionRef - The new action reference

getCommandName

public java.lang.String getCommandName()

Return the command name for this UICommand.

setCommandName

public void setCommandName(java.lang.String commandName)

Set the command name for this UICommand.

Parameters:

commandName - The new command name

updateModel

public void updateModel(FacesContext context)

Override the default behavior and perform no model update.

Specified by:

updateModel in interface UIComponent

Overrides:

updateModel in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

java.lang.IllegalArgumentException - if the modelReference property has invalid syntax for an expression

java.lang.NullPointerException - if context is null

addActionListener

public void addActionListener(ActionListener listener)

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

Parameters:

listener - The ActionListener to be added

Throws:

java.lang.NullPointerException - if listener is null

broadcast

public boolean broadcast(FacesEvent event,
                         PhaseId phaseId)
                  throws AbortProcessingException

Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type, for the specified PhaseId. The order in which registered listeners are notified is implementation dependent.

After all interested listeners have been notified, return false if this event does not have any listeners interested in this event in future phases of the request processing lifecycle. Otherwise, return true.

Specified by:

broadcast in interface UIComponent

Overrides:

broadcast in class UIComponentBase

Parameters:

event - The FacesEvent to be broadcast

phaseId - The PhaseId of the current phase of the request processing lifecycle

Throws:

AbortProcessingException - Signal the JavaServer Faces implementation that no further processing on the current event should be performed

java.lang.IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component

java.lang.IllegalStateException - if PhaseId.ANY_PHASE is passed for the phase identifier

java.lang.NullPointerException - if event or phaseId is null

broadcast

protected void broadcast(ActionEvent event,
                         java.util.List list)

Broadcast the specified ActionEvent to the ActionListeners on the specified list (if any)

Parameters:

event - The ActionEvent to be broadcast

list - The list of ActionListeners, or null for no interested listeners

fireActionEvent

public void fireActionEvent(FacesContext context)

Queue an ActionEvent for processing during the next event processing cycle.

Parameters:

context - The FacesContext for the current request

removeActionListener

public void removeActionListener(ActionListener listener)

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

Parameters:

listener - The ActionListener to be removed

Throws:

java.lang.NullPointerException - if listener is null