javax.faces.component
Class UICommand

java.lang.Object
  |
  +--javax.faces.component.UIComponent
        |
        +--javax.faces.component.UIComponentBase
              |
              +--javax.faces.component.UICommand

All Implemented Interfaces:

ActionSource, StateHolder

Direct Known Subclasses:

HtmlCommandButton, HtmlCommandLink

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" MethodBinding
3. The default ActionListener, retrieved from the Application - and therefore, any attached "action" MethodBinding.

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

Field Summary

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.

Constructor Summary

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

Method Summary

void	addActionListener(javax.faces.event.ActionListener listener) Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.
void	broadcast(javax.faces.event.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.
javax.faces.el.MethodBinding	getAction() 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.
javax.faces.el.MethodBinding	getActionListener() Return the MethodBinding pointing at an action listener method 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 upon the value of the immediate property.
javax.faces.event.ActionListener[]	getActionListeners() Return the set of registered ActionListeners 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() Return a flag indicating that the default ActionListener provided by the JavaServer Faces implementation should be executed immediately (that is, during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase.
void	queueEvent(javax.faces.event.FacesEvent e) Intercept queueEvent and, for ActionEvents, mark the phaseId for the event to be PhaseId.APPLY_REQUEST_VALUES if the immediate flag is true, PhaseId.INVOKE_APPLICATION otherwise.
void	removeActionListener(javax.faces.event.ActionListener listener) Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.
void	restoreState(javax.faces.context.FacesContext context, java.lang.Object state) Perform any processing required to restore the state from the entries in the state Object.
java.lang.Object	saveState(javax.faces.context.FacesContext context) Gets the state of the instance as a Serializable Object.
void	setAction(javax.faces.el.MethodBinding action) 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.
void	setActionListener(javax.faces.el.MethodBinding actionListener) Set the MethodBinding pointing at an action listener method 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 upon the value of the immmediate property.
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.

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, isRendered, isTransient, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class java.lang.Object

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

Field Detail

COMPONENT_TYPE

public static final java.lang.String COMPONENT_TYPE

The standard component type for this component.

See Also:

Constant Field Values

COMPONENT_FAMILY

public static final java.lang.String COMPONENT_FAMILY

The standard component family for this component.

See Also:

Constant Field Values

Constructor Detail

UICommand

public UICommand()

Create a new UICommand instance with default property values.

Method Detail

getFamily

public java.lang.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.

Specified by:

getFamily in class UIComponent

getAction

public javax.faces.el.MethodBinding getAction()

Description copied from interface: ActionSource

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.

Specified by:

getAction in interface ActionSource

setAction

public void setAction(javax.faces.el.MethodBinding action)

Description copied from interface: ActionSource

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.

Specified by:

setAction in interface ActionSource

Parameters:

action - The new MethodBinding expression

getActionListener

public javax.faces.el.MethodBinding getActionListener()

Description copied from interface: ActionSource

Return the MethodBinding pointing at an action listener method 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 upon the value of the immediate property.

Specified by:

getActionListener in interface ActionSource

setActionListener

public void setActionListener(javax.faces.el.MethodBinding actionListener)

Description copied from interface: ActionSource

Set the MethodBinding pointing at an action listener method 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 upon the value of the immmediate property.

Any method referenced by such an expression must be public, with a return type of void, and accept a single parameter of type ActionEvent.

Specified by:

setActionListener in interface ActionSource

Parameters:

actionListener - The new method binding expression

isImmediate

public boolean isImmediate()

Description copied from interface: ActionSource

Return a flag indicating that the default ActionListener provided by the JavaServer Faces implementation should be executed immediately (that is, during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase. The default value for this property must be false.

Specified by:

isImmediate in interface ActionSource

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 java.lang.Object getValue()

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

setValue

public void setValue(java.lang.Object value)

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

Parameters:

value - the new value

addActionListener

public void addActionListener(javax.faces.event.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:

java.lang.NullPointerException - if listener is null

getActionListeners

public javax.faces.event.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

removeActionListener

public void removeActionListener(javax.faces.event.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:

java.lang.NullPointerException - if listener is null

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext context)

Description copied from interface: StateHolder

Gets the state of the instance as a Serializable Object.

If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(javax.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

This method must not alter the state of the implementing object. In other words, after executing this code:

 Object state = component.saveState(facesContext);
 

component should be the same as before executing it.

The return from this method must be Serializable

Specified by:

saveState in interface StateHolder

Overrides:

saveState in class UIComponentBase

restoreState

public void restoreState(javax.faces.context.FacesContext context,
                         java.lang.Object state)

Description copied from interface: StateHolder

Perform any processing required to restore the state from the entries in the state Object.

If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object) method on all those instances as well.

Specified by:

restoreState in interface StateHolder

Overrides:

restoreState in class UIComponentBase

broadcast

public void broadcast(javax.faces.event.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.

Overrides:

broadcast in class UIComponentBase

Parameters:

event - FacesEvent to be broadcast

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.NullPointerException - if event is null

queueEvent

public void queueEvent(javax.faces.event.FacesEvent e)

Intercept queueEvent and, for ActionEvents, mark the phaseId for the event to be PhaseId.APPLY_REQUEST_VALUES if the immediate flag is true, PhaseId.INVOKE_APPLICATION otherwise.

Overrides:

queueEvent in class UIComponentBase