[jboss-cvs] JBossAS SVN: r103232 - projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Mar 30 02:36:06 EDT 2010
Author: misty at redhat.com
Date: 2010-03-30 02:36:06 -0400 (Tue, 30 Mar 2010)
New Revision: 103232
Modified:
projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml
Log:
More editing
Modified: projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml
===================================================================
--- projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml 2010-03-30 06:08:51 UTC (rev 103231)
+++ projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml 2010-03-30 06:36:06 UTC (rev 103232)
@@ -376,66 +376,74 @@
<section>
<title>Wiring POJOs together </title>
- <para>So far we have seen how to create POJOs and declare instances of them together with
- names in an XML deployment descriptor. However, individual POJO instances can only provide
- relatively simple behaviour. Things really get interesting when we combine POJOs together
- to perform more complex tasks. In our example we know that we can choose different salary
- strategy implementations for the HRManager so how do we go about wiring the POJOs
- together?</para>
- <para>The answer is to use the XML deployment descriptor again as follows:</para>
- <programlisting role="XML"><?xml version="1.0" encoding="UTF-8"?>
+ <para>
+ Now you know how to create POJOs and declare unique instances of them in an XML deployment descriptor. However, individual POJO instances can only provide relatively simple behaviour. The real power of POJOs comes from combining them to accomplish complex tasks. The next task is to wire POJOs together, to enable choosing different salary implementations for the HRManager.
+ </para>
+ <para>
+ To accomplish this, use the XML deployment descriptor as follows:
+ </para>
- <deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
- xmlns="urn:jboss:bean-deployer:2.0">
+ <programlisting role="XML">
+ <?xml version="1.0" encoding="UTF-8"?>
- <bean name="HRService" class="org.jboss.example.service.HRManager">
- <property name="salaryStrategy"><emphasis><inject bean="AgeBasedSalary"/></emphasis></property>
- </bean>
-
- <bean name="AgeBasedSalary"
- class="org.jboss.example.service.util.AgeBasedSalaryStrategy"/>
+ <deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="HRService" class="org.jboss.example.service.HRManager">
+ <property name="salaryStrategy"><emphasis><inject bean="AgeBasedSalary"/></emphasis></property>
+ </bean>
+
+ <bean name="AgeBasedSalary"
+ class="org.jboss.example.service.util.AgeBasedSalaryStrategy"/>
- </deployment></programlisting>
- <para>We first need to create an instance of our chosen salary strategy implementation by
- including an additional <bean> element. Here we have chosen the
- AgeBasedSalaryStrategy. Next we need to inject a reference to this bean into the instance
- of HRManager created using the HRService bean. Injection is possible as the HRManager
- class contains a <methodname>setSalaryStrategy(SalaryStrategy strategy)</methodname> method. Behind
- the scenes JBoss Microcontainer will call this method on the newly created HRManager
- instance and pass in a reference to the AgeBasedSalaryStrategy instance.</para>
- <para>In other words the XML deployment descriptor causes the same sequence of events to
- occur as if you had written the following code:</para>
- <programlisting role="JAVA">HRManager hrService = new HRManager();
- AgeBasedSalaryStrategy ageBasedSalary = new AgeBasedSalaryStrategy();
- hrService.setSalaryStrategy(ageBasedSalary);</programlisting>
- <para>In addition to performing injection via property setter methods JBoss Microcontainer
- can also perform injection via constructor parameters if necessary. For more details
- please see the 'Injection' chapter in Part II 'POJO Development'. </para>
+ </deployment>
+ </programlisting>
+
+ <procedure>
+ <title>XML Deployment Explanation</title>
+ <step>
+ <para>First, create an instance of your chosen salary strategy implementation by including an additional <bean> element. In this instance, the example uses AgeBasedSalaryStrategy.</para>
+ </step>
+ <step>
+ <para>Next, inject a reference to this bean into the instance of HRManager created using the HRService bean. Injection is possible as the HRManager class contains a <methodname>setSalaryStrategy(SalaryStrategy strategy)</methodname> method.</para>
+ </step>
+ <step>
+ <para>Behind the scenes JBoss Microcontainer will call this method on the newly created HRManager instance and pass in a reference to the AgeBasedSalaryStrategy instance.</para>
+ </step>
+ </procedure>
+
+ <para>
+ In other words the XML deployment descriptor causes the same sequence of events to occur as in the following code snippet:
+ </para>
+
+ <programlisting role="JAVA">
+ HRManager hrService = new HRManager();
+ AgeBasedSalaryStrategy ageBasedSalary = new AgeBasedSalaryStrategy();
+ hrService.setSalaryStrategy(ageBasedSalary);
+ </programlisting>
+
+ <para>
+ In addition to performing injection via property setter methods, JBoss Microcontainer can also perform injection via constructor parameters if necessary. For more details please see the <emphasis>Injection</emphasis> chapter in Part II <emphasis>POJO Development</emphasis>. <remark>Fix me</remark>
+ </para>
<note>
- <para>Although we can create instances of classes using the <bean> element in the
- deployment descriptor it is not always appropriate to do so. For example we do not need
- to create instances of the Employee and Address classes since these will be created by
- the client in response to input from the user. As such they remain part of the service
- but are not mentioned in the deployment descriptor. </para>
+ <para>
+ Although you can create instances of classes using the <bean> element in the deployment descriptor, it is not always appropriate to do so. For example you do not need to create instances of the Employee and Address classes. They are created by the client in response to input from the user. They remain part of the service but are not invoked in the deployment descriptor.
+ </para>
</note>
<note>
- <para>Also note that it is possible to define multiple beans within a deployment
- descriptor providing that each has a unique name. The names are required in order to
- perform injection as shown above. However this does not mean to say that all of the
- beans represent services. While a service could be implemented using a single bean it is
- most often the case that multiple beans are used together as in our example. In these
- cases there is usually one bean that represents the service entry point containing the
- public methods intended for the clients to call. In our example this is the HRService
- bean. Notice that there is nothing in the XML deployment descriptor to say which beans
- represent a service or indeed which bean if any is the service entry point (a service
- may run autonomously in which case it is its own client). Care must therefore be taken
- when creating deployment descriptors to ensure that sufficient comments are included to
- describe what the beans are used for. Alternatively a naming convention such as ending
- each bean name that represents a service entry point with 'Service' can be
- used instead, e.g. HRService.</para>
+ <para>
+ You can define multiple beans within a deployment descriptor if each has a unique name. The names are required to perform injection as shown above. However this does not mean that each bean represents a service. While a service could be implemented using a single bean, multiple beans are usually used together. In these cases, one bean usually represents the service entry point containing the public methods called by the clients. In our example this is the HRService bean. There is nothing in the XML deployment descriptor to indicate which beans represent a service or which bean (if any) is the service entry point.
+ </para>
+ <para>
+ A service may run autonomously in which case it is its own client.
+ </para>
+ <para>
+ When creating deployment descriptors, make sure to comment your code, making it clear what each bean is used for. Or, use a naming convention to clarify which beans represent service entry points. For example, our example uses a <literal>Service</literal> postfix: HRService.
+ </para>
</note>
</section>
+
<section>
<title>Configuring a service</title>
<para>Injecting references between POJO instances is one way of configuring a service
More information about the jboss-cvs-commits
mailing list