<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
      "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1>
   <title>Basic Configuration and Usage</title>

   <para>The Microcontainer's main purpose is to allow external configuration of
      POJOs. As we have seen in
      <xref linkend="examples"/>
      , the POJOs in a Microcontainer applications are nothing special. The key element that drives
      the application is the
      <varname>jboss-beans.xml</varname>
      configuration file.
      So, in this chapter, we will look at the some of the common configurations in
      <varname>jboss-beans.xml</varname>
      .
   </para>

   <sect2>
      <title>Deployment</title>

      <para>The
         <varname>deployment</varname>
         element acts as a container for many beans that are deployed together.
      </para>

      <programlisting>
<![CDATA[

         <?xml version="1.0" encoding="UTF-8"?>

         <!-- Deployment holds beans -->
         <deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_2_0.xsd"
            xmlns="urn:jboss:bean-deployer:2.0">

         <!-- bean part of the deployment -->
         <bean .../>

         <!-- bean part of the deployment -->
         <bean .../>

         </deployment>

]]>
   </programlisting>

   </sect2>

   <sect2>
      <title>Bean</title>

      <para>The
         <varname>bean</varname>
         element is the main deployment component. It describes a single managed object in the runtime.
      </para>

      <programlisting>
<![CDATA[

         <deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_2_0.xsd"
            xmlns="urn:jboss:bean-deployer:2.0">

         <bean name="Simple"
            class="org.jboss.example.microcontainer.simple.SimpleBean"/>

         </deployment>

]]>
      </programlisting>

      <para>The example above from the
         <varname>simple</varname>
         example uses the default constructor of
         <varname>SimpleBean</varname>
         to create a new POJO.
      </para>

      <programlisting>
         new org.jboss.example.microcontainer.simple.SimpleBean();
      </programlisting>

      <para>It is given the name
         <varname>"Simple"</varname>
         such that it can be referenced elsewhere.
      </para>
   </sect2>

   <sect2>
      <title>Construction</title>

      <para>The example above uses the default constructor. What if you want to use some other constructor? The
         simplest mechanism just matches the number of parameters in the constructor. The example below is from the
         <varname>constructor</varname>
         example.
      </para>

      <programlisting>
<![CDATA[

   public class ConstructorBean
   {
      ... ...

      public ConstructorBean(int integer)
      {
         ... ...
      }
   }
]]>
      </programlisting>

      <para>The
         <varname>jboss-beans.xml</varname>
         element for creating the POJO using the above constructor is as follows.
      </para>

      <programlisting>
<![CDATA[

   <bean name="Integer"
      class="org.jboss.example.microcontainer.constructor.ConstructorBean">

      <constructor>
         <parameter>4</parameter>
      </constructor>
   </bean>

]]>
      </programlisting>

      <para>The microcontainer would just use the following to create the
         <varname>Integer</varname>
         named component.
      </para>

      <programlisting>
         new ConstructorBean (4);
      </programlisting>

      <para>Sometimes there are two constructors with the same number of parameters. In this case, you must specify the
         types to resolve the ambiguity.
      </para>

      <programlisting>
         public class ConstructorBean {
         public ConstructorBean(String string, int integer) {}
         public ConstructorBean(String string, long long) {}
         }
      </programlisting>

      <para>The following configuration creates a managed bean instance named
         <varname>StringLong</varname>
         using the second constructor listed above.
      </para>

      <programlisting>
<![CDATA[

   <bean name="StringLong"
      class="org.jboss.example.microcontainer.constructor.ConstructorBean">

      <constructor>
         <parameter>a string</parameter>
         <parameter class="long">10</parameter>
      </constructor>
   </bean>

]]>
      </programlisting>

      <para>Behind the scene, the Micorcontainer invokes:</para>

      <programlisting>
         new ConstructorBean ("a string", (long) 10);
      </programlisting>

      <para>Note that you only have to be explicit enough to resolve the ambiguity.</para>

   </sect2>

   <sect2>
      <title>Factories</title>

      <para>Not all classes have pubic constructors. It is often good practice to use factories when you to have a
         choice of implementation for an interface. The microcontainer includes support for the several different types
         of factory. The simplest case is a static factory class with a static factory method like the following from
         the
         <varname>factory</varname>
         example.
      </para>

      <programlisting>
<![CDATA[

   public class StaticFactory
   {
      public static FactoryCreatedBean createBean()
      {
         return new FactoryCreatedBean("StaticFactory.createBean()");
      }
   }

]]>
      </programlisting>

      <para>The bean configuration tells the microcontainer to the use the
         <varname>StaticFactory.createBean()</varname>
         static method to create an instance of
         <varname>FactoryCreatedBean</varname>
         .
      </para>

      <programlisting>
<![CDATA[

   <bean name="StaticFactoryCreatedBean"
      class="org.jboss.example.microcontainer.factory.FactoryCreatedBean">

      <constructor factoryMethod="createBean"
         factoryClass="org.jboss.example.microcontainer.factory.StaticFactory"/>

   </bean>

]]>
      </programlisting>

      <para>Of course, the factory class itself does not have to be static. The microcontainer can create a non-static
         factory itself as a managed object, and then use this factory object to create other bean objects. For
         instance, the
         <varname>factory</varname>
         example contains a singleton factory class example.
      </para>

      <programlisting>
