[jboss-cvs] JBossAS SVN: r90082 - projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jun 11 07:10:53 EDT 2009
Author: kabir.khan at jboss.com
Date: 2009-06-11 07:10:53 -0400 (Thu, 11 Jun 2009)
New Revision: 90082
Modified:
projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/User_Guide.xml
Log:
Fix up the examples so that they match the actual annotations used. Add some more information about the different enum types used in the annotations.
Modified: projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/User_Guide.xml
===================================================================
--- projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/User_Guide.xml 2009-06-11 07:48:32 UTC (rev 90081)
+++ projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/User_Guide.xml 2009-06-11 11:10:53 UTC (rev 90082)
@@ -1190,11 +1190,13 @@
<itemizedlist>
<listitem>
<para>Default constructor</para>
- <programlisting role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean"/></programlisting>
+ <programlisting role="XML"><javabean xmlns="urn:jboss:javabean:2.0"
+ class="org.jboss.test.javabean.support.SimpleBean"/></programlisting>
</listitem>
<listitem>
- <para>Contructor with parameters</para>
- <programlisting role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <para>Constructor with parameters</para>
+ <programlisting role="XML"><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>
@@ -1204,14 +1206,16 @@
</listitem>
<listitem>
<para>Static factory method</para>
- <programlisting role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <programlisting role="XML"><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 role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <programlisting role="XML"><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>
@@ -1224,7 +1228,8 @@
<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 role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <programlisting role="XML"><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>
@@ -1232,14 +1237,16 @@
<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 role="XML"><javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.javabean.support.SimpleBean">
+ <programlisting role="XML"><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 role="XML"><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">
+ <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>
@@ -1304,7 +1311,8 @@
</property>
</bean>
- <bean xmlns="urn:jboss:spring-beans:2.0" id="testBean" class="org.jboss.test.TestBean">
+ <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>
@@ -1519,7 +1527,7 @@
</itemizedlist>
<para>You can also specify javabeans as parameters if required using the @JavaBeanValue annotation or <javabean> element. In this particular case the annotation is not very useful as it can only call the default constructor of the javabean class to create an instance. If you want to use a different constructor or inject properties then you should use the XML element instead.</para>
<programlisting role="JAVA">@Constructor
-public TestConstructorBean(@StringValue("this is a test constructor") String testString, @JavaBeanValue("org.jboss.test.Person") Person testPerson) {
+public TestConstructorBean(@StringValue("this is a test constructor") String testString, @JavaBeanValueorg.jboss.test.Person.class) Person testPerson) {
...
}</programlisting>
<programlisting role="XML"><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
@@ -1572,7 +1580,8 @@
<para>Static factory method with parameters</para>
<programlisting role="JAVA">@Factory (factoryClass="org.jboss.example.MyFactory",
factoryMethod="newInstance",
- parameters={@Value(string=@StringValue("a string")), at Value(string=@StringValue("7"))})
+ parameters={@Value(string=@StringValue("a string")),
+ @Value(string=@StringValue("7"))})
public class SimpleBean {
...
}</programlisting>
@@ -1586,7 +1595,7 @@
</listitem>
<listitem>
<para>Non-static factory method</para>
- <programlisting role="JAVA">@Factory (factory=@Value(javabean=@JavaBeanValue("org.jboss.example.MyOtherFactory")),
+ <programlisting role="JAVA">@Factory (factory=@Value(javabean=@JavaBeanValue(org.jboss.example.MyOtherFactory.class)),
factoryMethod="createBean")
public class SimpleBean {
...
@@ -1601,7 +1610,7 @@
</listitem>
<listitem>
<para>Non-static factory method with parameters</para>
- <programlisting role="JAVA">@Factory (factory=@Value(javabean=@JavaBeanValue("org.jboss.example.MyOtherFactory")),
+ <programlisting role="JAVA">@Factory (factory=@Value(javabean=@JavaBeanValue(org.jboss.example.MyOtherFactory.class)),
factoryMethod="createBean",
parameters={@Value(string=@StringValue("a string")), at Value(string=@StringValue("7"))})
public class SimpleBean {
@@ -1727,7 +1736,8 @@
...
}
}</programlisting>
- <programlisting role="XML"><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <programlisting role="XML"><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>
@@ -1738,7 +1748,8 @@
...
}
}</programlisting>
- <programlisting role="XML"><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <programlisting role="XML"><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>
@@ -1771,18 +1782,21 @@
<programlisting role="JAVA">public void setTitle(@NullValue String title) {
...
} </programlisting>
- <programlisting role="XML"><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <programlisting role="XML"><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 role="JAVA">public void setObject(@ThisValue Object target) {
...
} </programlisting>
- <programlisting role="XML"><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <programlisting role="XML"><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 role="XML"><bean name="PropertiesBean" class="org.jboss.example.microcontainer.properties.PropertiesBean">
+ <programlisting role="XML"><bean name="PropertiesBean"
+ class="org.jboss.example.microcontainer.properties.PropertiesBean">
<property name="number">
<value class="java.lang.Long">4</value>
</property>
@@ -1919,7 +1933,7 @@
</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>
+ <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, and any values defined in the annotations or xml deployment descriptor will be added to the exisiting values. 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>
@@ -1988,8 +2002,8 @@
<para>If you need to pass any parameters to the method then you can use multiple @Parameter annotations or nested <parameter> elements. </para>
<programlisting role="JAVA">@ValueFactory(bean="SimpleBean",
method="getFullName",
- parameters="{@Parameter(string=@StringValue("Bob")),
- @Parameter(string=@StringValue("Smith"))}")
+ parameters={@Parameter(string=@StringValue("Bob")),
+ @Parameter(string=@StringValue("Smith"))})
public void setName(String name) {
...
} </programlisting>
@@ -2004,7 +2018,7 @@
<para>Alternatively if only one parameter is required then you can use the <code>parameter</code> attribute to create a shorthand version. However this only works for values that can be created from strings.</para>
<programlisting role="JAVA">@ValueFactory(bean="SimpleBean",
method="getFullName",
- parameter="@Parameter(string=@StringValue("Bob"))")
+ parameter="Bob")
public void setName(String name) {
...
} </programlisting>
@@ -2064,7 +2078,7 @@
<title>Injecting context information</title>
<para>You may recall that inside the microcontainer each bean is represented by a context which holds amongst other things the bean's current state. This context information can be injected into bean properties or constructor/factory-method parameters using the @Inject annotation or <inject> element together with a <code>fromContext</code> attribute.</para>
<programlisting role="JAVA">@Inject(bean="otherBean",
- fromContext="beanInfo")
+ fromContext=FromContext.BEANINFO)
public void setBeanInfo(BeanInfo beanInfo) {
...
}</programlisting>
@@ -2074,7 +2088,7 @@
</property>
</bean></programlisting>
<para>If you want to inject information about the current bean's context then you can simply omit the <code>bean</code> attribute.</para>
- <programlisting role="JAVA">@Inject(fromContext="beanInfo")
+ <programlisting role="JAVA">@Inject(fromContext=FromContext.BEANINFO)
public void setBeanInfo(BeanInfo beanInfo) {
...
}</programlisting>
@@ -2083,7 +2097,8 @@
<inject fromContext="beaninfo"/>
</property>
</bean></programlisting>
- <para>The <code>fromContext</code> attribute can take the following values:</para>
+ <para>The <code>fromContext</code> attribute can take the following values from the
+ <code>org.jboss.beans.metadata.api.model.FromContext</code> enum:</para>
<itemizedlist>
<listitem>
<para>name - the name of the bean</para>
@@ -2132,21 +2147,23 @@
<property name="threadPool"><inject/></property>
</bean> </programlisting>
<para>By default the microcontainer will search for a bean whose class matches that of the parameter/property. However you can change this behaviour when auto-wiring properties so that the microcontainer searches for a bean whose name matches the property name. This is done using the <code>type</code> attribute of the <inject> element.</para>
- <programlisting role="JAVA">@Inject(type="ByName")
+ <programlisting role="JAVA">@Inject(type=AutowireType.By_NAME)
public void setThreadPool(ThreadPool pool) {
...
}</programlisting>
<programlisting role="XML"><bean name="propInj" class="com.acme.Example">
<property name="threadPool"><inject type="ByName"/></property>
</bean> </programlisting>
+ <para>The <code>org.jboss.beans.metadata.api.model.AutowireType</code> enum defines the valid values to use. <code>AutowireType.By_CLASS</code> is the default if using annotations, and <code>ByClass</code> the default when using xml.</para>
<para>If no match is found then by default the deployment will fail but for certain properties it may be acceptable for injection to occur after deployment. In these cases you can specify that a property should be set using a callback mechanism whenever a suitable bean becomes available. This is done using the <code>option</code> attribute.</para>
- <programlisting role="JAVA">@Inject(type="ByName", option="Callback")
+ <programlisting role="JAVA">@Inject(type=AutowireType.By_NAME, option=InjectOption.CALLBACK)
public void setThreadPool(ThreadPool pool) {
...
}</programlisting>
<programlisting role="XML"><bean name="propInj" class="com.acme.Example">
<property name="threadPool"><inject type="ByName" option="Callback"/></property>
</bean> </programlisting>
+ <para>The <code>org.jboss.beans.metadata.api.model.InjectOption</code> enum defines the valid values to use. <code>InjectOption.STRICT</code> is the default when using annotations, and <code>Strict</code> the default when using xml. Another possible value for <code>option</code> is <code>InjectOption.OPTIONAL</code> when using annotations, and <code>Optional</code> when using xml, if this option is used the dependency is injected if present at injection time, otherwise it is ignored.</para>
<para>Sometimes you may want to prevent a bean from being injected automatically using auto-wiring. In these situations you can set its <code>autowire-candidate</code> attribute to false so that it's not included in the search for matching beans. This is not currently possible using annotations as there is no annotation to declare a bean.</para>
<programlisting role="XML"><bean name="ignored" class="com.acme.Example" autowire-candidate="false" /></programlisting>
</section>
More information about the jboss-cvs-commits
mailing list