[jboss-cvs] JBossAS SVN: r68374 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Dec 18 05:55:45 EST 2007
Author: newtonm
Date: 2007-12-18 05:55:45 -0500 (Tue, 18 Dec 2007)
New Revision: 68374
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Finished 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-18 08:58:04 UTC (rev 68373)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-18 10:55:45 UTC (rev 68374)
@@ -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 declared in the constructor itself.</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 with parameter values represented as annotations of the constructor parameters themselves.</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>
@@ -1499,10 +1499,44 @@
</note>
</listitem>
</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>@Constructor
+public TestConstructorBean(@StringValue("this is a test constructor") String testString, @JavaBeanValue("org.jboss.test.Person") Person testPerson) {
+ ...
+}</programlisting>
+ <programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
+ <constructor>
+ <parameter>this is a test constructor</parameter>
+ <parameter>
+ <javabean xmlns="urn:jboss:javabean:2.0" class="org.jboss.test.Person">
+ <constructor>
+ <property name="age">21</property>
+ </constructor>
+ <property name="firstName">Mark</property>
+ <property name="lastName">Newton</property>
+ </javabean>
+ </parameter>
+ </constructor>
+</bean></programlisting>
+ <para>Finally you can inject references to other beans or their properties into constructor parameters giving you complete control of the construction of your POJOs.</para>
+ <programlisting>@Constructor
+public TestConstructorBean(@Inject(bean="TestPerson") Person testPerson, @Inject(bean="TestAddress", property="street") String street) {
+ ...
+}</programlisting>
+ <programlisting><bean name="Test" class="org.jboss.example.constructor.TestConstructorBean">
+ <constructor>
+ <parameter>
+ <inject bean="TestPerson"/>
+ </parameter>
+ <parameter>
+ <inject bean="TestAddress" property="street"/>
+ </parameter>
+ </constructor>
+</bean></programlisting>
</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>
+ <para>If you have a number of classes that share the same 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>
@@ -1512,8 +1546,8 @@
...
}</programlisting>
<programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
- <constructor factoryMethod="newInstance"
- factoryClass="org.jboss.example.MyFactory"/>
+ <constructor factoryClass="org.jboss.example.MyFactory"
+ factoryMethod="newInstance"/>
</bean> </programlisting>
</listitem>
<listitem>
@@ -1525,8 +1559,8 @@
...
}</programlisting>
<programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
- <constructor factoryMethod="newInstance"
- factoryClass="org.jboss.example.MyFactory">
+ <constructor factoryClass="org.jboss.example.MyFactory"
+ factoryMethod="newInstance">
<parameter>a string</parameter>
<parameter>7</parameter>
</constructor>
@@ -1583,9 +1617,12 @@
<parameter>5</parameter>
</constructor>
</bean> </programlisting>
- <para>Note that the @FactoryMethod annotation doesn't have a parameter attribute as the parameters are declared in the method itself.</para>
+ <para>Note that the @FactoryMethod annotation doesn't have a parameter attribute as the method parameters themselves are annotated.</para>
</listitem>
</itemizedlist>
+ <note>
+ <para>Factory method parameters can also be configured using JavaBeans and injected bean references if necessary just like constructor parameters. </para>
+ </note>
</section>
<section>
<title>Creating bean aliases</title>
@@ -1842,11 +1879,11 @@
<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")))
- })
+ {@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>
@@ -1919,16 +1956,181 @@
</section>
<section>
<title>Calling methods</title>
- <para>Value-factory</para>
+ <para>Using PropertyEditors to create instances of objects from strings is fine in many situations but sometimes you need to inject a return value from a method call. As the method is responsible for creating the value we refer to it as a value factory. Hence the @ValueFactory annotation or <value-factory> element can be used in place of @StringValue or <value> to call a method and inject the returned value during deployment.</para>
+ <programlisting>@ValueFactory(bean="SimpleBean",
+ method="getFullName")
+public void setName(String name) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropHolder" class="org.jboss.test.kernel.config.support.PropHolder">
+ <property name="name">
+ <value-factory bean="SimpleBean" method="getFullName"/>
+ </property>
+</bean> </programlisting>
+ <para>If you need to pass any parameters to the method then you can use multiple @Parameter annotations or nested <parameter> elements. </para>
+ <programlisting>@ValueFactory(bean="SimpleBean",
+ method="getFullName",
+ parameters="{@Parameter(string=@StringValue("Bob")),
+ @Parameter(string=@StringValue("Smith"))}")
+public void setName(String name) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropHolder" class="org.jboss.test.kernel.config.support.PropHolder">
+ <property name="name">
+ <value-factory bean="SimpleBean" method="getFullName">
+ <parameter>Bob</parameter>
+ <parameter>Smith</parameter>
+ </value-factory>
+ </property>
+</bean> </programlisting>
+ <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>@ValueFactory(bean="SimpleBean",
+ method="getFullName",
+ parameter="@Parameter(string=@StringValue("Bob"))")
+public void setName(String name) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropHolder" class="org.jboss.test.kernel.config.support.PropHolder">
+ <property name="name">
+ <value-factory bean="SimpleBean" method="getFullName" parameter="Bob"/>
+ </property>
+</bean> </programlisting>
+ <para>It is also possible to specify a default value to use in case the method returns null. This is done using the <code>defaultValue</code>/<code>default</code> attribute which like the <code>parameter</code> attribute only accepts values created using strings. </para>
+ <programlisting>@ValueFactory(bean="SimpleBean",
+ method="getFullName",
+ defaultValue="Mark Newton")
+public void setName(String name) {
+ ...
+} </programlisting>
+ <programlisting><bean name="PropHolder" class="org.jboss.test.kernel.config.support.PropHolder">
+ <property name="name">
+ <value-factory bean="SimpleBean" method="getFullName" default="Mark Newton"/>
+ </property>
+</bean> </programlisting>
</section>
<section>
<title>Using bean references</title>
+ <para>Injecting string-based properties or the return values of method calls into individual beans allows us to perform simple configurations. To create more complex configurations we need to wire beans together by injecting references using the @Inject annotation or <inject> element. </para>
+ <programlisting>@Inject(bean = "Name1")
+public void setSimpleBean(SimpleBean bean) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.test.SimpleBean">
+ <property name="simpleBean">
+ <inject bean="Name1"/>
+ </property>
+</bean></programlisting>
+ <para>Bean injections can be used anywhere a string value is used but you must ensure that the type of bean being injected is compatible with the type of property being set. It is also possible to inject a property from one bean into another using the <code>property</code> attribute.</para>
+ <programlisting>@Inject(bean = "Name1", property="age")
+public void setAge(Integer age) {
+ ...
+} </programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.test.SimpleBean">
+ <property name="age">
+ <inject bean="Name1" property="age"/>
+ </property>
+</bean></programlisting>
+ <para>Although injection is simple to use it provides a very powerful way to create arbitrary relationships between POJO instances. The dependencies that are formed by these relationships are discussed in the next chapter 'Defining Dependencies'.</para>
+ <note>
+ <para>Sometimes you may wish to declare a bean simply so that you can inject it into a single property. In this case you can replace the <inject> element with the bean declaration itself to reduce the amount of XML required. This is not possible using annotations as there is no annotation to declare a bean.</para>
+ <programlisting><bean name="SimpleBean" class="org.jboss.test.SimpleBean">
+ <property name="testBean">
+ <bean="TestBean" class="org.jboss.test.TestBean">
+ <property name="age">25</property>
+ </bean>
+ </property>
+</bean></programlisting>
+ </note>
</section>
<section>
<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>@Inject(bean="otherBean",
+ fromContext="beanInfo")
+public void setBeanInfo(BeanInfo beanInfo) {
+ ...
+}</programlisting>
+ <programlisting><bean name="sndBean" class="org.jboss.test.NameAwareBean">
+ <property name="beaninfo">
+ <inject bean="otherBean" fromContext="beaninfo"/>
+ </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>@Inject(fromContext="beanInfo")
+public void setBeanInfo(BeanInfo beanInfo) {
+ ...
+}</programlisting>
+ <programlisting><bean name="sndBean" class="org.jboss.test.NameAwareBean">
+ <property name="beaninfo">
+ <inject fromContext="beaninfo"/>
+ </property>
+</bean></programlisting>
+ <para>The <code>fromContext</code> attribute can take the following values:</para>
+ <itemizedlist>
+ <listitem>
+ <para>name - the name of the bean</para>
+ </listitem>
+ <listitem>
+ <para>aliases - a list of the bean's other names</para>
+ </listitem>
+ <listitem>
+ <para>metadata - information about the bean from annotations or deployment descriptors</para>
+ </listitem>
+ <listitem>
+ <para>beaninfo - information about the bean from the bean class</para>
+ </listitem>
+ <listitem>
+ <para>scope - the microcontainer scope that the bean belongs to</para>
+ </listitem>
+ <listitem>
+ <para>id - the internal id of the bean within the microcontainer</para>
+ </listitem>
+ <listitem>
+ <para>context - the bean context</para>
+ </listitem>
+ </itemizedlist>
+ <important>
+ <para>All context information is wrapped into unmodifiable objects to prevent the user from changing anything outside of the microcontainer's control. </para>
+ </important>
</section>
<section>
<title>Auto-wiring</title>
+ <para>Having to write large amounts of configuration information just to wire together sometimes trivial beans can often be frustrating. For this reason JBoss Microcontainer provides the ability to autowire beans. Auto-wiring means that a bean's properties or constructor/factory-method parameters are set by automatically searching for matching beans. The benefit is that you don't have to specify the names of the beans to inject yourself but the drawback is that this only works reliably for small environments. If you have an environment where more than one bean matches the property or parameter being set then it becomes unclear from the configuration information which one will be chosen during deployment. </para>
+ <para>To use auto-wiring you simply need to specify an @Inject annotation or <inject> element without a <code>bean</code> attribute for the parameter or property that you wish to set.</para>
+ <programlisting>@Inject
+public class Example(ThreadPool pool) {
+ ...
+}</programlisting>
+ <programlisting><bean name="paramInj" class="com.acme.Example">
+ <constructor>
+ <parameter name="threadPool"><inject/></parameter>
+ </constructor>
+</bean> </programlisting>
+ <programlisting>@Inject
+public void setThreadPool(ThreadPool pool) {
+ ...
+}</programlisting>
+ <programlisting><bean name="propInj" class="com.acme.Example">
+ <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>@Inject(type="ByName")
+public void setThreadPool(ThreadPool pool) {
+ ...
+}</programlisting>
+ <programlisting><bean name="propInj" class="com.acme.Example">
+ <property name="threadPool"><inject type="ByName"/></property>
+</bean> </programlisting>
+ <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>@Inject(type="ByName", option="Callback")
+public void setThreadPool(ThreadPool pool) {
+ ...
+}</programlisting>
+ <programlisting><bean name="propInj" class="com.acme.Example">
+ <property name="threadPool"><inject type="ByName" option="Callback"/></property>
+</bean> </programlisting>
+ <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><bean name="ignored" class="com.acme.Example" autowire-candidate="false" /></programlisting>
</section>
</chapter>
<chapter>
More information about the jboss-cvs-commits
mailing list