[jboss-cvs] JBossAS SVN: r68190 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Dec 12 12:44:22 EST 2007
Author: newtonm
Date: 2007-12-12 12:44:22 -0500 (Wed, 12 Dec 2007)
New Revision: 68190
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Added rest of content for Configuring POJOs chapter.
Modified: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-12 17:04:37 UTC (rev 68189)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-12 17:44:22 UTC (rev 68190)
@@ -1146,16 +1146,186 @@
</section>
<section>
<title>Writing deployment descriptors</title>
- <para/>
+ <para>Deployment descriptors externalize the configuration of POJOs into one or more files that are separate from the source code. This means that changes can be made without having to recompile any classes. The usual way to define a deployment descriptor is using the bean-deployer XML schema whose root element is <deployment>. This is used to group multiple beans together so that they are deployed as a unit:</para>
+ <programlisting><deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- Bean definitions -->
+
+</deployment></programlisting>
+ <para>The bean definitions are created using <bean> elements that each describe a single POJO instance. Each bean is given a name so that it can be referenced elsewhere in the deployment descriptor or looked up by a client at runtime.</para>
+ <programlisting><deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="Person" class="org.jboss.example.microcontainer.PersonBean"/>
+
+ <bean name="Address" class="org.jboss.example.microcontainer.AddressBean"/>
+
+</deployment> </programlisting>
+ <para>The name of the file containing these elements can be anything you like providing that a deployer can access it and parse the contents correctly. By convention it is called jboss-beans.xml as anything that ends in -beans.xml is found by default using the FileStructure deployer.</para>
+ <note>
+ <para>Although deployment descriptors are usually created using the bean-deployer XML schema it is also possible to use other XML schemas or even Java properties as shown in the following sections.</para>
+ </note>
</section>
<section>
<title>Using JavaBean XML</title>
+ <para>Together with the bean-deployer XML schema the microcontainer also contains a javabean XML schema. This is a lightweight version of bean-deployer that allows for the construction and configuration of <ulink url="http://java.sun.com/products/javabeans/">JavaBeans</ulink> without any advanced features like bean injection, callbacks or dependencies. It is intended to be used in situations where the microcontainer has been customised to remove all of the advanced functionality so that it can be bootstrapped in very small runtime environments. </para>
+ <para>Construction of POJOs is performed using either a normal constructor or a static factory method. In either case constructor or method parameters can be added as necessary: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Default constructor</para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean"/></programlisting>
+ </listitem>
+ <listitem>
+ <para>Contructor with parameters</para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <constructor>
+ <property name="ABoolean">true</property>
+ <property name="ACharacter">x</property>
+ <property name="AShort">123</property>
+ </constructor>
+</javabean></programlisting>
+ </listitem>
+ <listitem>
+ <para>Static factory method</para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <constructor factoryClass="org.jboss.test.javabean.support.SimpleBeanFactory"
+ factoryMethod="newInstance"/>
+</javabean></programlisting>
+ </listitem>
+ <listitem>
+ <para>Static factory method with parameters</para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <constructor factoryClass="org.jboss.test.javabean.support.SimpleBeanFactory"
+ factoryMethod="newInstance">
+ <property name="AString">StringValue</property>
+ <property name="AByte">12</property>
+ </constructor>
+</javabean></programlisting>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>JavaBean declarations do not include a <code>name</code> attribute which means that you cannot inject references into other JavaBeans or lookup a reference to a JavaBean instance from a client at runtime.</para>
+ </note>
+ <para>Once a JavaBean has been constructed then simple injection of property values is possible using the <property> element: </para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <property name="ADouble">3.14e12</property>
+ <property name="ADate">Jan 01 00:00:00 CET 2001</property>
+ <property name="ABigDecimal">12e4</property>
+ <property name="ABigInteger">123456</property>
+ <property name="abyte">12</property>
+</javabean></programlisting>
+ <para>As with properties defined using the bean-deployer XML schema the string values are converted into objects of the correct type using JavaBean <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/PropertyEditor.html">PropertyEditors</ulink>. For cases where the type is ambiguous, e.g. when defining numbers, you can specify the required type by including a <code>class</code> attribute: </para>
+ <programlisting><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <property name="ANumber" class="java.lang.Long">12345</property>
+</javabean></programlisting>
+ <important>
+ <para>Beans created using the bean-deployer XML schema can include JavaBeans created using the javabean XML schema instead of string values. This provides a simple way to inject objects composed of multiple values into a bean property without having to write a complicated property editor:</para>
+ <programlisting><bean name="example" class="org.jboss.acme.Example">
+ <property name="myProperty">
+ <javabean xmlns="urn:jboss:javabean:1.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <property name="ADate">Jan 01 00:00:00 CET 2001</property>
+ <property name="ABigDecimal">12e4</property>
+ </javabean>
+ </property>
+</bean> </programlisting>
+ </important>
</section>
<section>
<title>Using Spring XML</title>
+ <para>Spring like JBoss Microcontainer allows POJOs to be created and configured using an XML schema. As the microcontainer largely supports the same set of features as Spring it is possible to use the spring-beans schema to define beans instead of the bean-deployer schema. This makes migrating services built and tested using Spring to JBoss Microcontainer very straightforward.</para>
+ <para>To define beans using the spring-beans schema you need to include <code>spring-int.jar</code> on the microcontainer classpath. You can then create a deployment descriptor containing a <beans> element at the root instead of the usual <deployment> element:</para>
+ <programlisting><beans xmlns="urn:jboss:spring-beans:2.0">
+ <bean id="testBean" class="org.jboss.test.spring.support.SimpleBean">
+ <constructor-arg index="2">
+ <value>SpringBean</value>
+ </constructor-arg>
+ <constructor-arg index="0">
+ <value>1</value>
+ </constructor-arg>
+ <constructor-arg index="1">
+ <value>3.14159</value>
+ </constructor-arg>
+
+ <property name="mylist">
+ <list value-type="java.lang.String">
+ <value>onel</value>
+ <value>twol</value>
+ <value>threel</value>
+ </list>
+ </property>
+
+ <property name="myset">
+ <set value-type="java.lang.String">
+ <value>ones</value>
+ <value>twos</value>
+ <value>ones</value>
+ </set>
+ </property>
+
+ <property name="mymap">
+ <map key-type="java.lang.String">
+ <entry>
+ <key>
+ <value>test_key</value>
+ </key>
+ <value type="java.lang.String">myvalue</value>
+ </entry>
+ </map>
+ </property>
+ </bean>
+</beans></programlisting>
+ <para>The namespace declaration <code>xmlns="urn:jboss:spring-beans:2.0"</code> tells the microcontainer that it should interpret the XML according to the spring-bean schema.</para>
+ <para>You can even mix beans declared using the bean-deployer schema with those declared using the spring-beans schema just like we did with the javabean schema. All that you need to do is include the correct namespace declarations in the relevant elements:</para>
+ <itemizedlist>
+ <listitem>
+ <para>JBoss Microcontainer deployment containing Spring defined beans</para>
+ <programlisting><deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="oldBean" class="org.jboss.test.spring.support.OldBean">
+ <property name="testBean">
+ <inject/>
+ </property>
+ </bean>
+
+ <bean xmlns="urn:jboss:spring-beans:2.0" id="testBean" class="org.jboss.test.TestBean">
+ <property name="mylist">
+ <list value-type="java.lang.String">
+ <value>onel</value>
+ <value>twol</value>
+ <value>threel</value>
+ </list>
+ </property>
+ </bean>
+
+</deployment> </programlisting>
+ </listitem>
+ <listitem>
+ <para>Spring defined deployment containing JBoss Microcontainer beans</para>
+ <programlisting><beans xmlns="urn:jboss:spring-beans:2.0">
+
+ <bean id="testBean" class="org.jboss.test.spring.support.SimpleBean">
+ <property name="refBean">
+ <ref bean="oldBean"/>
+ </property>
+ </bean>
+
+ <bean xmlns="urn:jboss:bean-deployer:2.0" name="oldBean" class="org.jboss.test.spring.support.OldBean">
+ <property name="myString">I'm an old bean</property>
+ </bean>
+
+</beans></programlisting>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>Adding <code>spring-int.jar</code> to the microcontainer classpath simply adds the ability to define beans using the spring-beans XML schema. It does not integrate JBoss Microcontainer with Spring libraries.</para>
+ </note>
</section>
<section>
<title>Using Java Properties</title>
+ <para>Using XML schemas to create deployment descriptors provides us wth a powerful way to express complex configuration information. However the XML parsers that are needed to interpret this information are often large in size which doesn't help when bootstrapping the microcontainer in small runtime environments. For this reason you can also choose to create deployment descriptors using Java properties.</para>
</section>
</chapter>
<chapter>
More information about the jboss-cvs-commits
mailing list