[jboss-cvs] JBossAS SVN: r68233 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Dec 13 09:17:04 EST 2007
Author: newtonm
Date: 2007-12-13 09:17:04 -0500 (Thu, 13 Dec 2007)
New Revision: 68233
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Added content for Creating POJOs.
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-13 11:32:59 UTC (rev 68232)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-13 14:17:04 UTC (rev 68233)
@@ -1451,13 +1451,206 @@
</section>
<section>
<title>Calling constructors</title>
- <para>Remember to describe annotations aswell as XML.</para>
+ <para>Creating POJO instances is performed either by calling a constructor or using a factory method. The <constructor> element is used in both cases and parameters can be passed if necessary using nested <parameter> elements. Annotations also exist for either case but the constructor annotation takes no parameters since these are already present in the constructor.</para>
+ <important>
+ <para>At present it is not possible to create a POJO instance only using annotations. This is because classes are not automatically loaded and scanned whenever they are added to the classpath. Doing so would significantly reduce the performance of the deployment process as all classes would need to be loaded, even if they were not yet required. Instead you must always define beans using a deployment descriptor as this tells the microcontainer which classes to load. These classes are subsequently scanned for annotations such as @Constructor and @Factory to discover how to create instances.</para>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean"/></programlisting>
+ </important>
+ <itemizedlist>
+ <listitem>
+ <para>Default constructor</para>
+ <programlisting>@Constructor
+public TestConstructorBean() {
+ ...
+}</programlisting>
+ <programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean"/> </programlisting>
+ </listitem>
+ <listitem>
+ <para>Constructor with parameters</para>
+ <programlisting>@Constructor
+public TestConstructorBean(String testString, int testNumber) {
+ ...
+}</programlisting>
+ <programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
+ <constructor>
+ <parameter>this is a test constructor</parameter>
+ <parameter>25</parameter>
+ </constructor>
+</bean></programlisting>
+ </listitem>
+ <listitem>
+ <para>Choosing between two constructors with the same number of parameters</para>
+ <programlisting>public TestConstructorBean(String testString, int testNumber) {
+ ...
+}
+
+ at Constructor
+public TestConstructorBean(String testString, long testNumber) {
+ ...
+}</programlisting>
+ <programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
+ <constructor>
+ <parameter>this is a test constructor</parameter>
+ <parameter class="long">25</parameter>
+ </constructor>
+</bean></programlisting>
+ <note>
+ <para>You only need to include the <code>class</code> attribute on enough parameters to resolve the ambiguity.</para>
+ </note>
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Using factories</title>
+ <para>If you have a choice of implementations for an interface then you may want to use a factory to create your POJO instances. JBoss Microcontainer provides support for static or non-static factory methods which can also take parameters if necessary.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Static factory method</para>
+ <programlisting>@Factory (factoryClass="org.jboss.example.MyFactory",
+ factoryMethod="newInstance")
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <constructor factoryMethod="newInstance"
+ factoryClass="org.jboss.example.MyFactory"/>
+</bean> </programlisting>
+ </listitem>
+ <listitem>
+ <para>Static factory method with parameters</para>
+ <programlisting>@Factory (factoryClass="org.jboss.example.MyFactory",
+ factoryMethod="newInstance",
+ parameters={@Value(string=@StringValue(value="a string")), at Value(string=@StringValue(value="7"))})
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <constructor factoryMethod="newInstance"
+ factoryClass="org.jboss.example.MyFactory">
+ <parameter>a string</parameter>
+ <parameter>7</parameter>
+ </constructor>
+</bean> </programlisting>
+ </listitem>
+ <listitem>
+ <para>Non-static factory method</para>
+ <programlisting>@Factory (factory=@Value(javabean=@JavaBeanValue("org.jboss.example.MyOtherFactory")),
+ factoryMethod="createBean")
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="MyOtherFactory" class="org.jboss.example.MyOtherFactory"/>
+
+<bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <constructor factoryMethod="createBean">
+ <factory bean="MyOtherFactory"/>
+ </constructor>
+</bean></programlisting>
+ </listitem>
+ <listitem>
+ <para>Non-static factory method with parameters</para>
+ <programlisting>@Factory (factory=@Value(javabean=@JavaBeanValue("org.jboss.example.MyOtherFactory")),
+ factoryMethod="createBean",
+ parameters={@Value(string=@StringValue(value="a string")), at Value(string=@StringValue(value="7"))})
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="MyOtherFactory" class="org.jboss.example.MyOtherFactory"/>
+
+<bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <constructor factoryMethod="createBean">
+ <factory bean="MyOtherFactory"/>
+ <parameter>a string</parameter>
+ <parameter>7</parameter>
+ </constructor>
+</bean></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>For the special case where a bean implements its own static factory method in order to create itself then you can also use a shorthand notation:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Bean implementing its own static factory method</para>
+ <programlisting>public class SimpleBean {
+
+ @FactoryMethod
+ public static newInstance(String name, int level) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <constructor factoryMethod="newInstance">
+ <parameter>a string</parameter>
+ <parameter>5</parameter>
+ </constructor>
+</bean> </programlisting>
+ <para>Note that the @FactoryMethod annotation doesn't have a parameter attribute as the parameters are already specified in the method.</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Creating bean aliases</title>
+ <para>By default each bean declared in the deployment descriptor has a unique name that is used to inject it into other beans or to provide a reference to clients at runtime. Sometimes however it is useful to define additional names or aliases. This can be done using the @Aliases annotation or <alias> XML element. System property replacement is used by default to change the value of the alias at runtime but you can disable this if required. </para>
+ <itemizedlist>
+ <listitem>
+ <para>Defining extra bean names</para>
+ <programlisting>@Aliases({"MyAlias", "Test: ${test.name}"})
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="MyBean" class="org.acme.SimpleBean">
+ <alias>MyAlias</alias>
+ <alias>Test: ${test.name}</alias>
+</bean></programlisting>
+ </listitem>
+ <listitem>
+ <para>Disabling System property replacement</para>
+ <programlisting>@Aliases(value={"MyAlias", "Test: ${test.name}"} replace="false")
+public class SimpleBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="MyBean" class="org.acme.SimpleBean">
+ <alias>MyAlias</alias>
+ <alias replace="false">Test: ${test.name}</alias>
+</bean></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>The type of an alias doesn't have to be a string. If you want to choose a different type then you can specify a <code>class</code> attribute in the <alias> XML element. At present you cannot do this using the @Aliases annotation.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Choosing a different alias type</para>
+ <programlisting><bean name="MyBean" class="org.acme.SimpleBean">
+ <alias class="java.lang.Integer">12345</alias>
+</bean></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>Sometimes you may wish to define an alias for a bean after it has been deployed. This can be done using the standalone <alias> element in the deployment descriptor. There is no equivalent annotation in this case as there is no sensible place to put it.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Defining a standalone alias</para>
+ <programlisting><deployment name="FirstDeployment" xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="Bean1" class="java.lang.Object"/>
+ <bean name="Bean2" class="java.lang.Object"/>
+
+</deployment>
+
+<deployment name="SecondDeployment" xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="Xyz1" class="java.lang.Object">
+ <property name="locker1"><inject name="Lock1"></property>
+ <property name="locker2"><inject name="Lock2"></property>
+ </bean>
+
+ <alias name="Bean1">Lock1</alias>
+ <alias name="Bean2">Lock2</alias>
+
+</deployment> </programlisting>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>Standalone aliases behave just like normal beans with respect to dependencies. Specifically they won't be deployed until the beans that they represent have been deployed first. Likewise when a bean is undeployed then any corresponding standalone aliases are undeployed first.</para>
+ <para>Furthermore if any beans depend on a standalone alias then they will not be deployed until the alias is deployed first. Similarly undeploying a standalone alias will cause all dependent beans to be undeployed, regardless of whether the bean that it represents remains deployed. </para>
+ </note>
</section>
</chapter>
<chapter>
More information about the jboss-cvs-commits
mailing list