[jboss-cvs] JBossAS SVN: r68240 - 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 12:01:52 EST 2007
Author: newtonm
Date: 2007-12-13 12:01:52 -0500 (Thu, 13 Dec 2007)
New Revision: 68240
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Started Injecting properties 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-13 17:01:44 UTC (rev 68239)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-13 17:01:52 UTC (rev 68240)
@@ -1451,7 +1451,7 @@
</section>
<section>
<title>Calling constructors</title>
- <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>
+ <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 declared in the constructor itself.</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>
@@ -1468,7 +1468,7 @@
<listitem>
<para>Constructor with parameters</para>
<programlisting>@Constructor
-public TestConstructorBean(String testString, int testNumber) {
+public TestConstructorBean(@StringValue("this is a test contructor") String testString, @StringValue("25") int testNumber) {
...
}</programlisting>
<programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
@@ -1485,7 +1485,7 @@
}
@Constructor
-public TestConstructorBean(String testString, long testNumber) {
+public TestConstructorBean(@StringValue("this is a test constructor") String testString, @StringValue(value="25", type="long") long testNumber) {
...
}</programlisting>
<programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
@@ -1520,7 +1520,7 @@
<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"))})
+ parameters={@Value(string=@StringValue("a string")), at Value(string=@StringValue("7"))})
public class SimpleBean {
...
}</programlisting>
@@ -1551,7 +1551,7 @@
<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"))})
+ parameters={@Value(string=@StringValue("a string")), at Value(string=@StringValue("7"))})
public class SimpleBean {
...
}</programlisting>
@@ -1573,7 +1573,7 @@
<programlisting>public class SimpleBean {
@FactoryMethod
- public static newInstance(String name, int level) {
+ public static newInstance(@StringValue("a string") String name, @StringValue("5") int level) {
...
}
}</programlisting>
@@ -1583,7 +1583,7 @@
<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>
+ <para>Note that the @FactoryMethod annotation doesn't have a parameter attribute as the parameters are declared in the method itself.</para>
</listitem>
</itemizedlist>
</section>
@@ -1604,7 +1604,7 @@
</listitem>
<listitem>
<para>Disabling System property replacement</para>
- <programlisting>@Aliases(value={"MyAlias", "Test: ${test.name}"} replace="false")
+ <programlisting>@Aliases({"MyAlias", "Test: ${test.name}"} replace="false")
public class SimpleBean {
...
}</programlisting>
@@ -1657,7 +1657,74 @@
<title>Injecting properties</title>
<section>
<title>Defining values</title>
- <para>Defining collections</para>
+ <para>Once a POJO instance has been created then it can be configured by injecting property values. Like most other features this can be done using either annotations or a deployment descriptor. For each property that you wish to inject the bean must define an appropriate setter method for the microcontainer to call.</para>
+ <programlisting>public class PropertiesBean {
+
+ public void setTitle(@StringValue("JBoss Microcontainer") String title) {
+ ...
+ }
+
+ public void setLink(@StringValue("http://www.jboss.org") URL link) {
+ ...
+ }
+
+ public void setNumber(@StringValue("4") int number) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <property name="title">JBoss Microcontainer</property>
+ <property name="link">http://www.jboss.org</property>
+ <property name="number">4</property>
+</bean> </programlisting>
+ <para>As you have probably noticed we are required to enter all of our values as strings since we are dealing with text files. These strings 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>. If the property takes an interface or abstract class then you can pass a specific implementation using a <code>type</code> or <code>class</code> attribute depending on whether you're using annotations or not.</para>
+ <programlisting>public class PropertiesBean {
+
+ public void setNumber(@StringValue(value="4", type="java.lang.Long") Number number) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <property name="number" class="java.lang.Long">4</property>
+</bean> </programlisting>
+ <para>Sometimes you may want to pass in a value that isn't of the same type as the property but can be progressed into it. Progression is typically used for converting numbers from one type to another, e.g. Short to Int or Float to Double. JBoss Microcontainer by default will automatically perform progression using a <code>SimpleProgressionConverter</code> implementation.</para>
+ <programlisting><bean name="SimpleBean" class="org.jboss.test.SimpleBean">
+ <property name="anInt">
+ <javabean xmlns="urn:jboss:javabean:2.0" class="java.lang.Double">
+ <constructor>
+ <property name="aDouble">123.456</property>
+ </constructor>
+ </javabean>
+ </property>
+ <property name="aShort">
+ <javabean xmlns="urn:jboss:javabean:2.0" class="java.lang.Float">
+ <constructor>
+ <property name="aFloat">987.6543</property>
+ </constructor>
+ </javabean>
+ </property>
+ <property name="aFloat">
+ <javabean xmlns="urn:jboss:javabean:2.0" class="java.lang.Integer">
+ <constructor>
+ <property name="anInt">314159</property>
+ </constructor>
+ </javabean>
+ </property>
+</bean></programlisting>
+ <para>You can replace the default progression converter implementation with one of your own by setting the <code>org.jboss.reflect.plugins.progressionConverter</code> system property using a fully-qualified class name. If you want to prevent progression from occuring altogether then you can use the <code>NullProgressionConverter</code> which is also provided.</para>
+ <programlisting>-Dorg.jboss.reflect.plugins.progressionConverter=org.jboss.reflect.plugins.NullProgressionConvertor</programlisting>
+ <para>If you want to use a null value then you need to use the @NullValue annotation or <null/> element. This is because we have to differentiate it from the string 'null'.</para>
+ <programlisting>example</programlisting>
+ <para>Similarly if you want to refer to the current object then you should use the @ThisValue annotation or <this/> element.</para>
+ <programlisting>example</programlisting>
+ <para>Property values can also be defined using a longer form of XML if you prefer.</para>
+ <programlisting><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <property name="number">
+ <value class="java.lang.Long">4</value>
+ </property>
+</bean> </programlisting>
+ <para>This is primarily used when configuring values representing collections such as lists, sets, maps and arrays.</para>
+ <para/>
</section>
<section>
<title>Calling methods</title>
More information about the jboss-cvs-commits
mailing list