[seam-commits] Seam SVN: r12548 - in modules/faces/trunk: examples/short-ly and 1 other directories.

Author: lincolnthree Date: 2010-04-21 14:32:06 -0400 (Wed, 21 Apr 2010) New Revision: 12548 Modified: modules/faces/trunk/docs/reference/src/main/docbook/en-US/author_group.xml modules/faces/trunk/docs/reference/src/main/docbook/en-US/events.xml modules/faces/trunk/docs/reference/src/main/docbook/en-US/installation.xml modules/faces/trunk/examples/short-ly/pom.xml modules/faces/trunk/examples/short-ly/src/main/webapp/META-INF/MANIFEST.MF Log: Fixed broken example build (example still not functional) Documentation updates Modified: modules/faces/trunk/docs/reference/src/main/docbook/en-US/author_group.xml =================================================================== --- modules/faces/trunk/docs/reference/src/main/docbook/en-US/author_group.xml 2010-04-21 16:41:56 UTC (rev 12547) +++ modules/faces/trunk/docs/reference/src/main/docbook/en-US/author_group.xml 2010-04-21 18:32:06 UTC (rev 12548) @@ -10,6 +10,10 @@ <firstname>Lincoln</firstname> <surname>Baxter III</surname> </author> + <author> + <firstname>Nicklas</firstname> + <surname>Karlsson</surname> + </author> <!-- vim:et:ts=3:sw=3:tw=120 Modified: modules/faces/trunk/docs/reference/src/main/docbook/en-US/events.xml =================================================================== --- modules/faces/trunk/docs/reference/src/main/docbook/en-US/events.xml 2010-04-21 16:41:56 UTC (rev 12547) +++ modules/faces/trunk/docs/reference/src/main/docbook/en-US/events.xml 2010-04-21 18:32:06 UTC (rev 12548) @@ -9,47 +9,54 @@ </para> <para> There are two categories of events: JSF phase events, and JSF system events. Phase events are triggered - as JSF processes HTTP requests, while system events are raised at specific events during the JSF lifecycle. + as JSF processes each lifecycle phase, while system events are raised at more specific, fine-grained events during + request processing. </para> <section id="events.phases"> - <title>JSF phases events</title> + <title>JSF Phase events</title> + <para> - A JSF phase listener is a class that implements the <literal>javax.faces.event.PhaseListener</literal> and - is registered in the web applications <literal>faces-config.xml</literal>. By implementing the methods of the + A JSF phase listener is a class that implements <literal>javax.faces.event.PhaseListener</literal> and + is registered in the web application's <literal>faces-config.xml</literal> 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: <literal>restore view</literal>, <literal>apply request values</literal>, <literal>process validations</literal>, <literal>update model values</literal>, <literal>invoke application</literal> or <literal>render view</literal>. </para> - <para> - Instead of registering your own phase listener, you can use the seam-faces module to have the events propagated - to the CDI event bus where they can be observed using the normal CDI <literal>@Observes</literal> methods. Bringing - the events to your beans saves you the trouble of registering your own phase listeners and gives you the added - benfit of injection, alternatives, interceptors and other features of CDI you already have available in your beans! - </para> - <para> - CDI observation works by providing a method in a managed bean that has a method parameter annotated - <literal>@Observes</literal>. This method parameter is the event object passed along when firing the event and - can be further narrowed down by adding qualifiers. The naming of the method itself is not significant. - See the Seam Reference Guide for more information on events and observing. - </para> - <para> - The event object passed along from the phase listener is a <literal>javax.faces.event.PhaseEvent</literal>. So if - you would like to observe the full spectrum of events propagated you would write the following method in your - observer bean - <programlisting role="Java"> + + <section id="events.phases.seam"> + <title>Seam Faces Phase events</title> + <para> + What Seam provides is propagation of these Phase events to the CDI event bus; therefore, you can observe events + using normal CDI <literal>@Observes</literal> 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. + </para> + <para> + Creating an observer method in CDI is simple; just provide a method in a managed bean that is annotated with + <literal>@Observes</literal>. Each observer method must accept one method parameter: the event object; + the type of this object determines the type of event being observed. + </para> + <para> + In this case, the event object passed along from the phase listener is a + <literal>javax.faces.event.PhaseEvent</literal>. The following example observes all Phase events. + + <programlisting role="Java"> public void observeAll(@Observes PhaseEvent e) { // Do something with the event object } </programlisting> - </para> - <para> - Since the example above flushes you with a lot of events you have to sort out yourself, you might want to - consider flitering them out a bit. We mentioned that there are six phases in the JSF lifecycle and each of - these phases fire one event before executing and one after. This will result in 12 events fired, six - "before" and six "after" events which have their corresponding temportal qualifiers <literal>@Before</literal> and - <literal>@After</literal>. In order to split out the events into these categories, you would write two - observer methods like - <programlisting role="Java"> + </para> + <para> + 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.) + </para> + <para> + 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 <literal>@Before</literal> and + <literal>@After</literal> "temporal" qualifiers can be used to observe events occurring only before or only after + a Phase event. For example: + <programlisting role="Java"> public void observeBefore(@Observes @Before PhaseEvent e) { // Do something with the "before" event object @@ -59,210 +66,250 @@ { // Do something with the "after" event object } </programlisting> - </para> - <para> - If you are interested in both the "before" and "after" event of a particular phase, you can limit them - by adding a lifecycle qualifer that corresponds to the phase: - <programlisting role="Java"> + </para> + <para> + 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: + <programlisting role="Java"> public void observeRenderResponse(@Observes @RenderResponse PhaseEvent e) { // Do something with the "render response" event object } </programlisting> - </para> - <para> - By combining a temporal qualifier with a lifecycel one you can achieve the tightest qualification: - <programlisting role="Java"> + </para> + <para> + By combining a temporal and lifecycle qualifier, we can achieve the most specific qualification: + <programlisting role="Java"> public void observeBeforeRenderResponse(@Observes @Before @RenderResponse PhaseEvent e) { // Do something with the "before render response" event object } </programlisting> - </para> - <para> - This is the full list of temporal and lifecycle qualifers - <informaltable> - <tgroup cols="3"> - <colspec colnum="1" colwidth="1*" /> - <colspec colnum="2" colwidth="1*" /> - <colspec colnum="3" colwidth="3*" /> - <thead> - <row> - <entry>Qualifier</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>@Before</entry> - <entry>temporal</entry> - <entry>Qualifies events before lifecycle phases</entry> - </row> - <row> - <entry>@After</entry> - <entry>temporal</entry> - <entry>Qualifies events after lifecycle phases</entry> - </row> - <row> - <entry>@RestoreView</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "restore view" phase</entry> - </row> - <row> - <entry>@ApplyRequestValues</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "apply request values" phase</entry> - </row> - <row> - <entry>@ProcessValidations</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "process validations" phase</entry> - </row> - <row> - <entry>@UpdateModelValues</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "update model values" phase</entry> - </row> - <row> - <entry>@InvokeApplication</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "invoke application" phase</entry> - </row> - <row> - <entry>@RenderResponse</entry> - <entry>lifecycle</entry> - <entry>Qualifies events from the "render response" phase</entry> - </row> - </tbody> - </tgroup> - </informaltable> - The event object is always a <literal>javax.faces.event.PhaseEvent</literal> and according to the general - CDI principle, filtering is tightened by adding qualifiers and loosened by omitting them. - </para> + </para> + </section> + + + <section id="events.phases.seam.table"> + <title>Phase events listing</title> + <para> + This is the full list of temporal and lifecycle qualifiers + <informaltable> + <tgroup cols="3"> + <colspec colnum="1" colwidth="1*" /> + <colspec colnum="2" colwidth="1*" /> + <colspec colnum="3" colwidth="3*" /> + <thead> + <row> + <entry>Qualifier</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>@Before</entry> + <entry>temporal</entry> + <entry>Qualifies events before lifecycle phases</entry> + </row> + <row> + <entry>@After</entry> + <entry>temporal</entry> + <entry>Qualifies events after lifecycle phases</entry> + </row> + <row> + <entry>@RestoreView</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "restore view" phase</entry> + </row> + <row> + <entry>@ApplyRequestValues</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "apply request values" phase</entry> + </row> + <row> + <entry>@ProcessValidations</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "process validations" phase</entry> + </row> + <row> + <entry>@UpdateModelValues</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "update model values" phase</entry> + </row> + <row> + <entry>@InvokeApplication</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "invoke application" phase</entry> + </row> + <row> + <entry>@RenderResponse</entry> + <entry>lifecycle</entry> + <entry>Qualifies events from the "render response" phase</entry> + </row> + </tbody> + </tgroup> + </informaltable> + The event object is always a <literal>javax.faces.event.PhaseEvent</literal> and according to the general + CDI principle, filtering is tightened by adding qualifiers and loosened by omitting them. + </para> + </section> </section> + + + <section id="events.system"> <title>JSF system events</title> <para> - JSF 2.0 brings along system events and seam-faces provides a CDI bridge which allows you to observe them. - Since all JSF system event objects are distinct, no qualifiers are needed to observe them, all the CDI bridge - does it pass them along + 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. </para> - <para> - Here is the complete list of event objects available for observation - <informaltable> - <tgroup cols="3"> - <colspec colnum="1" colwidth="3*" /> - <colspec colnum="2" colwidth="1*" /> - <colspec colnum="3" colwidth="4*" /> - <thead> - <row> - <entry>Event object</entry> - <entry>Context</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>SystemEvent</entry> - <entry>all</entry> - <entry>All events</entry> - </row> - <row> - <entry>ComponentSystemEvent</entry> - <entry>component</entry> - <entry>All component events</entry> - </row> - <row> - <entry>PostAddToViewEvent</entry> - <entry>component</entry> - <entry>After a component was added to the view</entry> - </row> - <row> - <entry>PostConstructViewMapEvent</entry> - <entry>view</entry> - <entry>After a view map was created</entry> - </row> - <row> - <entry>PostRestoreStateEvent</entry> - <entry>component</entry> - <entry>After a component has its state restored</entry> - </row> - <row> - <entry>PostValidateEvent</entry> - <entry>component</entry> - <entry>After a component has been validated</entry> - </row> - <row> - <entry>PreDestroyViewMapEvent</entry> - <entry>view</entry> - <entry>Before a view map has been restored</entry> - </row> - <row> - <entry>PreRemoveFromViewEvent</entry> - <entry>component</entry> - <entry>Before a component has been removed from the view</entry> - </row> - <row> - <entry>PreRenderComponentEvent</entry> - <entry>component</entry> - <entry>After a component has been rendered</entry> - </row> - <row> - <entry>PreRenderViewEvent</entry> - <entry>view</entry> - <entry>Before a view has been rendered</entry> - </row> - <row> - <entry>PreValidateEvent</entry> - <entry>component</entry> - <entry>Before a component has been validated</entry> - </row> - <row> - <entry>ExceptionQueuedEvent</entry> - <entry>system</entry> - <entry>When an exception has been queued</entry> - </row> - <row> - <entry>PostConstructApplicationEvent</entry> - <entry>system</entry> - <entry>After the application has been constructed</entry> - </row> - <row> - <entry>PostConstructCustomScopeEvent</entry> - <entry>system</entry> - <entry>After a custom scope has been constructed</entry> - </row> - <row> - <entry>PreDestroyApplicationEvent</entry> - <entry>system</entry> - <entry>Before the application is destroyed</entry> - </row> - <row> - <entry>PreDestroyCustomScopeEvent</entry> - <entry>system</entry> - <entry>Before a custom scope is destroyed</entry> - </row> - </tbody> - </tgroup> - </informaltable> - Component events can further be qualified with the <literal>@Component</literal> qualifer, which takes the component id - as the value. The corresponding qualifier for view events is <literal>@View</literal>. - <programlisting role="Java"> -public void observePrePasswordValidation(@Observes @Component("form:password") PreValidateEvent e) + + + + + + <section id="events.system.seam"> + <title>Seam Faces System events</title> + <para> + This is an example of observing a Faces system event: + </para> + <para> + <programlisting role="Java"> +public void observesThisEvent(@Observes ExceptionQueuedEvent e) { - // Do something with the "before password is validated" event object + // Do something with the event object } </programlisting> - <programlisting role="Java"> -public void observePreFooViewRendered(@Observes @View("/foo.xhtml") PreRenderViewEvent e) + </para> + </section> + + + + + <section id="events.system.seam.listing"> + <title>System events listing</title> + <para> + Since all JSF system event objects are distinct, no qualifiers are needed to observe them. The following events + may be observed: + <informaltable> + <tgroup cols="3"> + <colspec colnum="1" colwidth="3*" /> + <colspec colnum="2" colwidth="1*" /> + <colspec colnum="3" colwidth="4*" /> + <thead> + <row> + <entry>Event object</entry> + <entry>Context</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>SystemEvent</entry> + <entry>all</entry> + <entry>All events</entry> + </row> + <row> + <entry>ComponentSystemEvent</entry> + <entry>component</entry> + <entry>All component events</entry> + </row> + <row> + <entry>PostAddToViewEvent</entry> + <entry>component</entry> + <entry>After a component was added to the view</entry> + </row> + <row> + <entry>PostConstructViewMapEvent</entry> + <entry>component</entry> + <entry>After a view map was created</entry> + </row> + <row> + <entry>PostRestoreStateEvent</entry> + <entry>component</entry> + <entry>After a component has its state restored</entry> + </row> + <row> + <entry>PostValidateEvent</entry> + <entry>component</entry> + <entry>After a component has been validated</entry> + </row> + <row> + <entry>PreDestroyViewMapEvent</entry> + <entry>component</entry> + <entry>Before a view map has been restored</entry> + </row> + <row> + <entry>PreRemoveFromViewEvent</entry> + <entry>component</entry> + <entry>Before a component has been removed from the view</entry> + </row> + <row> + <entry>PreRenderComponentEvent</entry> + <entry>component</entry> + <entry>After a component has been rendered</entry> + </row> + <row> + <entry>PreRenderViewEvent</entry> + <entry>component</entry> + <entry>Before a view has been rendered</entry> + </row> + <row> + <entry>PreValidateEvent</entry> + <entry>component</entry> + <entry>Before a component has been validated</entry> + </row> + <row> + <entry>ExceptionQueuedEvent</entry> + <entry>system</entry> + <entry>When an exception has been queued</entry> + </row> + <row> + <entry>PostConstructApplicationEvent</entry> + <entry>system</entry> + <entry>After the application has been constructed</entry> + </row> + <row> + <entry>PostConstructCustomScopeEvent</entry> + <entry>system</entry> + <entry>After a custom scope has been constructed</entry> + </row> + <row> + <entry>PreDestroyApplicationEvent</entry> + <entry>system</entry> + <entry>Before the application is destroyed</entry> + </row> + <row> + <entry>PreDestroyCustomScopeEvent</entry> + <entry>system</entry> + <entry>Before a custom scope is destroyed</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </section> + + + + <section id="events.system.component"> + <title>Component system events</title> + <para> + There is one qualifier, <literal>@Component</literal> that can be used with component events by specifying the component ID. Note that + view-centric component events <literal>PreRenderViewEvent</literal>, <literal>PostConstructViewMapEvent</literal> and + <literal>PreDestroyViewMapEvent</literal> do not fire with the <literal>@Component</literal> qualifier. + <programlisting role="Java"> +public void observePrePasswordValidation(@Observes @Component("form:password") PreValidateEvent e) { - // Do something with the "before view is rendered" event object +// Do something with the "before password is validated" event object } </programlisting> - Global system events are observer without the component qualifier - <programlisting role="Java"> + Global system events are observer without the component qualifier + <programlisting role="Java"> public void observeApplicationConstructed(@Observes PostConstructApplicationEvent e) { - // Do something with the "after application is constructed" event object +// Do something with the "after application is constructed" event object } </programlisting> - The name of the observing method is insignificant. - </para> + The name of the observing method is not relevant; observers are defined solely via annotations. + </para> + </section> + + </section> </chapter> \ No newline at end of file Modified: modules/faces/trunk/docs/reference/src/main/docbook/en-US/installation.xml =================================================================== --- modules/faces/trunk/docs/reference/src/main/docbook/en-US/installation.xml 2010-04-21 16:41:56 UTC (rev 12547) +++ modules/faces/trunk/docs/reference/src/main/docbook/en-US/installation.xml 2010-04-21 18:32:06 UTC (rev 12548) @@ -16,6 +16,8 @@ <tip> <para>Replace ${seam-faces-version} with the most recent or appropriate version of Seam Faces.</para> </tip> + +<!-- <section id="configuration"> <title>Configuration</title> <para> @@ -52,10 +54,11 @@ <entry>Conversation Support</entry> <entry>interceptor</entry> <entry>org.jboss.seam.faces.context.conversation.ConversationBoundaryInterceptor</entry> - </row> + </row> </tbody> </tgroup> </informaltable> </para> </section> + --> </chapter> \ No newline at end of file Modified: modules/faces/trunk/examples/short-ly/pom.xml =================================================================== --- modules/faces/trunk/examples/short-ly/pom.xml 2010-04-21 16:41:56 UTC (rev 12547) +++ modules/faces/trunk/examples/short-ly/pom.xml 2010-04-21 18:32:06 UTC (rev 12548) @@ -45,7 +45,7 @@ <dependency> <groupId>com.ocpsoft</groupId> <artifactId>ocpsoft-pretty-faces</artifactId> - <version>2.0.5-SNAPSHOT</version> + <version>2.0.4</version> </dependency> <dependency> Modified: modules/faces/trunk/examples/short-ly/src/main/webapp/META-INF/MANIFEST.MF =================================================================== --- modules/faces/trunk/examples/short-ly/src/main/webapp/META-INF/MANIFEST.MF 2010-04-21 16:41:56 UTC (rev 12547) +++ modules/faces/trunk/examples/short-ly/src/main/webapp/META-INF/MANIFEST.MF 2010-04-21 18:32:06 UTC (rev 12548) @@ -1,3 +1,2 @@ Manifest-Version: 1.0 -Class-Path: