SeamFramework.orgCommunity Documentation

Chapter 41. Faces Events Propagation

41.1. JSF Phase events
41.1.1. Seam Faces Phase events
41.1.2. Phase events listing
41.2. JSF system events
41.2.1. Seam Faces System events
41.2.2. System events listing
41.2.3. Component system events

When the seam-faces module is installed in a web application, JSF events will automatically be propagated via the CDI event-bridge, enabling managed beans to easily observe all Faces events.

There are two categories of events: JSF phase events, and JSF system events. Phase events are triggered as JSF processes each lifecycle phase, while system events are raised at more specific, fine-grained events during request processing.

A JSF phase listener is a class that implements javax.faces.event.PhaseListener and is registered in the web application's faces-config.xml file. By implementing the methods of the interfaces, the user can observe events fired before or after any of the six lifecycle phases of a JSF request: restore view, apply request values, process validations, update model values, invoke application or render view.

What Seam provides is propagation of these Phase events to the CDI event bus; therefore, you can observe events using normal CDI @Observes methods. Bringing the events to CDI beans removes the need to register phase listener classes via XML, and gives the added benefit of injection, alternatives, interceptors and access to all other features of CDI.

Creating an observer method in CDI is simple; just provide a method in a managed bean that is annotated with @Observes. Each observer method must accept at least one method parameter: the event object; the type of this object determines the type of event being observed. Additional parameters may also be specified, and their values will be automatically injected by the container as per the CDI specification.

In this case, the event object passed along from the phase listener is a javax.faces.event.PhaseEvent. The following example observes all Phase events.

public void observeAll(@Observes PhaseEvent e)
    // Do something with the event object

Events can be further filtered by adding Qualifiers. The name of the method itself is not significant. (See the CDI Reference Guide for more information on events and observing.)

Since the example above simply processes all events, however, it might be appropriate to filter out some events that we aren't interested in. As stated earlier, there are six phases in the JSF lifecycle, and an event is fired before and after each, for a total of 12 events. The @Before and @After "temporal" qualifiers can be used to observe events occurring only before or only after a Phase event. For example:

public void observeBefore(@Observes @Before PhaseEvent e)
    // Do something with the "before" event object
public void observeAfter(@Observes @After PhaseEvent e)
    // Do something with the "after" event object

If we are interested in both the "before" and "after" event of a particular phase, we can limit them by adding a "lifecycle" qualifier that corresponds to the phase:

public void observeRenderResponse(@Observes @RenderResponse PhaseEvent e)
    // Do something with the "render response" event object

By combining a temporal and lifecycle qualifier, we can achieve the most specific qualification:

public void observeBeforeRenderResponse(@Observes @Before @RenderResponse PhaseEvent e)
    // Do something with the "before render response" event object

This is the full list of temporal and lifecycle qualifiers

@BeforetemporalQualifies events before lifecycle phases
@AftertemporalQualifies events after lifecycle phases
@RestoreViewlifecycleQualifies events from the "restore view" phase
@ApplyRequestValueslifecycleQualifies events from the "apply request values" phase
@ProcessValidationslifecycleQualifies events from the "process validations" phase
@UpdateModelValueslifecycleQualifies events from the "update model values" phase
@InvokeApplicationlifecycleQualifies events from the "invoke application" phase
@RenderResponselifecycleQualifies events from the "render response" phase

The event object is always a javax.faces.event.PhaseEvent and according to the general CDI principle, filtering is tightened by adding qualifiers and loosened by omitting them.

Similar to JSF Phase Events, System Events take place when specific events occur within the JSF life-cycle. Seam Faces provides a bridge for all JSF System Events, and propagates these events to CDI.

Since all JSF system event objects are distinct, no qualifiers are needed to observe them. The following events may be observed:

Event objectContextDescription
SystemEventallAll events
ComponentSystemEventcomponentAll component events
PostAddToViewEventcomponentAfter a component was added to the view
PostConstructViewMapEventcomponentAfter a view map was created
PostRestoreStateEventcomponentAfter a component has its state restored
PostValidateEventcomponentAfter a component has been validated
PreDestroyViewMapEventcomponentBefore a view map has been restored
PreRemoveFromViewEventcomponentBefore a component has been removed from the view
PreRenderComponentEventcomponentAfter a component has been rendered
PreRenderViewEventcomponentBefore a view has been rendered
PreValidateEventcomponentBefore a component has been validated
ExceptionQueuedEventsystemWhen an exception has been queued
PostConstructApplicationEventsystemAfter the application has been constructed
PostConstructCustomScopeEventsystemAfter a custom scope has been constructed
PreDestroyApplicationEventsystemBefore the application is destroyed
PreDestroyCustomScopeEventsystemBefore a custom scope is destroyed