org.jboss.seam.faces.component
Class UIViewAction

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          org.jboss.seam.faces.component.UIViewAction

All Implemented Interfaces:

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

public class UIViewAction
extends UIComponentBase
implements ActionSource2

UIViewAction is an ActionSource2 UIComponent that specifies an application-specific command (or action)--defined as an EL method expression--to be invoked during one of the JSF lifecycle phases that proceeds view rendering. This component must be declared as a child of the ViewMetadata facet of the UIViewRoot so that it gets incorporated into the JSF lifecycle on both non-faces (initial) requests and faces (postback) requests.

The purpose of this component is to provide a light-weight front-controller solution for executing code upon the loading of a JSF view to support the integration of system services, content retrieval, view management, and navigation. This functionality is especially useful for non-faces (initial) requests.

The UIViewAction component is closely tied to the UIViewParameter component. The UIViewParameter component binds a request parameter to a model property. Most of the time, this binding is used to populate the model with data that supports the method being invoked by a UIViewAction component, much like form inputs populate the model with data to support the method being invoked by a UICommand component.

When the decode() method of the UIViewAction is invoked, it will queue an ActionEvent to be broadcast to all interested listeners when the broadcast() method is invoked.

If the value of the component's immediate attribute is true, the action will be invoked during the Apply Request Values JSF lifecycle phase. Otherwise, the action will be invoked during the Invoke Application phase, the default behavior. The phase can be set explicitly in the phase attribute, which takes precedence over the immediate attribute.

The invocation of the action is normally suppressed (meaning the ActionEvent is not queued) on a faces request. It can be enabled by setting the component's onPostback attribute to true. Execution of the method can be subject to a required condition for all requests by assigning an EL value expression of expected type boolean to the component's if attribute, which must evaluate to true for the action to be invoked.

The NavigationHandler is consulted after the action is invoked to carry out the navigation case that matches the action signature and outcome. If a navigation case is matched, or the response is marked complete by the action, subsequent UIViewAction components associated with the current view are short-circuited. The lifecycle then advances appropriately.

It's important to note that the full component tree is not built before the UIViewAction components are processed on an non-faces (initial) request. Rather, the component tree only contains the ViewMetadata, an important part of the optimization of this component and what sets it apart from a PreRenderViewEvent listener.

Author:

Dan Allen, Andy Schwartz

See Also:

UIViewParameter

Field Summary

static String	COMPONENT_FAMILY The standard component family for this component.
static String	COMPONENT_TYPE The standard component type for this component.

Fields inherited from class javax.faces.component.UIComponent

BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, VIEW_LOCATION_KEY

Constructor Summary

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

Method Summary

void	addActionListener(ActionListener listener) Action listeners are not supported by the UIViewAction component.
void	broadcast(FacesEvent event) In addition to to the default UIComponent.broadcast(javax.faces.event.FacesEvent) processing, pass the ActionEvent being broadcast to the default ActionListener registered on the Application.
void	decode(FacesContext context) First, determine if the action should be invoked by evaluating this components pre-conditions.
MethodBinding	getAction() Deprecated. This has been replaced by getActionExpression().
MethodExpression	getActionExpression() Returns the action, represented as an EL method expression, to invoke.
MethodBinding	getActionListener() Action listeners are not supported by the UIViewAction component.
ActionListener[]	getActionListeners() Action listeners are not supported by the UIViewAction component.
String	getFamily()
String	getPhase() Returns the name of the phase in which the action is to be queued.
PhaseId	getPhaseId()
boolean	isIf() Returns a condition, represented as an EL value expression, that must evaluate to true for the action to be invoked.
boolean	isImmediate() Returns the value which dictates the JSF lifecycle phase in which the action is invoked.
boolean	isOnPostback() Returns a boolean value that controls whether the action is invoked during faces (postback) request.
void	removeActionListener(ActionListener listener) Action listeners are not supported by the UIViewAction component.
void	setAction(MethodBinding action) Deprecated. This has been replaced by setActionExpression(javax.el.MethodExpression).
void	setActionExpression(MethodExpression actionExpression) Sets the action, represented as an EL method expression, to invoke.
void	setActionListener(MethodBinding actionListener) Action listeners are not supported by the UIViewAction component.
void	setIf(boolean condition) Sets the condition, represented as an EL value expression, that must evaluate to true for the action to be invoked.
void	setImmediate(boolean immediate) Sets the immediate flag, which controls the JSF lifecycle in which the action is invoked.
void	setOnPostback(boolean onPostback) Set the bookean flag that controls whether the action is invoked during a faces (postback) request.
void	setPhase(String phase) Set the name of the phase in which the action is to be queued.

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, clearInitialState, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, setInView, setValueExpression, subscribeToEvent, unsubscribeFromEvent, visitTree

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 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 Detail

UIViewAction

public UIViewAction()

Create a new UIViewAction instance with default property values.

Method Detail

getFamily

public String getFamily()

Specified by:

getFamily in class UIComponent

getAction

@Deprecated
public MethodBinding getAction()

Deprecated. This has been replaced by getActionExpression().

Specified by:

getAction in interface ActionSource

setAction

@Deprecated
public void setAction(MethodBinding action)

Deprecated. This has been replaced by setActionExpression(javax.el.MethodExpression).

Specified by:

setAction in interface ActionSource

Throws:

UnsupportedOperationException - if called

getActionListener

public MethodBinding getActionListener()

Action listeners are not supported by the UIViewAction component.

Specified by:

getActionListener in interface ActionSource

Throws:

UnsupportedOperationException - if called

setActionListener

public void setActionListener(MethodBinding actionListener)

Action listeners are not supported by the UIViewAction component.

Specified by:

setActionListener in interface ActionSource

Throws:

UnsupportedOperationException - if called

isImmediate

public boolean isImmediate()

Returns the value which dictates the JSF lifecycle phase in which the action is invoked. If the value of this attribute is true, the action will be invoked in the Apply Request Values phase. If the value of this attribute is false, the default, the action will be invoked in the Invoke Application Phase.

Specified by:

isImmediate in interface ActionSource

setImmediate

public void setImmediate(boolean immediate)

Sets the immediate flag, which controls the JSF lifecycle in which the action is invoked.

Specified by:

setImmediate in interface ActionSource

getPhase

public String getPhase()

Returns the name of the phase in which the action is to be queued. Only the following phases are supported (case does not matter):

• APPLY_REQUEST_VALUES
• PROCESS_VALIDATIONS
• UPDATE_MODEL_VALUES
• INVOKE_APPLICATION

If the phase is set, it takes precedence over the immediate flag.

setPhase

public void setPhase(String phase)

Set the name of the phase in which the action is to be queued.

getPhaseId

public PhaseId getPhaseId()

addActionListener

public void addActionListener(ActionListener listener)

Action listeners are not supported by the UIViewAction component.

Specified by:

addActionListener in interface ActionSource

Throws:

UnsupportedOperationException - if called

getActionListeners

public ActionListener[] getActionListeners()

Action listeners are not supported by the UIViewAction component.

Specified by:

getActionListeners in interface ActionSource

removeActionListener

public void removeActionListener(ActionListener listener)

Action listeners are not supported by the UIViewAction component.

Specified by:

removeActionListener in interface ActionSource

Throws:

UnsupportedOperationException - if called

getActionExpression

public MethodExpression getActionExpression()

Returns the action, represented as an EL method expression, to invoke.

Specified by:

getActionExpression in interface ActionSource2

setActionExpression

public void setActionExpression(MethodExpression actionExpression)

Sets the action, represented as an EL method expression, to invoke.

Specified by:

setActionExpression in interface ActionSource2

isOnPostback

public boolean isOnPostback()

Returns a boolean value that controls whether the action is invoked during faces (postback) request. The default is false.

setOnPostback

public void setOnPostback(boolean onPostback)

Set the bookean flag that controls whether the action is invoked during a faces (postback) request.

isIf

public boolean isIf()

Returns a condition, represented as an EL value expression, that must evaluate to true for the action to be invoked.

setIf

public void setIf(boolean condition)

Sets the condition, represented as an EL value expression, that must evaluate to true for the action to be invoked.

broadcast

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

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

NullPointerException - if event is null

decode

public void decode(FacesContext context)

First, determine if the action should be invoked by evaluating this components pre-conditions. If this is a faces (postback) request and the evaluated value of the postback attribute is false, take no action. If the evaluated value of the if attribute is false, take no action. If both conditions pass, proceed with creating an ActionEvent.

Set the phaseId in which the queued ActionEvent should be broadcast by assigning the appropriate value to the phaseId property of the ActionEvent according to the evaluated value of the immediate attribute. If the value is true, set the phaseId to PhaseId.APPLY_REQUEST_VALUES. Otherwise, set the phaseId to to PhaseId.INVOKE_APPLICATION.

Finally, queue the event by calling queueEvent() and passing the ActionEvent just created.

Overrides:

decode in class UIComponentBase