[jboss-cvs] JBossAS SVN: r105536 - projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Jun 1 23:27:24 EDT 2010
Author: misty at redhat.com
Date: 2010-06-01 23:27:24 -0400 (Tue, 01 Jun 2010)
New Revision: 105536
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Events.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Events.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Events.xml 2010-06-02 03:15:24 UTC (rev 105535)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Events.xml 2010-06-02 03:27:24 UTC (rev 105536)
@@ -46,13 +46,13 @@
Each of these events is mapped to Seam components with JSF EL method-binding expressions. For a JSF event, this is defined in the JSF template:
</para>
-<programlisting role="XHTML"><![CDATA[<h:commandButton value="Click me!" action="#{helloWorld.sayHello}"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<h:commandButton value="Click me!" action="#{helloWorld.sayHello}"/>]]>
</programlisting>
<para>
For a jBPM transition event, it is specified in the jBPM process definition or pageflow definition:
</para>
-<programlisting role="XML"><![CDATA[<start-page name="hello" view-id="/hello.jsp">
+<programlisting language="XML" role="XML"><![CDATA[<start-page name="hello" view-id="/hello.jsp">
<transition to="hello">
<action expression="#{helloWorld.sayHello}"/>
</transition>
@@ -69,7 +69,7 @@
A Seam page action is an event occurring immediately before a page is rendered. Declare page actions in <filename>WEB-INF/pages.xml</filename>. We can define a page action for a particular JSF view ID:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/hello.jsp" action="#{helloWorld.sayHello}"/>
</pages>]]>
</programlisting>
@@ -77,7 +77,7 @@
Or we can use a <literal>*</literal> wildcard as a suffix to the <literal>view-id</literal> to specify an action that applies to all view IDs that match that pattern:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/hello/*" action="#{helloWorld.sayHello}"/>
</pages>]]>
</programlisting>
@@ -99,7 +99,7 @@
Multiple or conditional page actions can be specified with the <literal><![CDATA[<action>]]></literal> tag:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/hello.jsp">
<action execute="#{helloWorld.sayHello}"
if="#{not validation.failed}"/>
@@ -111,7 +111,7 @@
Page actions are executed on both an initial (non-Faces) request and a postback (Faces) request. If you use the page action to load data, it may conflict with the standard JSF actions being executed on a postback. One way to disable the page action is to set up a condition that resolves to <literal>true</literal> only upon an initial request.
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/dashboard.xhtml">
<action execute="#{dashboard.loadData}"
if="#{not FacesContext.renderKit.responseStateManager
@@ -126,7 +126,7 @@
Seam offers a built-in condition that accomplishes this result less verbosely. You can disable a page action on a postback by setting the <literal>on-postback</literal> attribute to <literal>false</literal>:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/dashboard.xhtml">
<action execute="#{dashboard.loadData}" on-postback="false"/>
</page>
@@ -154,7 +154,7 @@
Seam lets us provide a value binding that maps a named request parameter to an attribute of a model object.
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
<param name="firstName" value="#{person.firstName}"/>
<param name="lastName" value="#{person.lastName}"/>
@@ -199,7 +199,7 @@
If only the <literal>name</literal> attribute is specified, the request parameter is propagated with the <literal>PAGE</literal> context (that is, it is not mapped to model property).
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
<param name="firstName" />
<param name="lastName" />
@@ -232,7 +232,7 @@
Rewriting occurs based on patterns found for views in <filename>pages.xml</filename>. Seam URL rewriting performs both incoming and outgoing URL rewriting based on the same pattern. A simple pattern for this process is:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/home.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/home.xhtml">
<rewrite pattern="/home" />
</page> ]]>
</programlisting>
@@ -243,7 +243,7 @@
Rewrite rules can take query paramters into consideration, as shown with the following rules.
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/home.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/home.xhtml">
<rewrite pattern="/home/{color}" />
<rewrite pattern="/home" />
</page> ]]>
@@ -255,7 +255,7 @@
Default Seam query parameters can also be mapped with URL rewriting, further concealing Seam's fingerprints. In the following example, <literal>/search.seam?conversationId=13</literal> would be written as <literal>/search-13</literal>.
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/search.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/search.xhtml">
<rewrite pattern="/search-{conversationId}" />
<rewrite pattern="/search" />
</page> ]]>
@@ -274,7 +274,7 @@
You can specify a JSF converter for complex model properties:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/calculator.jsp" action="#{calculator.calculate}">
<param name="x" value="#{calculator.lhs}"/>
<param name="y" value="#{calculator.rhs}"/>
@@ -287,7 +287,7 @@
Alternatively:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/calculator.jsp" action="#{calculator.calculate}">
<param name="x" value="#{calculator.lhs}"/>
<param name="y" value="#{calculator.rhs}"/>
@@ -300,7 +300,7 @@
JSF validators, and <literal>required="true"</literal> may also be used:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/blog.xhtml">
<param name="date" value="#{blog.date}"
validatorId="com.my.blog.PastDate" required="true"/>
@@ -311,7 +311,7 @@
Alternatively:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/blog.xhtml">
<param name="date" value="#{blog.date}"
validator="#{pastDateValidator}" required="true"/>
@@ -355,7 +355,7 @@
This JSF navigation rule:
</para>
-<programlisting role="XML"><![CDATA[<navigation-rule>
+<programlisting language="XML" role="XML"><![CDATA[<navigation-rule>
<from-view-id>/editDocument.xhtml</from-view-id>
<navigation-case>
<from-action>#{documentEditor.update}</from-action>
@@ -369,7 +369,7 @@
Can be rewritten as follows:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<rule if-outcome="success">
<redirect view-id="/viewDocument.xhtml"/>
@@ -381,7 +381,7 @@
However, this method pollutes <literal>DocumentEditor</literal> with string-valued return values (the JSF outcomes). Instead, Seam lets us write:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}"
evaluate="#{documentEditor.errors.size}">
<rule if-outcome="0">
@@ -394,7 +394,7 @@
Or even:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<rule if="#{documentEditor.errors.empty}">
<redirect view-id="/viewDocument.xhtml"/>
@@ -409,7 +409,7 @@
When an update succeeds, we probably want to end the current conversation, like so:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<rule if="#{documentEditor.errors.empty}">
<end-conversation/>
@@ -422,7 +422,7 @@
Since the conversation has ended, any subsequent requests will not know which document we are interested in. We can pass the document ID as a request parameter, which also makes the view bookmarkable:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<rule if="#{documentEditor.errors.empty}">
<end-conversation/>
@@ -437,7 +437,7 @@
Null outcomes are a special case in JSF, and are interpreted as instructions to redisplay the page. The following navigation rule matches any non-null outcome, but <emphasis>not</emphasis> the null outcome:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<rule>
<render view-id="/viewDocument.xhtml"/>
@@ -449,7 +449,7 @@
To perform navigation when a null outcome occurs, use the following:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation from-action="#{documentEditor.update}">
<render view-id="/viewDocument.xhtml"/>
</navigation>
@@ -459,7 +459,7 @@
The view ID can be given as a JSF EL expression:
</para>
-<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+<programlisting language="XML" role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
<navigation>
<rule if-outcome="success">
<redirect view-id="/#{userAgent}/displayDocument.xhtml"/>
@@ -475,7 +475,7 @@
If you have a large number of different page actions and parameters — or even just a large number of navigation rules — it is sensible to split the declarations into several smaller files. You can define actions and parameters for a page with the view ID <literal>/calc/calculator.jsp</literal> in a resource named <literal>calc/calculator.page.xml</literal>. In this case, <literal><![CDATA[<page>]]></literal> is the root element, and the view ID is implied:
</para>
-<programlisting role="XML"><![CDATA[<page action="#{calculator.calculate}">
+<programlisting language="XML" role="XML"><![CDATA[<page action="#{calculator.calculate}">
<param name="x" value="#{calculator.lhs}"/>
<param name="y" value="#{calculator.rhs}"/>
<param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
@@ -492,7 +492,7 @@
We specify event listeners (observers) in <filename>components.xml</filename>.
</para>
-<programlisting role="XML"><![CDATA[<components>
+<programlisting language="XML" role="XML"><![CDATA[<components>
<event type="hello">
<action execute="#{helloListener.sayHelloBack}"/>
<action execute="#{logger.logHello}"/>
@@ -506,70 +506,70 @@
When an event occurs, the actions registered for that event will be called in the order they appear in <filename>components.xml</filename>. Seam provides a built-in component to raise events.
</para>
-<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+<programlisting language="Java" role="JAVA">@Name("helloWorld")
public class HelloWorld {
public void sayHello() {
FacesMessages.instance().add("Hello World!");
Events.instance().raiseEvent("hello");
}
-}]]>
+}
</programlisting>
<para>
You can also use an annotation, like so:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+<programlisting language="Java" role="JAVA">@Name("helloWorld")
public class HelloWorld {
@RaiseEvent("hello")
public void sayHello() {
FacesMessages.instance().add("Hello World!");
}
-}]]>
+}
</programlisting>
<para>
This event producer is not dependent upon event consumers. The event listener can now be implemented with absolutely no dependency upon the producer:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+<programlisting language="Java" role="JAVA">@Name("helloListener")
public class HelloListener {
public void sayHelloBack() {
FacesMessages.instance().add("Hello to you too!");
}
-}]]>
+}
</programlisting>
<para>
The method binding defined above in <filename>components.xml</filename> maps the event to the consumer. If you prefer, you can also do this with annotations:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+<programlisting language="Java" role="JAVA">@Name("helloListener")
public class HelloListener {
@Observer("hello")
public void sayHelloBack() {
FacesMessages.instance().add("Hello to you too!");
}
-}]]>
+}
</programlisting>
<para>
If you are familiar with component-driven events, you may be wondering about event objects. In Seam, event objects do not need to propagate state between the event producer and listener. State is held in the Seam contexts, and shared between components. However, if you do want to pass an event object, you can do so:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+<programlisting language="Java" role="JAVA">@Name("helloWorld")
public class HelloWorld {
private String name;
public void sayHello() {
FacesMessages.instance().add("Hello World, my name is #0.", name);
Events.instance().raiseEvent("hello", name);
}
-}]]>
+}
</programlisting>
-<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+<programlisting language="Java" role="JAVA">@Name("helloListener")
public class HelloListener {
@Observer("hello")
public void sayHelloBack(String name) {
FacesMessages.instance().add("Hello #0!", name);
}
-}]]>
+}
</programlisting>
</section>
@@ -786,7 +786,7 @@
EJB3 introduced a standard interceptor model for session bean components. To add an interceptor to a bean, you need to write a class with a method annotated <literal>@AroundInvoke</literal> and annotate the bean with an <literal>@Interceptors</literal> annotation that specifies the name of the interceptor class. For example, the following interceptor checks that the user is logged in before allowing invoking an action listener method:
</para>
-<programlisting role="JAVA"><![CDATA[public class LoggedInInterceptor {
+<programlisting language="Java" role="JAVA">public class LoggedInInterceptor {
@AroundInvoke
public Object checkLoggedIn(InvocationContext invocation)
throws Exception {
@@ -798,22 +798,22 @@
//the user is not logged in, fwd to login page return "login";
}
}
-}]]>
+}
</programlisting>
<para>
To apply this interceptor to a session bean acting as an action listener, we must annotate the session bean <literal>@Interceptors(LoggedInInterceptor.class)</literal>. However, Seam builds upon the interceptor framework in EJB3 by allowing you to use <literal>@Interceptors</literal> as a meta-annotation for class level interceptors (those annotated <literal>@Target(TYPE)</literal>). In this example, we would create an <literal>@LoggedIn</literal> annotation, as follows:
</para>
-<programlisting role="JAVA"><![CDATA[@Target(TYPE)
+<programlisting language="Java" role="JAVA">@Target(TYPE)
@Retention(RUNTIME)
@Interceptors(LoggedInInterceptor.class)
-public @interface LoggedIn {}]]>
+public @interface LoggedIn {}
</programlisting>
<para>
We can now annotate our action listener bean with <literal>@LoggedIn</literal> to apply the interceptor.
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("changePasswordAction")
@LoggedIn
@Interceptors(SeamInterceptor.class)
@@ -822,29 +822,29 @@
public String changePassword() {
...
}
-}]]>
+}
</programlisting>
<para>
Where interceptor order is important, add <literal>@Interceptor</literal> annotations to your interceptor classes to specify a particular order of interceptors.
</para>
-<programlisting role="JAVA"><![CDATA[@Interceptor(around={BijectionInterceptor.class,
+<programlisting language="Java" role="JAVA">@Interceptor(around={BijectionInterceptor.class,
ValidationInterceptor.class,
ConversationInterceptor.class},
within=RemoveInterceptor.class)
public class LoggedInInterceptor {
...
-}]]>
+}
</programlisting>
<para>
You can even have a client-side interceptor, for built-in EJB3 functions:
</para>
-<programlisting role="JAVA"><![CDATA[@Interceptor(type=CLIENT)
+<programlisting language="Java" role="JAVA">@Interceptor(type=CLIENT)
public class LoggedInInterceptor {
...
-}]]>
+}
</programlisting>
<para>
EJB interceptors are stateful, and their lifecycles match that of the component they intercept. For interceptors that do not need to maintain state, Seam allows performance optimization where <literal>@Interceptor(stateless=true)</literal> is specified.
@@ -889,7 +889,7 @@
To enable Seam's exception handling, the master Servlet filter must be declared in <filename>web.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<filter>
+<programlisting language="XML" role="XML"><![CDATA[<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>
@@ -910,20 +910,20 @@
The following exception results in a HTTP 404 error whenever it propagates outside the Seam component layer. It does not roll back the current transaction immediately when thrown, but the transaction will be rolled back if it the exception is not caught by another Seam component.
</para>
-<programlisting role="JAVA"><![CDATA[@HttpError(errorCode=404)
+<programlisting language="Java" role="JAVA">@HttpError(errorCode=404)
public class ApplicationException extends Exception {
...
-}]]>
+}
</programlisting>
<para>
This exception results in a browser redirect whenever it propagates outside the Seam component layer. It also ends the current conversation. It causes an immediate rollback of the current transaction.
</para>
-<programlisting role="JAVA"><![CDATA[@Redirect(viewId="/failure.xhtml", end=true)
+<programlisting language="Java" role="JAVA">@Redirect(viewId="/failure.xhtml", end=true)
@ApplicationException(rollback=true)
public class UnrecoverableApplicationException extends RuntimeException {
...
-}]]>
+}
</programlisting>
<note>
<para>
@@ -937,10 +937,10 @@
When this exception propagates outside the Seam component layer, it results in a redirect and a message to the user. It also immediately rolls back the current transaction.
</para>
-<programlisting role="JAVA"><![CDATA[@Redirect(viewId="/error.xhtml", message="Unexpected error")
+<programlisting language="Java" role="JAVA">@Redirect(viewId="/error.xhtml", message="Unexpected error")
public class SystemException extends RuntimeException {
...
-}]]>
+}
</programlisting>
</section>
@@ -950,7 +950,7 @@
Since annotations cannot be added to all exception classes, Seam also lets us specify this functionality in <filename>pages.xml</filename>.
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<exception class="javax.persistence.EntityNotFoundException">
<http-error error-code="404"/>
</exception>
@@ -971,7 +971,7 @@
</pages>]]>
</programlisting>
<para>
- The final <literal><![CDATA[<exception>]]></literal> declaration does not specify a class, and acts as catch-all for any exception without specified handling via annotations or in <filename>pages.xml</filename>.
+ The final <tag><![CDATA[<exception>]]></tag> declaration does not specify a class, and acts as catch-all for any exception without specified handling via annotations or in <filename>pages.xml</filename>.
</para>
<para>
You can also use EL to specify the <literal>view-id</literal> to redirect to.
@@ -980,7 +980,7 @@
You can also access the handled exception instance through EL. Seam places it in the conversation context. For example, to access the exception message:
</para>
-<programlisting role="XML"><![CDATA[...
+<programlisting language="XML" role="XML"><![CDATA[...
throw new AuthorizationException("You are not allowed to do this!");
<pages>
@@ -1003,7 +1003,7 @@
For the exception handlers defined in <filename>pages.xml</filename>, it is possible to declare the level at which the exception will be logged, or to suppress exception logging altogether. The <literal>log</literal> and <literal>log-level</literal> attributes are used to control exception logging. No log message will be generated when the specified exception occurs when <literal>log="false"</literal> is set, as shown here:
</para>
-<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
+<programlisting language="XML" role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
log="false">
<redirect view-id="/register.xhtml">
<message severity="warn">
@@ -1016,7 +1016,7 @@
If the <literal>log</literal> attribute is not specified, then it defaults to <literal>true</literal> — that is, the exception will be logged. Alternatively, you can specify the <literal>log-level</literal> to control the level at which the exception will be logged:
</para>
-<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
+<programlisting language="XML" role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
log-level="info">
<redirect view-id="/register.xhtml">
<message severity="warn">
@@ -1038,7 +1038,7 @@
If you are using JPA:
</para>
-<programlisting role="XML"><![CDATA[<exception class="javax.persistence.EntityNotFoundException">
+<programlisting language="XML" role="XML"><![CDATA[<exception class="javax.persistence.EntityNotFoundException">
<redirect view-id="/error.xhtml">
<message>Not found</message>
</redirect>
@@ -1057,7 +1057,7 @@
If you are using the Seam Application Framework:
</para>
-<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.framework.EntityNotFoundException">
+<programlisting language="XML" role="XML"><![CDATA[<exception class="org.jboss.seam.framework.EntityNotFoundException">
<redirect view-id="/error.xhtml">
<message>Not found</message>
</redirect>
@@ -1067,7 +1067,7 @@
If you are using Seam Security:
</para>
-<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.AuthorizationException">
+<programlisting language="XML" role="XML"><![CDATA[<exception class="org.jboss.seam.security.AuthorizationException">
<redirect>
<message>You don't have permission to do this</message>
</redirect>
@@ -1083,7 +1083,7 @@
And, for JSF:
</para>
-<programlisting role="XML"><![CDATA[<exception class="javax.Faces.application.ViewExpiredException">
+<programlisting language="XML" role="XML"><![CDATA[<exception class="javax.Faces.application.ViewExpiredException">
<redirect view-id="/error.xhtml">
<message>Your session has timed out, please try again</message>
</redirect>
More information about the jboss-cvs-commits
mailing list