The Java EE 5 Tutorial (PDF) - Oracle Software Downloads

User Interface Component Model
304
user activates a component, such as by clicking a button, an event is fired. This causes the
JavaServer Faces implementation to invoke the listener method that processes the event.
JavaServer Faces technology supports three kinds of events: value-change events, action events,
and data-model events.
An action event occurs when the user activates a component that implements ActionSource.
These components include buttons and hyperlinks.
A value-change event occurs when the user changes the value of a component represented by
UIInput or one of its subclasses. An example is selecting a check box, an action that results in
the component’s value changing to true. The component types that can generate these types of
events are the UIInput, UISelectOne, UISelectMany, and UISelectBoolean components.
Value-change events are fired only if no validation errors were detected.
Depending on the value of the immediate property (see “The immediate Attribute” on page 326)
of the component emitting the event, action events can be processed during the invoke
application phase or the apply request values phase, and value-change events can be processed
during the process validations phase or the apply request values phase.
A data-model event occurs when a new row of a UIData component is selected. The discussion
of data-model events is an advanced topic. It is not covered in this tutorial but may be discussed
in future versions of this tutorial.
There are two ways to cause your application to react to action events or value-change events
emitted by a standard component:
■ Implement an event listener class to handle the event and register the listener on the
component by nesting either a valueChangeListener tag or an actionListener tag inside
the component tag.
■ Implement a method of a backing bean to handle the event and refer to the method with a
method expression from the appropriate attribute of the component’s tag.
See “Implementing an Event Listener” on page 393 for information on how to implement an
event listener. See “Registering Listeners on Components” on page 357 for information on how
to register the listener on a component.
See “Writing a Method to Handle an Action Event” on page 404 and “Writing a Method to
Handle a Value-Change Event” on page 405 for information on how to implement backing bean
methods that handle these events.
See “Referencing a Backing Bean Method” on page 368 for information on how to refer to the
backing bean method from the component tag.
When emitting events from custom components, you must implement the appropriate Event
class and manually queue the event on the component in addition to implementing an event
listener class or a backing bean method that handles the event. “Handling Events for Custom
Components” on page 427 explains how to do this.
The Java EE 5Tutorial • June 2010