<![CDATA[

   public class SingletonFactory
   {
      private static SingletonFactory singleton;

      public synchronized static SingletonFactory getInstance()
      {
         if (singleton == null)
            singleton = new SingletonFactory();

         return singleton;
      }

      public FactoryCreatedBean createBean()
      {
         return new FactoryCreatedBean("SingletonFactory.createBean()");
      }

      private SingletonFactory()
      {
         System.out.println("SingletonFactory()");
      }
   }

]]>
      </programlisting>

      <para>In the following configuration, we first create an instance of the
         <varname>SingletonFactory</varname>
         class under the name
         <varname>"SingletonFactory"</varname>
         using the
         <varname>SingletonFactory.getInstance()</varname>
         static method. Then, we use this factory object to create a
         <varname>FactoryCreatedBean</varname>
         instance under the name
         <varname>SingletonFactoryCreatedBean</varname>
         .
      </para>

      <programlisting>
<![CDATA[

   <bean name="SingletonFactory"
      class="org.jboss.example.microcontainer.factory.SingletonFactory">

      <constructor factoryMethod="getInstance"
         factoryClass="org.jboss.example.microcontainer.factory.SingletonFactory"/>

   </bean>

   <bean name="SingletonFactoryCreatedBean"
      class="org.jboss.example.microcontainer.factory.FactoryCreatedBean">

      <constructor factoryMethod="createBean">
         <factory bean="SingletonFactory"/>
      </constructor>

   </bean>

]]>
      </programlisting>

      <para>Like the constructor method we mentioned before, the factory method can also take call parameters via the
         nested
         <varname>parameter</varname>
         element.
      </para>

   </sect2>

   <sect2>
      <title>Properties</title>

      <para>It is possible to create all objects using factories and constructors, however many people use the JavaBean
         or MBean convention where an object is constructed using a default constructor and then configured using
         properties or attributes (i.e., setter methods). The following class from the
         <varname>properties</varname>
         example is a JavaBean style POJO.
      </para>

      <programlisting>
<![CDATA[

   public class PropertiesBean
   {
      public PropertiesBean()
      {
         System.out.println("PropertiesBean()");
      }

      public void setTitle(String title)
      {
         System.out.println("setTitle: " + title);
      }

      public void setSubTitle(String subTitle)
      {
         System.out.println("setSubTitle: " + subTitle);
      }

      public void setLink(URL url)
      {
         System.out.println("setLink: " + url);
      }

      public void setNumber(Number number)
      {
         System.out.println("setNumber: " + number + " type=" + number.getClass().getName());
      }
   }

]]>
      </programlisting>

      <para>The configuration creates the
         <varname>PropertiesBean</varname>
         instance and then uses the setter methods to set its properties.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PropertiesBean"
      class="org.jboss.example.microcontainer.properties.PropertiesBean">

      <property name="title">JBoss Microcontainer property example</property>
      <property name="subTitle"><null/></property>
      <property name="link">http://www.jboss.org</property>
      <property name="number" class="java.lang.Long">4</property>
   </bean>

]]>
      </programlisting>

      <para>Here we use the string representation of various objects, including the
         <varname>null</varname>
         value. They will be discussed in more detail in the next section.
      </para>

   </sect2>

   <sect2>
      <title>String Values</title>

      <para>Now, you probably noticed that we use string values to represent all kinds of objects in the
         <varname>parameter</varname>
         element for the constructors or factory methods, and in the
         <varname>property</varname>
         element for JavaBean properties.
      </para>

      <para>In the most generic case, a JavaBean
         <ulink url="http://java.sun.com/j2se/1.4.2/docs/api/java/beans/PropertyEditor.html">PropertyEditor</ulink>
         can be used to convert a string to a specific type. JBoss already provides a large number of property editors
         for standard types. Please see the example below for the POJO class, the configuration, and the resultant
         Microcontainer action.
      </para>

      <programlisting>
<![CDATA[

   import java.beans.PropertyEditorSupport;

   public class URLEditor extends PropertyEditorSupport
   {
      public void setAsText(final String text)
      {
         setValue(new URL(text));
      }
   }

   public class Example
   {
      public URL getLink() {}

      public void setLink(URL url) {}

   }

   <bean name="Name1" class=com.acme.Example">
      <property name="link">http://acme.com/index.html</property>
   </bean>

   Example example = new com.acme.Example();
   PropertyEditor editor = PropertyEditorManager.findEditor(URL.class);
   editor.setAsText("http://acme.com/index.html");
   example.setLink((URL)editor.getValue());

]]>
      </programlisting>

      <para>Often the property takes an interface or abstract class, but you want to pass a specific implementation or a
         subclass. That is easy. Just specify the implementation class in the
         <varname>property.class</varname>
         attribute as show below.
      </para>

      <programlisting>
<![CDATA[

   public class Example
   {
         public Number getNumber() {}

         public void setNumber(Number number) {}

   }

   <bean name="Name1" class=com.acme.Example">
      <property name="number" class="java.lang.Long">4</property>
   </bean>

   Example example = new com.acme.Example();
   example.setNumber(new Long(4));

]]>
      </programlisting>


      <para>There is also a more long-winded form of value that we will see later when configuring collections.</para>

      <programlisting>
