[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Thu Jul 13 23:26:32 EDT 2006
User: gavin
Date: 06/07/13 23:26:32
Modified: doc/reference/en/modules components.xml concepts.xml
conversations.xml drools.xml
Log:
updated docs
Revision Changes Path
1.36 +8 -1 jboss-seam/doc/reference/en/modules/components.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: components.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/components.xml,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -b -r1.35 -r1.36
--- components.xml 13 Jul 2006 02:45:41 -0000 1.35
+++ components.xml 14 Jul 2006 03:26:32 -0000 1.36
@@ -1071,7 +1071,8 @@
<term><literal><emphasis><alias></emphasis></literal></term>
<listitem>
<para>
- An "alias" (a second name) for a component.
+ An "alias" (a second name) for a component. You can even create
+ an alias for an often-used expression.
</para>
<itemizedlist>
<listitem>
@@ -1080,6 +1081,12 @@
— the name of the component to be aliased.
</para>
</listitem>
+ <listitem>
+ <para>
+ <literal><emphasis><alias></emphasis>.expression</literal>
+ — an expression to be evaluated.
+ </para>
+ </listitem>
</itemizedlist>
</listitem>
</varlistentry>
1.29 +114 -0 jboss-seam/doc/reference/en/modules/concepts.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: concepts.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/concepts.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -b -r1.28 -r1.29
--- concepts.xml 12 Jul 2006 23:14:33 -0000 1.28
+++ concepts.xml 14 Jul 2006 03:26:32 -0000 1.29
@@ -644,6 +644,9 @@
annotation but are not installed by default (this is the case for certain
built-in components).
</para></listitem>
+ <listitem><para>
+ Override the scope of a component.
+ </para></listitem>
</itemizedlist>
<para>
@@ -681,6 +684,34 @@
</components>]]></programlisting>
<para>
+ This example creates a session-scoped Seam-managed persistence context (this
+ is not recommended in practice):
+ </para>
+
+ <programlisting><![CDATA[<components>
+
+ <component name="productDatabase"
+ scope="session"
+ class="org.jboss.seam.core.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
+ </component>
+
+</components>]]></programlisting>
+
+ <para>
+ You can create an "alias" (a second name) for a Seam component like so:
+ </para>
+
+ <programlisting><![CDATA[<components>
+
+ <component name="user"
+ class="org.jboss.seam.core.Alias">
+ <property name="name">actor</property>
+ </component>
+
+</components>]]></programlisting>
+
+ <para>
Sometimes we want to reuse the same <literal>components.xml</literal> file with
minor changes during both deployment and testing. Seam let's you place wildcards
of the form <literal>@wildcard@</literal> in the <literal>components.xml</literal>
@@ -691,6 +722,60 @@
</sect2>
+ <sect2>
+ <title>Configurable property types</title>
+ <para>
+ Properties of string, primitive or primitive wrapper type may be configured just
+ as you would expect:
+ </para>
+
+ <programlisting><![CDATA[org.jboss.seam.core.manager.conversationTimeout 60000]]></programlisting>
+
+ <programlisting><![CDATA[<component name="org.jboss.seam.core.manager">
+ <property name="conversationTimeout">60000</property>
+</component>]]></programlisting>
+
+ <para>
+ Arrays, sets and lists of strings or primitives are also supported:
+ </para>
+
+ <programlisting><![CDATA[org.jboss.seam.core.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml]]></programlisting>
+
+ <programlisting><![CDATA[<component name="org.jboss.seam.core.jbpm">
+ <property name="processDefinitions">
+ <value>order.jpdl.xml</value>
+ <value>return.jpdl.xml</value>
+ <value>inventory.jpdl.xml</value>
+ </property>
+</component>]]></programlisting>
+
+ <para>
+ Even maps with String-valued keys and string or primitive values are supported:
+ </para>
+
+ <programlisting><![CDATA[<component name="issueEditor">
+ <property name="issueStatuses">
+ <key>open</key> <value>open issue</value>
+ <key>resolved</key> <value>issue resolved by developer</value>
+ <key>closed</key> <value>resolution accepted by user</value>
+ </property>
+</component>]]></programlisting>
+
+ <para>
+ Finally, you may wire together components using a value-binding expression. Note
+ that this is quite different to injection using <literal>@In</literal>, since it
+ happens at component instantiation time instead of invocation time. It is
+ therefore much more similar to the dependecy injection facilities offered by
+ traditional IoC containers like Spring.
+ </para>
+
+ <programlisting><![CDATA[<component name="policyPricingWorkingMemory"
+ class="org.jboss.seam.drools.ManagedWorkingMemory">
+ <property name="ruleBase">#{policyPricingRules}</property>
+</component>]]></programlisting>
+
+ </sect2>
+
</sect1>
<sect1>
@@ -1186,4 +1271,33 @@
</sect1>
+ <sect1>
+ <title>Managing exceptions</title>
+ <para>
+ JSF is surprisingly limited when it comes to exception handling. Seam lets you
+ define how a particular class of event is to be treated by annotating the event
+ class. This facility is meant to be combined with the EJB 3.0-standard
+ <literal>@ApplicationException</literal> annotation which specifies whether
+ the exception should cause a transaction rollback.
+ </para>
+
+ <para>
+ This exception results in a HTTP 404 error whenever it propagates out of the
+ Seam component layer. It does not roll back the current transaction.
+ </para>
+
+ <programlisting><![CDATA[@HttpError(errorCode=404)
+public class DocumentNotFoundException extends Exception { ... }]]></programlisting>
+
+ <para>
+ This exception results in a browser redirect whenever it propagates out of the
+ Seam component layer. It also rolls back the current transaction.
+ </para>
+
+ <programlisting><![CDATA[@Redirect(viewId="/error.xhtml")
+ at ApplicationException(rollback=true)
+public class UnrecoverableException extends RuntimeException { ... }]]></programlisting>
+
+ </sect1>
+
</chapter>
\ No newline at end of file
1.15 +69 -1 jboss-seam/doc/reference/en/modules/conversations.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: conversations.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/conversations.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- conversations.xml 23 Jun 2006 14:57:34 -0000 1.14
+++ conversations.xml 14 Jul 2006 03:26:32 -0000 1.15
@@ -107,7 +107,8 @@
<para>
If the JSF request lifecycle is foreshortened by a redirect,
Seam transparently stores and restores the current conversation
- context.
+ context—unless the conversation was already ended via
+ <literal>@End(beforeRedirect=true)</literal>.
</para>
</listitem>
</itemizedlist>
@@ -781,6 +782,73 @@
</section>
<section>
+ <title>Seam-managed persistence contexts and atomic conversations</title>
+ <para>
+ Seam provides built-in components for EJB 3.0 and Hibernate persistence context
+ management that support the use of persistence contexts scoped to the conversation.
+ This useful feature allows you to program optimistic transactions that span multiple
+ requests to the server without the need to use the merge() operation or to re-load
+ data at the beginning of each request, and without the need to wrestle with the
+ dreaded <literal>LazyInitializationException</literal> or
+ <literal>NonUniqueObjectException</literal>. Please see the configuration chapter
+ for information about configuring Seam-managed persistence contexts and
+ Seam-managed transactions.
+ </para>
+ <para>
+ As with any optimistic transaction management, transaction isolation and consistency
+ can be achieved via use of optimistic locking. Fortunately, both Hibernate and EJB
+ 3.0 make it very easy to use optimistic locking, by providing the
+ <literal>@Version</literal> annotation.
+ </para>
+ <para>
+ By default, the persistence context is flushed (synchronized with the database)
+ at the end of each transaction. This is sometimes the desired behavior. But very
+ often, we would prefer that all changes are held in memory and only written to
+ the database when the conversation ends successfully. This allows for truly
+ atomic conversations. As the result of a truly stupid and shortsighted decision
+ by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group,
+ there is currently no simple, usable and portable way to implement atomic
+ conversations using EJB 3.0 persistence. However, Hibernate provides this feature
+ as a vendor extension to the <literal>FlushModeType</literal>s defined by the
+ specification, and it is our expectation that other vendors will soon provide
+ a similar extension.
+ </para>
+ <para>
+ Seam lets you specify <literal>FlushModeType.MANUAL</literal> when beginning a
+ conversation. Currently, this works only when Hibernate is the underlying
+ persistence provider, but we plan to support other equivalent vendor extensions.
+ </para>
+
+ <programlisting><![CDATA[@In(create=true) EntityManager em; //a Seam-managed persistence context
+
+ at Begin(flushMode=MANUAL)
+public void beginClaimWizard() {
+ claim = em.find(Claim.class, claimId);
+}]]></programlisting>
+
+ <para>
+ Now, the <literal>claim</literal> object remains managed by the persistence context
+ for the rest ot the conversation. We can make changes to the claim:
+ </para>
+
+ <programlisting><![CDATA[public void addPartyToClaim() {
+ Party party = ....;
+ claim.addParty(party);
+}]]></programlisting>
+
+ <para>
+ But these changes will not be flushed to the database until we explicitly force
+ the flush to occur:
+ </para>
+
+ <programlisting><![CDATA[@End
+public void commitClaim() {
+ em.flush();
+}]]></programlisting>
+
+ </section>
+
+ <section>
<title>Seam and AJAX</title>
<para>
1.8 +2 -2 jboss-seam/doc/reference/en/modules/drools.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: drools.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/drools.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- drools.xml 18 Jun 2006 15:48:17 -0000 1.7
+++ drools.xml 14 Jul 2006 03:26:32 -0000 1.8
@@ -42,12 +42,12 @@
<programlisting><![CDATA[<component name="policyPricingWorkingMemory"
class="org.jboss.seam.drools.ManagedWorkingMemory">
- <property name="ruleBaseName">policyPricingRules</property>
+ <property name="ruleBase">#{policyPricingRules}</property>
</component>]]></programlisting>
<para>
Notice that we gave the <literal>policyPricingWorkingMemory</literal> a
- reference back to our rule base via the <literal>ruleBaseName</literal>
+ reference back to our rule base via the <literal>ruleBase</literal>
configuration property.
</para>
More information about the jboss-cvs-commits
mailing list