[jboss-cvs] JBossAS SVN: r68279 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Dec 14 05:58:01 EST 2007
Author: newtonm
Date: 2007-12-14 05:58:01 -0500 (Fri, 14 Dec 2007)
New Revision: 68279
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Completed Using values 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-14 10:54:19 UTC (rev 68278)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-14 10:58:01 UTC (rev 68279)
@@ -1656,7 +1656,7 @@
<chapter>
<title>Injecting properties</title>
<section>
- <title>Defining values</title>
+ <title>Using values</title>
<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 {
@@ -1677,7 +1677,7 @@
<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>
+ <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 XML.</para>
<programlisting>public class PropertiesBean {
public void setNumber(@StringValue(value="4", type="java.lang.Long") Number number) {
@@ -1713,18 +1713,213 @@
</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>If you want to use a null value then you need to use the @NullValue annotation or <null/> element. This is so we can differentiate it from the string 'null'.</para>
+ <programlisting>public void setTitle(@NullValue String title) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <property name="title"><null/></property>
+</bean> </programlisting>
+ <para>Similarly if you want to refer to the current object then you should use the @ThisValue annotation or <this/> element.</para>
+ <programlisting>public void setObject(@ThisValue Object target) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <property name="target"><this/></property>
+</bean> </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/>
+ <para>This is primarily used when configuring values representing collections such as lists, sets and arrays. Elements of a collection are defined by listing annotations or nesting <value> elements as follows:</para>
+ <programlisting>@CollectionValue({@Value(string=@StringValue("string1")),
+ @Value(string=@StringValue("string2")),
+ @Value(string=@StringValue("string3")),
+ @Value(string=@StringValue("string4"))},
+ elementClass="java.lang.String")
+public void setCollection(Collection collection) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean"
+ class="org.jboss.example.SimpleBean">
+ <property name="collection">
+ <collection elementClass="java.lang.String">
+ <value>string1</value>
+ <value>string2</value>
+ <value>string3</value>
+ <value>string4</value>
+ </collection>
+ </property>
+</bean> </programlisting>
+ <para>The <code>elementClass</code> attribute specifies the default class for the values. This can be overriden for individual values using the <code>type</code> or <code>class</code> attributes.</para>
+ <programlisting>@CollectionValue({@Value(string=@StringValue("string1")),
+ @Value(string=@StringValue("string2")),
+ @Value(string=@StringValue(value="3.0", type="java.lang.Float")),
+ @Value(string=@StringValue(value="4", type="java.lang.Integer"))},
+ elementClass="java.lang.String")
+public void setCollection(Collection collection) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean"
+ class="org.jboss.example.SimpleBean">
+ <property name="collection">
+ <collection elementClass="java.lang.String">
+ <value>string1</value>
+ <value>string2</value>
+ <value class="java.lang.Float">3.0</value>
+ <value class="java.lang.Integer">4</value>
+ </collection>
+ </property>
+</bean> </programlisting>
+ <warning>
+ <para>The type of each value must be specified using either the <code>elementClass</code> or <code>type/class</code> attribute in order for the collection to be created.</para>
+ </warning>
+ <para>Lists, sets and arrays take the same form as the collection annotation and XML element. </para>
+ <programlisting>@ListValue({@Value(string=@StringValue("my first string")),
+ @Value(string=@StringValue("my second string"))},
+ elementClass="java.lang.String")
+public void setList(List list) {
+ ...
+}
+
+ at SetValue({@Value(string=@StringValue("50")),
+ @Value(string=@StringValue("55"))},
+ elementClass="java.lang.Integer")
+public void setSet(Set set) {
+ ...
+}
+
+ at ArrayValue({@Value(string=@StringValue("1.0")),
+ @Value(string=@StringValue("2.0"))},
+ elementClass="java.lang.Float")
+public void setArray(Object[] array) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean"
+ class="org.jboss.example.SimpleBean">
+ <property name="list">
+ <list elementClass="java.lang.String">
+ <value>my first string</value>
+ <value>my second string</value>
+ </list>
+ </property>
+
+ <property name="set">
+ <set elementClass="java.lang.Integer">
+ <value>50</value>
+ <value>55</value>
+ </set>
+ </property>
+
+ <property name="array">
+ <array elementClass="java.lang.Float">
+ <value>1.0</value>
+ <value>2.0</value>
+ </array>
+ </array>
+</bean> </programlisting>
+ <para>They can even be nested within one another if required. </para>
+ <programlisting>@ListValue({@Value(string=@StringValue("my first string")),
+ @Value(string=@SetValue({@Value(string=@StringValue("1")),
+ @Value(string=@StringValue="2"))},
+ elementClass="java.lang.Integer"))},
+ elementClass="java.lang.String")
+public void setList(List list) {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean"
+ class="org.jboss.example.SimpleBean">
+ <property name="list">
+ <list elementClass="java.lang.String">
+ <value>my first string</value>
+ <value>
+ <set elementClass="java.lang.Integer">
+ <value>1</value>
+ <value>2</value>
+ </set>
+ </value>
+ </list>
+ </property>
+</bean></programlisting>
+ <para>Maps can also be created using multiple entries of key/value pairs. As we now have two types to consider we must use the <code>keyClass</code> and <code>valueClass</code> attributes to specify the default classes for each entry. Again these can be overriden for individual entries if necessary.</para>
+ <programlisting>@MapValue(keyClass="java.lang.String",
+ valueClass="java.lang.String",
+ value={@EntryValue(key=@Value(string=@StringValue("foo.bar.key")),
+ value=@Value(string=@StringValue("QWERT"))),
+ @EntryValue(key=@Value(string=@StringValue("xyz.key")),
+ value=@Value(string=@StringValue("QWERTY")))
+ })
+public void setMap(Map<String, String> map) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <property name="map">
+ <map keyClass="java.lang.String" valueClass="java.lang.String">
+ <entry>
+ <key>foo.bar.key</key>
+ <value>QWERT</value>
+ </entry>
+ <entry>
+ <key>xyz.key</key>
+ <value>QWERTY</value>
+ </entry>
+ </map>
+ </property>
+</bean> </programlisting>
+ <para>So far we have defined collections, lists, sets, arrays and maps but all of these have multiple implementations, e.g. java.util.ArrayList, java.util.LinkedList, so which are we using at runtime? By default JBoss Microcontainer will look for an existing instance using the corresponding getter method for the property. If one is found then it is used. If not then the type of the property is analysed and providing that it represents a class (not an interface) then this is used to create a new instance. Failing that a default instance will be created as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Collection - java.util.ArrayList</para>
+ </listitem>
+ <listitem>
+ <para>List - java.util.ArrayList</para>
+ </listitem>
+ <listitem>
+ <para>Set - java.util.HashSet</para>
+ </listitem>
+ <listitem>
+ <para>Array - java.lang.Object[]</para>
+ </listitem>
+ <listitem>
+ <para>Map - java.util.HashMap</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you want to override this behaviour and specify your own class then you can simply add a <code>clazz</code> attribute to your annotation or <code>class</code> attribute to your XML element containing the fully-qualified class name. This causes the microcontainer to create a new instance using the specified class.</para>
+ <programlisting>@SetValue({@Value(string=@StringValue("50")),
+ @Value(string=@StringValue("55"))},
+ clazz="java.util.TreeSet",
+ elementClass="java.lang.Integer")
+public void setSet(Set set) {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean"
+ class="org.jboss.example.SimpleBean">
+ <property name="set">
+ <set class="java.util.TreeSet" elementClass="java.lang.Integer">
+ <value>50</value>
+ <value>55</value>
+ </set>
+ </property>
+</bean> </programlisting>
+ <note>
+ <para>If you don't specify a <code>clazz</code><code>/class</code> attribute but you want to ensure that a new instance is created then you can prevent the microcontainer from looking for a existing instance by specifying a <code>preinstantiate</code> attribute in the <property> element. Currently this cannot be achieved using annotations.</para>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <property name="list" preinstantiate="false">
+ <list elementClass="java.lang.String">
+ <value>string1</value>
+ <value>string2</value>
+ </list>
+ </property>
+</bean> </programlisting>
+ </note>
+ <note>
+ <para>If you want to define a <code>clazz</code><code>/class</code> attribute for an array then you must use the following syntax:</para>
+ <para> <code>[L</code><emphasis><fully-qualified class name></emphasis><code>;</code></para>
+ <para>e.g. an array of strings - [Ljava.lang.String;</para>
+ <para>or an array of integers - [Ljava.lang.Integer;</para>
+ </note>
</section>
<section>
<title>Calling methods</title>
More information about the jboss-cvs-commits
mailing list