<![CDATA[

   public class Example
   {
      public Number getNumber() {}

      public void setNumber(Number number) {}

   }

   <bean name="Name1" class=com.acme.Example">
      <property name="number">
         <value class="java.lang.Long">4</value>
      </property>
   </bean>

   Example example = new com.acme.Example();
   example.setNumber(new Long(4));

]]>
      </programlisting>


      <para>Finally, the
         <varname>null</varname>
         value is trivial, <varname><![CDATA[<null/>]]></varname>. But, it needs to differentiated from the string "null". Please see the example
         below for the usage.
      </para>

      <programlisting>
<![CDATA[

   public class Example
   {
         public String getTitle() {}

         public void setTitle(String string) {}

   }

   <!-- Wrong -->
   <bean name="Name1" class=com.acme.Example">
      <property name="title">null</property>
   </bean>

   Example example = new com.acme.Example();
   example.setTitle(new String("null"));

   <!-- Correct -->
   <bean name="Name1" class=com.acme.Example">
      <property name="title"><null/></property>
   </bean>

   Example example = new com.acme.Example();
   example.setTitle(null);

]]>
      </programlisting>

      <para>Sometimes it is still useful to be able to set or inject a value which can be morphed / progressed into
         the needed type although the existing type is not compatible (normally getting <varname>ClassCastException</varname>). This is mostly true
         for <varname>java.lang.Number</varname> subclasses. Let's see how <varname>progression</varname> is used in the following example
         (here we use <varname><![CDATA[<inject />]]></varname>, which is actually explained in the next chapter).
      </para>

      <programlisting>
<![CDATA[

   <bean name="FromBean" class="org.jboss.test.kernel.config.support.SimpleBean">
      <property name="adouble">123.456</property>
      <property name="AFloat" class="java.lang.Float">987.6543</property>
      <property name="anInt">314159</property>
   </bean>

   <bean name="SimpleBean" class="org.jboss.test.kernel.config.support.SimpleBean">
      <property name="anint">
         <inject bean="FromBean" property="adouble" />
      </property>

      <property name="AShort">
         <inject bean="FromBean" property="AFloat" />
      </property>

      <property name="AFloat">
         <inject bean="FromBean" property="anInt" />
      </property>
   </bean>

]]>
      </programlisting>

      <para>SimpleBean is a plain JavaBean, property names reflect the field type: having a<varname>double</varname>
         property name means that a field is of type double. A<varname>Float</varname> corresponds to Float type. Etc.
      </para>

      <para>You can change the progression behavior by setting the System property
         <varname>org.jboss.reflect.plugins.progressionConvertor</varname>,
         putting the ProgressionConvertor's implementation fully qualified class name as value.
         By default the SimpleProgressionConvertor implementation is used. Another existing implementation is
         NullProgressionConvertor, which doesn't do any actual progression.
      </para>

   </sect2>

   <sect2>
      <title>Injections</title>

      <para>Objects by themself are not very useful. They need to be linked together to form more complicated data
         structures. We have already seen one form of injection when using factory instances above. Injections can be
         used anywhere a string value is used. All the examples that we have previously seen with strings could also be
         done with injections.
      </para>

      <para>The
         <varname>injection</varname>
         example shows how dependency injection works in JBoss Microcontainer. The
         <varname>InjectionBean</varname>
         class has a
         <varname>host</varname>
         property, which is the
         <varname>java.net.URL</varname>
         type. We will inject an URL object into the bean via the microcontainer.
      </para>

      <programlisting>
<![CDATA[

   public class InjectionBean
   {
      String name;

      public InjectionBean(String name)
      {
         this.name = name;
         System.out.println("InjectionBean() " + this);
      }

      public String toString()
      {
         return name;
      }

      public void setHost(String host)
      {
         System.out.println("setHost: " + host + " on " + this);
      }

      public void setOther(InjectionBean other)
      {
         System.out.println("setOther: " + other + " on " + this);
      }
   }

]]>
      </programlisting>

      <para>The microcontainer creates the
         <varname>URL</varname>
         object first, and then passes the
         <varname>URL</varname>
         object as a property into the
         <varname>InjectionBean1</varname>
         object when it is instantiated.
      </para>

      <programlisting>
<![CDATA[

   <bean name="URL" class="java.net.URL">
      <constructor>
         <parameter>http://www.jboss.org/index.html</parameter>
      </constructor>
   </bean>

   <bean name="InjectionBean1"
      class="org.jboss.example.microcontainer.injection.InjectionBean">

      <constructor>
         <parameter>InjectionBean1</parameter>
      </constructor>

      <property name="host">
         <inject bean="URL" property="host"/>
      </property>
   </bean>

]]>
      </programlisting>


      <para>The order of the
         <varname>bean</varname>
         elements does not matter. The microcontainer orders the beans into the correct order. For instance, in the
         above example, the
         <varname>URL</varname>
         object is always created before the
         <varname>InjectionBean1</varname>
         object since the latter is dependent on the former. But that leaves the problem of how to resolve circular
         dependencies. These can be resolved by specifying when you want the injection to occur. In the example below we
         say once
         <varname>Circular1</varname>
         is "Instantiated" (constructed) it is ok to configure it on
         <varname>Circular2</varname>
         . Normally, injections wait for the referenced bean to reach the state "Installed" (see later on life cycles).
      </para>

      <programlisting>
<![CDATA[

   <bean name="Circular1"
      class="org.jboss.example.microcontainer.injection.InjectionBean">

      <constructor>
         <parameter>Circular1</parameter>
      </constructor>

      <property name="other">
         <inject bean="Circular2"/>
      </property>

   </bean>

   <bean name="Circular2"
      class="org.jboss.example.microcontainer.injection.InjectionBean">

      <constructor>
         <parameter>Circular2</parameter>
      </constructor>

      <property name="other">
         <inject bean="Circular1" state="Instantiated"/>
      </property>
   </bean>

]]>
      </programlisting>

      <para>Here is the order the microcontainer instantiates those objects.</para>

      <programlisting>
<![CDATA[

   InjectionBean Circular1 = new InjectionBean ();
   InjectionBean Circular2 = new InjectionBean ();
   Circular1.setOther(Circular2); // don't wait for a fully configured Circular1
   Circular2.setOther(Circular1); // Complete the confguration of Circular2

]]>
      </programlisting>

   </sect2>

   <sect2>
      <title>Value Factory</title>

      <para>Similar to using <varname>inject</varname>'s property attribute, we sometimes want to use other beans to
         create new values from bean's multi parameter methods.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PropHolder" 
     class="org.jboss.test.kernel.config.support.PropHolder">
      <property name="value">
         <value-factory bean="ldap" method="getValue">
            <parameter>xyz.key</parameter>
            <parameter>xyz</parameter>
            <parameter>
               <bean name="t" 
                 class="org.jboss.test.kernel.config.support.TrimTransformer"/>
            </parameter>
         </value-factory>
      </property>
   </bean>

   <bean name="ldap" class="org.jboss.test.kernel.config.support.LDAPFactory">
      <constructor>
         <parameter>
            <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>QWERT</value>
               </entry>

            </map>

         </parameter>
      </constructor>
   </bean>

]]>
      </programlisting>

      <para>For the quick usage there is also shorthand version of the value-factory element, having single parameter
         as string attribute.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PropHolder" 
     class="org.jboss.test.kernel.config.support.PropHolder">
      <constructor>
         <parameter>
            <value-factory bean="ldap" method="getValue" parameter="foo.bar.key"/>
         </parameter>
      </constructor>
   </bean>

]]>
      </programlisting>

      <para>You can also define a default value for the value-factory return value.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PropHolder" 
     class="org.jboss.test.kernel.config.support.PropHolder">
      <property name="list">
         <list elementClass="java.lang.String">
            <value-factory bean="ldap" method="getValue" default="QWERT">
               <parameter>no.such.key</parameter>
            </value-factory>
         </list>
      <property>
   </bean>

]]>
      </programlisting>

   </sect2>

   <sect2>
      <title>Collections</title>

      <para>The
         <varname>collection</varname>
         ,
         <varname>list</varname>
         ,
         <varname>set</varname>
         and
         <varname>array</varname>
         elements are used to enclose collection of values to pass to the bean components as properties or constructor
         (factory method) parameters. The default types are:
      </para>

      <itemizedlist mark="bullet">
         <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>
      </itemizedlist>

      <para>They all take the same form. So, only
         <varname>list</varname>
         is shown here in those examples. You just need to nest
         <varname>value</varname>
         elements inside the collection element to specify the contents of the collection. Please note that an
         <varname>"elementClass"</varname>
         attribute is required on the collection element, unless you specify explicit types on all the
         <varname>value</varname>s.
      </para>

      <para>Below is a sample configuration from the
         <varname>collections</varname>
         example. It sets a
         <varname>List</varname>
         with two elements of mixed types to the
         <varname>ObjectPrinter.print</varname>
         property on the
         <varname>PrintList</varname>
         named object.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PrintList"
      class="org.jboss.example.microcontainer.collections.ObjectPrinter">

      <constructor>
         <parameter>List</parameter>
      </constructor>

      <property name="print">
         <list elementClass="java.lang.String">
            <value>Value of type elementClass</value>
            <value class="java.lang.Integer">4</value>
         </list>
      </property>
   </bean>

]]>
      </programlisting>

      <para>It is also possible to use a
         <varname>List</varname>
         as an element inside another
         <varname>List</varname>
         . Here is an example.
      </para>

      <programlisting>
<![CDATA[

   <bean name="Name1" class="com.acme.Example">
      <property name="list">
         <list class="java.util.LinkedList" elementClass="java.lang.String">

            <!-- uses elementClass -->
            <value>A string</value> 

            <!-- a URL -->
            <value class="java.lang.URL">http://acme.com/index.html</value> 

            <!-- inject some other bean -->
            <value><inject bean="SomeBean"/></value> 

            <!-- a list inside a list -->
            <value> 
               <list elementClass="java.lang.String">
                  <value>Another string</value>
               </list>
            </value>

         </list>
      </property>
   </bean>

]]>
      </programlisting>

      <para>Below is what happens inside the microcontainer.</para>

      <programlisting>
<![CDATA[

   Example example = new com.acme.Example();
   List list = new LinkedList();
   list.add(new String("A string"));
   list.add(new URL("http://acme.com/index.html"));
   list.add(someBean);
   List subList = new ArrayList();
   subList.add(new String("Another string"));
   list.add(subList);
   element.setList(list);

]]>
      </programlisting>

      <para>The other type of collection is a map which also covers Properties and Hashtables. The default is
         <varname>java.util.HashMap</varname>
         . The
         <varname>entry</varname>
         element inside the map differentiates each
         <varname>key</varname>
         and
         <varname>value</varname>
         pair. For maps there are two default types for the elements: the
         <varname>keyClass</varname>
         and
         <varname>valueClass</varname>
         . Below is a map sample from the
         <varname>collections</varname>
         example.
      </para>

      <programlisting>
<![CDATA[

   <bean name="PrintMap"
      class="org.jboss.example.microcontainer.collections.ObjectPrinter">

      <constructor>
         <parameter>Map</parameter>
      </constructor>

      <property name="print">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry>
               <key>Key1 of type keyClass</key>
               <value>Value1 of type valueClass</value>
            </entry>

            <entry>
               <key>Key2 of type keyClass</key>
               <value class="java.lang.Integer">4</value>
            </entry>

            <entry>
               <key class="java.lang.Long">4</key>
               <value>Value of type valueClass</value>
            </entry>
         </map>
      </property>

   </bean>

]]>
      </programlisting>

      <para>When using collections in your bean configuration, this is the order the Microcontainer will use for new
         instantiation or using an already existing collection instance.
         <itemizedlist mark="bullet">
            <listitem>
               <para>if the collection's class attribute is defined, a new instance of that class will be instantiated</para>
            </listitem>
            <listitem>
               <para>if an already instantiated collection exists and is available via getter, this instance will be used -
                  unless you define the preinstantiate attribute on the property to false
               </para>
            </listitem>
            <listitem>
               <para>if the collection references some non interface class, we'll try to instantiate a new instance of
                  that class
               </para>
            </listitem>
            <listitem>
               <para>default collection instance will be used - Collection and List will use ArrayList, Set uses
                  HashSet and Map will use HashMap
               </para>
            </listitem>
         </itemizedlist>
      </para>

      <programlisting>
<![CDATA[

   <bean name="SimpleBean" 
     class="org.jboss.test.kernel.config.support.UnmodifiableGetterBean">
      <property name="list" preinstantiate="false">
         <list elementClass="java.lang.String">
            <value>string1</value>
            <value>string2</value>
         </list>
      </property>
   </bean>

]]>
      </programlisting>

   </sect2>

   <sect2>
      <title>Lifecycle</title>

      <para>Anybody familiar with the JBoss JMX microkernel will know about the lifecycle. The microcontainer extends
         the lifecycle concept to the managed POJOs. A POJO can have the following lifecycle states.
      </para>

      <itemizedlist mark="bullet">
         <listitem>
            <para>Not Installed: The POJO has not been described or has been uninstalled.</para>
         </listitem>
         <listitem>
            <para>Pre Install: The scoping description has been examined and classloader dependencies determined.</para>
         </listitem>
         <listitem>
            <para>Described: The POJO's bean description has been examined and dependencies determined.</para>
         </listitem>
         <listitem>
            <para>Instantiated: All the dependencies have been resolved to construct the bean. These include: the class
               exists, the constructor parameter injections can be resolved, any factory can be resolved.
            </para>
         </listitem>
         <listitem>
            <para>Configured: All the property injections can be resolved, this includes all the dependencies in any
               collections.
            </para>
         </listitem>
         <listitem>
            <para>Create: All the dependent beans have been "created", this includes any injections passed to the create
               method.
            </para>
         </listitem>
         <listitem>
            <para>Start: All the dependent beans have been "started", this includes any injections passed to the start
               method.
            </para>
         </listitem>
         <listitem>
            <para>Installed: The lifecycle is complete.</para>
         </listitem>
         <listitem>
            <para>*** ERROR ***: Some unexpected error occured, usually due to misconfiguration.</para>
         </listitem>
      </itemizedlist>

      <para>At each stage of the lifecycle, the corresponding method in the bean class is automatically called by the
         Microcontainer, so that you can programatically control how the objects behave throughout its lifecycle. For
         instance, the
         <varname>start()</varname>
         method in the bean class is called when the bean enters the
         <varname>Start</varname>
         state. Below is the
         <varname>LifecycleBean</varname>
         class from the
         <varname>lifecycle</varname>
         example.
      </para>

      <programlisting>
<![CDATA[

   public class LifecycleBean
   {
      String name;

      public LifecycleBean(String name)
      {
         this.name = name;
         System.out.println("LifecycleBean() " + this);
      }

      public void create()
      {
         System.out.println("create: " + this);
      }

      public void start()
      {
         System.out.println("start: " + this);
      }

      public void stop()
      {
         System.out.println("stop: " + this);
      }

      public void destroy()
      {
         System.out.println("destroy: " + this);
      }

      public String toString()
      {
         return name;
      }
   }

]]>
      </programlisting>

      <para>The
         <varname>depends</varname>
         element allows two beans to perform two phase startup processing like the JMX microkernel.
      </para>

      <programlisting>
<![CDATA[

   <bean name="Lifecycle1"
      class="org.jboss.example.microcontainer.lifecycle.LifecycleBean">

      <constructor>
         <parameter>Lifecycle1</parameter>
      </constructor>

      <depends>Lifecycle2</depends>

   </bean>

   <bean name="Lifecycle2"
      class="org.jboss.example.microcontainer.lifecycle.LifecycleBean">

      <constructor>
         <parameter>Lifecycle2</parameter>
      </constructor>

   </bean>

]]>
      </programlisting>

      <para>The microcontainer resolves the dependency and starts both beans in the appropriate order. Below is the
         console output when you run the
         <varname>lifecycle</varname>
         example. It shows when various lifecycle methods are called when the bean enters those states.
      </para>

      <programlisting>
         run:
         [java] LifecycleBean() Lifecycle1
         [java] LifecycleBean() Lifecycle2
         [java] create: Lifecycle2
         [java] create: Lifecycle1
         [java] start: Lifecycle2
         [java] start: Lifecycle1
         [java] stop: Lifecycle1
         [java] stop: Lifecycle2
         [java] destroy: Lifecycle1
         [java] destroy: Lifecycle2
      </programlisting>

      <para>The
         <varname>create()</varname>
         ,
         <varname>start()</varname>
         ,
         <varname>stop()</varname>
         and
         <varname>destroy()</varname>
         methods can be overridden with parameters passed to them. Below is an example on how to override the
         <varname>create()</varname>
         method via the
         <varname>jboss-beans.xml</varname>
         configuration file.
      </para>

      <programlisting>
<![CDATA[

   public class Example
   {
      public void initialize(Object someObject) {}
   }

   <bean name="Name1" class="com.acme.Example">
      <create method="initialize">
         <parameter><inject bean="SomeBean"/></parameter>
      </create>
   </bean>

]]>
      </programlisting>

      <para>They can also be ignored. See the
         <varname>jboss-beans.xml</varname>
         with the <varname>ignore</varname> attribute set to true on the start element.
      </para>

      <programlisting>
<![CDATA[

   public class Example
   {
      public void start() {}
   }

   <bean name="Name1" class="com.acme.Example">
      <start ignore="true"/>
   </bean>

]]>
      </programlisting>

      <para>In this case the Microcontainer would not
         invoke the start method when passing over Start state.
      </para>
   </sect2>

   <sect2>
      <title>Installation</title>

      <para>As of 2.0.0, you can provide generic install/uninstall actions. Allowing you to dynamically setup
         repositories. Note the use of
         <varname>this</varname>
         to pass yourself as a parameter. If you exlude the bean name on the action, the operation is performed on
         yourself.
      </para>

      <programlisting>
<![CDATA[

   <bean name="name1" class="java.util.Timer"/>

   <bean name="name2" ...>
      <install bean="name1" method="schedule">
         <parameter><this/></parameter>
         <parameter>100</parameter>
         <parameter>10000</parameter>
      </install>

      <uninstall method="cancel"/>

   </bean>

   // Install
   name1 = new Timer();
   name2 = ...;
   name1.schedule(name2, 100, 10000);

   // Uninstall
   name2.cancel();

]]>
      </programlisting>
   </sect2>

   <sect2>
      <title>ClassLoader</title>

      <para>The Microcontainer supports configuration of the classloader at either the deployment or bean level. The
         classloader element has three alternatives.
      </para>

      <programlisting>
<![CDATA[

   <!-- deployment level - applies to all beans in the deployment -->
   <deployment>
      <classloader><inject bean="ClassLoaderName"/></classloader>

      <!-- bean level -->
      <bean name="Name2" ...>
         <classloader><inject bean="ClassLoaderName"/></classloader>
      </bean>

      <!-- bean level will use any deployment level classloader -->
      <bean name="Name3" ...>
      </bean>

      <!-- bean level as null to not use any deployment level classloader -->
      <bean name="Name4" ...>
         <classloader><null/></classloader>
      </bean>

   </deployment>

]]>
      </programlisting>
   </sect2>

   <sect2>
      <title>Annotations via XML</title>

      <para>With the new Microcontainer 2.0 we've added support for annotations via XML. Meaning you can have annotation
<!--         support even in Java 1.4 and before, depending on the retrowoven Microcontainer project. -->
         support where the annotation is not part of the bean class's bytecode.
         Each annotation is set per bean instance and you can set annotations on the following types:
         <itemizedlist>
            <listitem><simpara>deployment (all beans inherit this annotations)</simpara></listitem>
            <listitem><simpara>bean</simpara></listitem>
            <listitem><simpara>constructor</simpara></listitem>
            <listitem><simpara>lifecycle</simpara></listitem>
            <listitem><simpara>install / uninstall</simpara></listitem>
            <listitem><simpara>callback</simpara></listitem>
            <listitem><simpara>annotated value</simpara></listitem>
         </itemizedlist>
         Let's see some use cases on the examples below.
      </para>

      <programlisting>
<![CDATA[

   <deployment name="SimpleDeployment" xmlns="urn:jboss:bean-deployer:2.0">

      <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation1</annotation>
      <annotation>@org.jboss.test.kernel.deployment.xml.support.AnnotationWithAttributes(clazz=java.lang.Integer.class, integer=100, str="Annotations are nice")</annotation>

      <bean name="bn1" class="org.jboss.test.Example1">
         <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation2</annotation>
         <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation3</annotation>
      </bean>

      <bean name="bn2" class="org.jboss.test.Example2">
         <constructor>
            <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation3</annotation>
         </constructor>
      </bean>

      <bean name="bn3" class="org.jboss.test.Example3">
         <install method="someMethod">
            <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation1</annotation>
         </install>
      </bean>

      <bean name="bn4" class="org.jboss.test.Example4">
         <create>
            <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation1</annotation>
         </create>
      </bean>

      <bean name="bn5" class="org.jboss.test.Example5">
         <property name="PropertyName">
            <annotation>@org.jboss.test.kernel.deployment.xml.support.Annotation1</annotation>
            <value>123</value>
         </property>
      </bean>

   </deployment>

]]>
      </programlisting>

      <para>The only issue with having annotations defined via XML is that they are per instance basis - 
         as already mentioned, not added at compile time. In this case you need an external mechanism in
         order to do the annotation inspection. In the Microcontainer this is its metadata repository.
         See how this is done in Reference Manual, TODO.
      </para>

   </sect2>

   <sect2>
      <title>Alias</title>

      <para>Mostly each bean will have one unique name, but sometimes it is useful to be able to have an extra name.
         The extra ones are considered aliases.
      </para>

      <programlisting>
