[jboss-cvs] JBossAS SVN: r103730 - projects/snowdrop/examples/trunk/sportsclub/docs/guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Apr 9 01:46:26 EDT 2010
Author: marius.bogoevici
Date: 2010-04-09 01:46:26 -0400 (Fri, 09 Apr 2010)
New Revision: 103730
Modified:
projects/snowdrop/examples/trunk/sportsclub/docs/guide/en-US/Modules.xml
Log:
Documentation
Modified: projects/snowdrop/examples/trunk/sportsclub/docs/guide/en-US/Modules.xml
===================================================================
--- projects/snowdrop/examples/trunk/sportsclub/docs/guide/en-US/Modules.xml 2010-04-09 05:24:40 UTC (rev 103729)
+++ projects/snowdrop/examples/trunk/sportsclub/docs/guide/en-US/Modules.xml 2010-04-09 05:46:26 UTC (rev 103730)
@@ -20,14 +20,148 @@
changed easily if the implementations change.</para>
<section>
- <title>A list of the Spring integration use cases</title>
+ <title>A look at the JBoss/Spring integration use cases</title>
<para>The Sportsclub application covers a number of JBoss and Spring
integration use cases. The scenarios selected for this example are
focusing on using the Java EE 5 services provided by JBoss AS in Spring
applications.</para>
- <para></para>
+ <para>The use cases can be grouped in categories as follows:<table>
+ <title>Use case list overview</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry align="center">Category</entry>
+
+ <entry align="center">Use case</entry>
+
+ <entry align="center">How does this involve JBoss AS</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Persistence</entry>
+
+ <entry>Spring/Hibernate integration</entry>
+
+ <entry>The application is using a Spring-configured Hibernate
+ SessionFactory using JTA transaction management and bound to
+ JTA. The Hibernate library being used is the one provided by
+ JBoss AS.</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+
+ <entry>Spring/JPA integration</entry>
+
+ <entry>The Persistence Unit is deployed by JBoss and retrieved
+ from JNDI to be injected into Spring beans. PersistenceContext
+ is shared with surrounding EJBs (if any)</entry>
+ </row>
+
+ <row>
+ <entry>Testing</entry>
+
+ <entry>Unit-testing components that have managed infrastructure
+ dependencies</entry>
+
+ <entry>The DataSource and EntityManager are managed by JBoss and
+ acquired from JNDI by Spring when the application is running. In
+ the case of JBoss, developers can test their code in isolation
+ using Spring-specific replacements that 'simulate' the JBoss
+ environment.</entry>
+ </row>
+
+ <row>
+ <entry>Business Logic</entry>
+
+ <entry>Spring-based service beans</entry>
+
+ <entry>The business services are Spring-managed and wrapped into
+ transactions managed by Spring's interceptors. The
+ TransactionManager in use is the JTATransactionManager using
+ JBoss Transactions provided in JBoss AS.</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+
+ <entry>EJBs injected with Spring Beans</entry>
+
+ <entry>The application uses JBoss-deployed EJBs which are
+ injected with Spring beans acquired from an application context
+ bootstrapped by the Spring Deployer. Transactions are managed by
+ EJBs. </entry>
+ </row>
+
+ <row>
+ <entry>User Interface</entry>
+
+ <entry>JSF/Richfaces and Spring integration </entry>
+
+ <entry>The application uses the JBoss AS-provided JSF support,
+ and Richfaces components. The business services and UI-backing
+ instances are Spring beans.</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+
+ <entry>Spring MVC and EJB integration</entry>
+
+ <entry>The application uses Spring MVC and the business logic is
+ implemented using JBoss-deployed EJBs, which are injected into
+ the Spring controllers.</entry>
+ </row>
+
+ <row>
+ <entry>JMS/JCA integration</entry>
+
+ <entry>JMS/Spring integration using JCA</entry>
+
+ <entry>Spring-configured message listeners are used for
+ processing JMS messages from JBoss AS-managed destinations. The
+ application uses the Spring /JCA integration for receiving
+ messages.</entry>
+ </row>
+
+ <row>
+ <entry>Aspect-oriented programming</entry>
+
+ <entry>Spring-based weaving of POJO aspects</entry>
+
+ <entry>This use case does not have any JBoss AS-specific
+ functionality.</entry>
+ </row>
+
+ <row>
+ <entry>JMX</entry>
+
+ <entry>Spring beans are exposed as JMX beans</entry>
+
+ <entry>The JBoss AS MBean Server is used for registering the
+ Spring-exported JMX beans. Consequently, the Spring beans can be
+ managed from the JBoss AS Administration Console.</entry>
+ </row>
+
+ <row>
+ <entry>Web Services</entry>
+
+ <entry>JAX-WS defined web-services are injected with Spring
+ beans</entry>
+
+ <entry>The application uses JBoss AS' support for JAX-WS through
+ JBoss WS, but also Spring to define the underlying business
+ logic, which is injected into the JBoss WS-deployed
+ services.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
</section>
<section>
@@ -691,7 +825,9 @@
the previous sections, the Sportsclub application suite provides a few
other examples of integrating Spring and JBoss. Since all the features are
Spring-based, they have been included as business services of the
- Invoicing web application. </para>
+ Invoicing web application. All the definitions for the following examples
+ can be found in the /WEB-INF/spring-business-context.xml file defined in
+ the spring-invoicing-webmvc module.</para>
<section>
<title>Payment processing: JMS integration through JCA</title>
@@ -718,9 +854,37 @@
PaymentAuditor aspect that intercepts every call made to the
PaymentProcessor.</para>
- <para>The solution applied in this application is to use the 'aop'
- namespace provided by Spring and XML configuration, defining pointcuts
- via AspectJ syntax.</para>
+ <para>The aspect is a simple POJO:</para>
+
+ <para><informalexample>
+ <para><programlisting>public class PaymentAuditor
+{
+ /* code ommitted */
+
+ public void auditPayment(Long accountId, BigDecimal amount)
+ {
+ System.out.println("AUDIT ENABLED! A payment has been made to account "
+ + accountId + " for the amount of " + amount);
+ }
+}</programlisting></para>
+ </informalexample>The aspect is applied through the following
+ definitions:</para>
+
+ <informalexample>
+ <para><programlisting> <aop:config>
+ <aop:aspect ref="paymentAuditor">
+ <aop:pointcut id="processingPayment"
+ expression="execution(* *..PaymentProcessor+.*(..)) &amp;&amp; args(accountId, amount)"/>
+ <aop:before arg-names="accountId, amount" pointcut-ref="processingPayment" method="auditPayment"/>
+ </aop:aspect>
+ </aop:config>
+
+ <bean id="paymentAuditor" class="org.jboss.snowdrop.samples.sportsclub.audit.PaymentAuditor"/>
+
+</programlisting>As you can see, the aspect is defined as a bean and applied
+ as an aspect through the Spring aop namespace. The pointcut definition
+ is an AspectJ expression.</para>
+ </informalexample>
</section>
<section>
@@ -728,18 +892,74 @@
<para>JMX is a very important tool for monitoring and configuring Java
applications. Collecting information about the system and the ability of
- making configuration at runtime are important administration tools. For
- this example, the requirement is to be able to turn auditing on and off,
- at runtime, as required. Removing an aspect once it has been applied by
- Spring is not possible, so the solution in this case is to define a flag
- property on the aspect, which controls whether the auditing
- functionality will be invoked or not. </para>
+ making configuration at runtime are important administration features.
+ For this example, the requirement is to be able to turn auditing on and
+ off, at runtime, whenever required. Removing an aspect once it has been
+ applied by Spring is not possible, so the solution in this case is to
+ define a flag property on the aspect, which controls whether the
+ auditing functionality will be invoked or not.</para>
<para>In order to be able to make changes at runtime, the Spring bean
which implements the aspect will be configured as a JMX bean and
- registered in the MBean server of JBoss. As a result, you can turn this
- functionality on and off directly from the JBoss AS JMX administration
- console. </para>
+ registered in the MBean server of JBoss. In this example, we are using
+ annotations to define Spring-specific JMX metadata. The complete
+ definition for the PaymentAuditor is:</para>
+
+ <para><informalexample>
+ <para><programlisting>@ManagedResource(objectName = "sportsclub:name=paymentAuditor", description = "Payment Auditor", logFile = "log-sportsclub-auditor-jmx.log")
+ at Component
+public class PaymentAuditor
+{
+ private boolean enabled = true;
+
+ @ManagedAttribute
+ public void setEnabled(boolean enabled)
+ {
+ this.enabled = enabled;
+ }
+
+ @ManagedAttribute
+ public boolean getEnabled()
+ {
+ return this.enabled;
+ }
+
+ public void auditPayment(Long accountId, BigDecimal amount)
+ {
+ if (this.enabled)
+ {
+ System.out.println("AUDIT ENABLED! A payment has been made to account " + accountId + " for the amount of " + amount);
+ }
+ else
+ {
+ System.out.println("AUDIT DISABLED!");
+ }
+ }
+}</programlisting>The annotations ManagedResource and ManagedAttribute are
+ using to indicate what classes and properties are JMX-managed. In
+ order to expose the bean through JMX, it must be exported using
+ Spring's MBean Exporter.</para>
+
+ <para><programlisting><bean id="attributeSource" class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/>
+
+ <bean class="org.springframework.jmx.export.MBeanExporter">
+ <property name="autodetectModeName" value="AUTODETECT_ASSEMBLER"/>
+ <property name="ensureUniqueRuntimeObjectNames" value="true"/>
+ <property name="namingStrategy">
+ <bean class="org.springframework.jmx.export.naming.MetadataNamingStrategy">
+ <property name="attributeSource" ref="attributeSource"/>
+ </bean>
+ </property>
+ <property name="assembler">
+ <bean class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler">
+ <property name="attributeSource" ref="attributeSource"/>
+ </bean>
+ </property>
+ </bean></programlisting></para>
+ </informalexample></para>
+
+ <para>As a result, you can turn this functionality on and off directly
+ from the JBoss AS JMX administration console.</para>
</section>
<section>
@@ -752,7 +972,43 @@
will expose a Spring bean with JAX-WS annotations as a web
service.</para>
- <para></para>
+ <para>To that end, a JAX-WS annotated class is provided by the
+ application:</para>
+
+ <informalexample>
+ <para><programlisting>@WebService
+public class PaymentNotificationService extends SpringBeanAutowiringSupport
+{
+
+ @Autowired
+ private PaymentProcessor paymentProcessor;
+
+ @WebMethod
+ public Long notifyPayment(Long accountNumber, BigDecimal amount)
+ {
+ return paymentProcessor.processPayment(accountNumber, amount);
+ }
+
+}</programlisting>By extending SpringBeanAutowiringSupport, the class
+ PaymentNotificationService will be injected automatically with the
+ same PaymentProcessor instance that is used by the JMS notification
+ processor, and defined in the application context created from
+ WEB-INF/spring-business-context.xml. This is necessary, because no
+ bean of the type PaymentNotificationService is defined in the
+ application context. Instead, the web service is defined and mapped as
+ a servlet in /WEB-INF/web.xml:</para>
+
+ <para><programlisting><servlet>
+ <servlet-name>PaymentNotificationService</servlet-name>
+ <servlet-class>org.jboss.snowdrop.samples.sportsclub.ws.PaymentNotificationService</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>PaymentNotificationService</servlet-name>
+ <url-pattern>/ws/payment</url-pattern>
+ </servlet-mapping></programlisting>As a result, the a JAX-WS web
+ service can be accessed at http://localhost:8080/ws/payment.</para>
+ </informalexample>
</section>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list