<![CDATA[

   <bean xmlns="urn:jboss:bean-deployer:2.0" class="org.acme.Example">
      <alias>SimpleAlias</alias>
   </bean>

]]>
      </programlisting>

      <para>As with all String values you can have System property replacement as part of actual alias value.
         Additionally you can specify if this replacement is ignored. Or you can even convert a final alias String value
         into any other class supported by PropertyEditors by setting the class attribute on an alias element. Lets see this
         configuration on the examples below.
      </para>

      <programlisting>
<![CDATA[

   <bean xmlns="urn:jboss:bean-deployer:2.0" class="org.acme.Example">
      <alias>${example.cluster.name}</alias>
   </bean>

   <bean xmlns="urn:jboss:bean-deployer:2.0" class="org.acme.Example">
      <alias replace="false">X${alias.test.name}X</alias>
   </bean>

   <bean xmlns="urn:jboss:bean-deployer:2.0" class="org.acme.Example">
      <alias class="java.lang.Integer">12345</alias>
   </bean>

]]>
      </programlisting>

      <para>Having to specify all aliases when the bean is actually defined is not always adequate however. It is
         sometimes desirable to introduce an alias for a bean which is defined elsewhere. In XML-based configuration
         metadata this may be accomplished via the use of the standalone <varname><![CDATA[<alias/>]]></varname> element.
      </para>

      <programlisting>
<![CDATA[

   <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>

      <para>
         A newly added alias defined as a element on the deployment acts as a full dependency item. Meaning
         it won't get registered (installed) until the original bean is installed. What this means is that you can have
         original beans defined in one deployment and aliases in another, and the order of deployment doesn't matter.
         When the original bean is uninstalled, the alias gets unregistered (uninstalled) as well.
         When the alias gets unregistered, all beans that depend on the alias get undeployed as well, regardless of if
         the original bean is still present.
      </para>

   </sect2>

   <sect2>
      <title>Supply and Demand</title>

      <para>
         There is another useful definition of loosely coupled dependency.
         Each bean can define which beans should be installed for it to move
         to certain state.
      </para>

      <programlisting>
<![CDATA[

   <bean name="TM" class="com.acme.SomeSingleton">
      <property name="host">http://www.jboss.org</property>
   </bean>

   <bean name="SM" class="com.acme.AnotherSingleton">
      <property name="treadSize">10</property>
   </bean>

   <bean name="Name2" class="com.acme.Example">
      <property name="threadPool"><inject bean="pool"/></property>
      <demand state="Start">TM</demand>
      <demand state="Configure">SM</demand>
   </bean>

   // Example class
   public class Example
   {
      public void start()
      {
         SomeSingleton tm = ...; // should be there!
      }

      public void setThreadPool(ThreadPool pool)
      {
         AnotherSingleton config = ...; // should be there
         pool.setThreadSize(config.getThreadSize());
      }

   }

]]>
      </programlisting>

      <para>
         On the other hand each bean can also provide additional information
         what it supplies, apart from it self. The actual supply doesn't need to be
         bound to the Microcontainer in any way.
         More about this feature with the actual example.
      </para>

      <programlisting>
<![CDATA[

   public class FooBarBinder extends JndiBinder
   {
      public void start()
      {
         FooBar foobar = new FooBar();
         bindToJndi("fbName", foobar);
      }

   }

   public class FooBarConsumer
   {
      public FooBarConsumer()
      {
         FooBar foobar = ...; // get it from jndi. should be there
      }
   }

   <bean name="provider" class="com.acme.FooBarBinder">
      <supply>foobar</supply>
   </bean>

   <bean name="consumer" class="com.acme.FooBarConsumer">
      <demand state="Instantiate">foobar</demand>
   </bean>

]]>
      </programlisting>
   </sect2>

   <sect2>
      <title>Contextual Awareness</title>

      <para>
         With existing annoyance of using huge amounts of xml to sometimes wire up
         trivial beans, IoC containers provide a simpler solution called autowiring.
         Beans, specially singletons, can often be wired with a simple class type knowledge.
         But with huge systems you should use this feature with care, since it can easly get broken
         with addition of another bean that would satisfy contextual dependency.
         The existing 2.0.0 version supports three ways of autowiring:
         <itemizedlist spacing="compact">
            <listitem>
               <para>full bean autowiring</para>
            </listitem>
            <listitem>
               <para>property / parameter injection</para>
            </listitem>
            <listitem>
               <para>callback injection</para>
            </listitem>
         </itemizedlist>
      </para>

      <para>On the other hand, if you don't want a particular bean to be involved as a candidate for
         autowiring, you can set the bean element's attribute <varname>autowire-candidate</varname> to false.
      </para>

      <programlisting>
<![CDATA[

   <bean name="ignored" class="com.acme.Example" autowire-candidate="false" />

]]>
      </programlisting>

      <para>
         TODO for bean autowiring.
      </para>

      <programlisting>
<![CDATA[

   <bean name="autowired" class="com.acme.Example" autowire="true" />

]]>
      </programlisting>

      <para>
         When doing a propery / parameter injection of some existing bean, you can omit the bean attibute, meaning that the
         Microcontainer will do the injection based on the information from the property / parameter class type.
         If no such information is available, an exception will be thrown. If no such bean is eventually available, you can define
         the behavior after validation. For Strict option the deployment will fail, for Callback see the callback injection below.
         There is also a way of doing contextual injection based on property name. Property name will be matched against
         newly wired bean's name.
      </para>

      <programlisting>
<![CDATA[

   <bean name="pool" class="com.acme.ThreadPoolImpl"/>

   <bean name="propInj" class="com.acme.Example">
      <property name="threadPool"><inject/></property>
   </bean>

   <bean name="paramInj" class="com.acme.Example">
      <constructor>
         <parameter name="threadPool"><inject/></parameter>
      </constructor>
   </bean>

   public class Example
   {
      protected ThreadPool pool;

      public Example() {}

      public Example(ThreadPool pool)
      {
         this.pool = pool;
      }

      public void setThreadPool(ThreadPool pool)
      {
         this.pool = pool;
      }

   }

]]>
      </programlisting>

      <para>
         Sometimes it is useful to be notified of certain beans being installed / uninstalled by
         inspecting their class type. In the Microcontainer we call this callbacks.
         You can define which methods should be used for callback resolution on a particular bean. Usually the method
         name is sufficient. In the case of having multiple methods with the same name, you can narrow down the
         exact method by specifying the class type to use for contextual lookup.
      </para>

      <programlisting>
<![CDATA[

   <bean name="editorHolder" class="com.acme.Example">
      <incallback method="addEditor" />
      <uncallback method="removeEditor" />
   </bean>

   <bean name="fbEditor" class="com.acme.FooEditor"/>

   public class Example
   {
      protected Set<Editor> editors = new HashSet<Editor>();

      public Example() {}

      public void addEditor(Editor editor)
      {
         editors.add(editor);
      }

      public void removeEditor(Editor editor)
      {
         editors.remove(editor);
      }
   }

]]>
      </programlisting>

      <para>
         We can do the same callback injection on a property.
         And there is also an interesting feature available, though it will probably rarely be used.
         You can define a Cardinality as a condition when that actual dependency is satisfied and injection
         can take place.
         The following examples shows how we need at least 2 Editor instances to satisfy callback dependency.
      </para>

      <programlisting>
<![CDATA[

   <bean name="editorHolder" class="com.acme.Example">
      <incallback property="editors" cardinality="2..n" />
      <uncallback property="editors" />
   </bean>

   <bean name="fbEditor" class="com.acme.FooEditor"/>

   <bean name="xyzEditor" class="com.acme.XYZEditor"/>

   public class Example
   {
      protected Set<Editor> editors;

      public Example() {}

      public void setEditors(Set<Editor> editors)
      {
         this.editors = editors;
      }
   }

]]>
      </programlisting>

      <para>While using callbacks on the Collection subclasses, currently only basic Collection subinterfaces
         are supported: List, Set and Queue. See BasicCollectionCallbackItemFactory for more details.
         But you can change the Collection callback behaviour by providing your own CollectionCallbackItemFactory.
         You do this by setting the System Property <varname>org.jboss.dependency.collectionCallbackItemFactory</varname>
         and putting the CollectionCallbackItemFactory implementation fully qualified class name as a value.
      </para>

   </sect2>

   <sect2>
      <title>Injection from Context</title>

      <para>Even though the Microcontainer is aimed at POJOs, it doesn't mean you are not able to easily get into
         the underlying architecture of its state machine.
         Each bean is represented in the Microcontainer's state machine (Controller) as a ControllerContext.
         The ControllerContext holds various information in order to consistently move between lifecycle states,
         resolve dependencies, apply instance aspects, annotations, metadata ...
      </para>

      <para>
         With the already known injection concept (<varname><![CDATA[<inject />]]></varname>), you can also inject some information from the context.
         This is what you can currently get a hold on from the underlying context:
         <itemizedlist>
            <listitem>
               <para>name - <varname><![CDATA[<inject fromContext="name"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>aliases - <varname><![CDATA[<inject fromContext="aliases"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>metadata - <varname><![CDATA[<inject fromContext="metadata"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>beaninfo - <varname><![CDATA[<inject fromContext="beaninfo"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>scope - <varname><![CDATA[<inject fromContext="scope"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>id - <varname><![CDATA[<inject fromContext="id"/>]]></varname></para>
            </listitem>
            <listitem>
               <para>context itself - <varname><![CDATA[<inject fromContext="context"/>]]></varname></para>
            </listitem>
         </itemizedlist>
      </para>

      <para>All this information is wrapped into unmodifiable objects, preventing the user to add or set additional
         information outside the Microcontainer's Controller.
         As we already know, the <varname><![CDATA[<inject/>]]></varname> element can take a 
		 <varname>bean</varname> attribute. In this case, if the bean attribute is set,
         we are not obtaining the target bean's underlying context, but the context that coresponds to the bean being injected.
      </para>

      <programlisting>
<![CDATA[

   <bean name="sndBean" 
     class="org.jboss.test.kernel.deployment.support.NameAwareBean">
      <property 
	    name="beaninfo"><inject bean="otherBean" fromContext="beaninfo"/></property>
   </bean>

]]>
      </programlisting>

      <para>In this example we inject otherBean's beaninfo information into sndBean bean.</para>
   </sect2>

</sect1>
