[jboss-cvs] JBossAS SVN: r61482 - in projects/microcontainer/trunk: docs and 6 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Mar 20 00:19:01 EDT 2007
Author: scott.stark at jboss.org
Date: 2007-03-20 00:19:01 -0400 (Tue, 20 Mar 2007)
New Revision: 61482
Added:
projects/microcontainer/trunk/docs/
projects/microcontainer/trunk/docs/gettingstarted/
projects/microcontainer/trunk/docs/gettingstarted/src/
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/images/
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/images/empty.dir
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/master.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/basics.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/conclusion.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/examples.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/installation.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/introduction.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/packaging.xml
projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/standalone.xml
Log:
Migrate the 1.0 docs into svn
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/images/empty.dir
===================================================================
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/images/empty.dir
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/master.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/master.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/master.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+[
+<!ENTITY introduction SYSTEM "modules/introduction.xml">
+<!ENTITY installation SYSTEM "modules/installation.xml">
+<!ENTITY examples SYSTEM "modules/examples.xml">
+<!ENTITY packaging SYSTEM "modules/packaging.xml">
+<!ENTITY basics SYSTEM "modules/basics.xml">
+<!ENTITY standalone SYSTEM "modules/standalone.xml">
+<!ENTITY conclusion SYSTEM "modules/conclusion.xml">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>Getting Started with the JBoss Microcontainer</title>
+
+ <subtitle>A Guide for POJO Developers</subtitle>
+
+ <releaseinfo>1.0.2</releaseinfo>
+ </bookinfo>
+
+ <toc></toc>
+
+ <preface id="target" revision="1">
+ <title>Target Audience</title>
+
+ <para>This guide is aimed at developers who want to use the Microcontainer to assemble their own applications or use it to develop shared services in the JBoss Application Server.</para>
+ </preface>
+
+ <preface id="preface" revision="1">
+ <title>Preface</title>
+
+ <para>Commercial development support, production support and training for
+ the JBoss Microcontainer is available through <ulink
+ url="http://www.jboss.com">JBoss Inc.</ulink> The JBoss Microcontainer is
+ a project of the JEMS product suite.</para>
+
+ <para>Authors: <itemizedlist spacing="compact">
+ <listitem>
+ <para>Adrian Brock - JBoss Microcontainer Project Lead and Chief
+ Scientist of JBoss Inc.</para>
+ </listitem>
+ </itemizedlist></para>
+ </preface>
+
+ &introduction;
+
+ &installation;
+
+ &examples;
+
+ &basics;
+
+ &packaging;
+
+ &standalone;
+
+ &conclusion;
+</book>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/master.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/basics.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/basics.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/basics.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,668 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="basics">
+ <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>
+
+ <section>
+ <title>Deployment</title>
+
+ <para>The <varname>deployment</varname> element acts as a container for many beans that are deployed together.</para>
+
+ <programlisting><?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_1_0.xsd"
+ xmlns="urn:jboss:bean-deployer">
+
+ <!-- bean part of the deployment -->
+ <bean .../>
+
+ <!-- bean part of the deployment -->
+ <bean .../>
+
+</deployment></programlisting>
+ </section>
+
+ <section>
+ <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>
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
+ xmlns="urn:jboss:bean-deployer">
+
+ <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>
+ </section>
+
+ <section>
+ <title>Construction</title>
+
+ <para>The example above uses the default constructor. What if you don't 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>
+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>
+<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>
+<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 (new String("a string"), (long) 10);
+ </programlisting>
+
+ <para>Note that you only have to be explicit enough to resolve the ambiguity.</para>
+
+ </section>
+
+ <section>
+ <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>
+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>
+<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>
+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>
+<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>
+
+ </section>
+
+ <section>
+ <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>
+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 use the setter methods to set its properties.</para>
+
+ <programlisting>
+<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>
+
+ </section>
+
+ <section>
+ <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>
+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>
+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>
+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, <null/>. But, it needs to differentiated from the string "null". Please see the example below for the usage.</para>
+
+ <programlisting>
+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>
+
+ </section>
+
+ <section>
+ <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 an 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>
+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>
+<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>
+<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>
+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>
+
+ </section>
+
+ <section>
+ <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 a <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>
+<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>
+<bean name="Name1" class=com.acme.Example">
+ <property name="list">
+ <list class="java.util.LinkedList" elementClass="java.lang.String">
+
+ <value>A string</value> <!-- uses elementClass -->
+
+ <value class="java.lang.URL">http://acme.com/index.html</value> <!-- a URL -->
+
+ <value><inject bean="SomeBean"/></value> <!-- inject some other bean -->
+
+ <value> <!-- a list inside a list -->
+ <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>
+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>
+<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>
+
+ </section>
+
+ <section>
+ <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>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>
+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>
+<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>
+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>
+ </section>
+
+ <section>
+ <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>
+<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>
+ </section>
+
+ <section>
+ <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>
+// 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="Name2" ...>
+</bean>
+
+// bean level as null to not use any deployment level classloader
+<bean name="Name2" ...>
+ <classloader><null/></classloader>
+</bean>
+ </programlisting>
+ </section>
+ </chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/basics.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/conclusion.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/conclusion.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/conclusion.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="conclusion">
+ <title>Conclusion</title>
+
+ <para>The microcontainer is a powerful replacement for the JBoss's JMX
+ microcontainer. It brings the loosely coupled configuration environment of
+ JBoss to POJO environments, adding more control and extra features. Both
+ inside and outside the JBoss Application Server.</para>
+
+ <para></para>
+
+ <para>Going forward these additional features will allow even more advances,
+ including aspectized deployment, on demand services, versioned deployments,
+ etc.</para>
+</chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/conclusion.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/examples.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/examples.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/examples.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="examples">
+ <title>Examples</title>
+
+ <section>
+ <title>A Simple Example</title>
+
+ <para>The best way to learn the MicroContainer is through examples. The Microcontainer distribution is bundled with several examples, which we will discuss in later this guide. In this section, let's first have a look at the <varname>simple</varname> example. It shows the structure of a simple MicroContainer application and how to run the application in both standalone and JBoss AS environments.</para>
+
+ <para>The <varname>simple</varname> example is located in the <varname>examples/simple</varname> directory of the Microcontainer distribution. It contains a single class under the <varname>src/main</varname> directory.</para>
+
+ <programlisting>
+public class SimpleBean
+{
+ public SimpleBean()
+ {
+ System.out.println("SimpleBean() constructor");
+ }
+}
+ </programlisting>
+
+ <para>The <varname>SimpleBean</varname> object prints to the system console when it is instantiated via the default constructor. Now, we need to use the Microcontainer to instantiate a <varname>SimpleBean</varname> POJO. We do this by invoking the Microcontainer with the <varname>src/resources/META-INF/jboss-beans.xml</varname> configuration file.</para>
+
+ <programlisting>
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
+ xmlns="urn:jboss:bean-deployer">
+
+ <bean name="Simple"
+ class="org.jboss.example.microcontainer.simple.SimpleBean"/>
+
+</deployment>
+ </programlisting>
+
+ <para>This configuration file tells the Microcontainer to create an instance of the <varname>SimpleBean</varname> POJO and manage it under the name <varname>Simple</varname>. When other objects in the application need to access this <varname>SimpleBean</varname> instance, they can simply ask for the <varname>Simple</varname> object from the Microcontainer API. Essentially, we just created a <varname>SimpleBean</varname> singleton instance here. When we run this application, we are expected to see the <varname>"SimpleBean() constructor"</varname> printout from the console when the Microcontainer creates the <varname>Simple</varname> object.</para>
+
+ </section>
+
+ <section>
+ <title>Build and Package the Application</title>
+
+ <para>To build, package, and run the <varname>simple</varname> application, we can simply execute the <varname>ant</varname> command in the <varname>examples/simple</varname> directory. It runs the <varname>build.xml</varname> script, which further invokes the <varname>examples/build-common.xml</varname> script. The <varname>compile</varname> and <varname>dist</varname> tasks in the build script builds the application.</para>
+
+ <programlisting>
+<target name="compile">
+
+ <mkdir dir="build"/>
+
+ <javac destdir="build"
+ debug="on"
+ deprecation="on"
+ optimize="on"
+ classpathref="compile.classpath">
+ <src path="src"/>
+ </javac>
+</target>
+
+<target name="dist" depends="compile">
+
+ <copy todir="build">
+ <fileset dir="src/resources"/>
+ </copy>
+
+ <mkdir dir="dist"/>
+
+ <jar jarfile="dist/${ant.project.name}.beans" basedir="build"/>
+
+</target>
+ </programlisting>
+
+ <para>The <varname>compile</varname> task compiles the Java source files into class files under the <varname>build</varname> directory. Then, the <varname>dist</varname> task packages the class files and the <varname>META-INF/jboss-beans.xml</varname> file together in a JAR file named <varname>example-simple.beans</varname> in the <varname>dist</varname> directory. Note that the <varname>.beans</varname> extension is important if you need to run the application inside the JBoss AS. For more on Microcontainer application packaging, please refer to <xref linkend="packaging"/>.</para>
+
+ <para>In the next two sections, let's discuss how to run the <varname>.beans</varname> application both as a standalone Java SE application and as a service in the JBoss AS.</para>
+
+ </section>
+
+ <section>
+ <title>Run the Application in Standalone Mode</title>
+
+ <para>The <varname>run</varname> task in the <varname>build.xml</varname> script loads the Microcontainer with the <varname>example-simple.beans</varname> JAR file on the classpath. The Microcontainer then scans for the <varname>META-INF/jboss-beans.xml</varname> file on the classpath and creates / manages objects according to the configuration.</para>
+
+ <programlisting>
+<target name="run" depends="dist">
+
+ <java
+classname="org.jboss.kernel.plugins.bootstrap.standalone.StandaloneBootstrap"
+fork="true">
+ <classpath refid="run.classpath"/>
+ </java>
+</target>
+
+<path id="run.classpath">
+ <fileset dir="dist">
+ <include name="*.beans"/>
+ </fileset>
+ <fileset dir="${jboss.micro.home}/lib">
+ <include name="*.jar"/>
+ </fileset>
+</path>
+ </programlisting>
+
+ <para>The <varname>StandaloneBootstrap</varname> class is a utility class to load the Microcontainer as a standalone application in the Java SE environment. We will discuss more about it in <xref linkend="standalone"/>. As expected, the Microcontainer instantiates the <varname>SimpleBean</varname> POJO and the message is successfully printed from the constructor.</para>
+
+ <programlisting>
+run:
+ [java] SimpleBean() constructor
+
+BUILD SUCCESSFUL
+Total time: 12 seconds
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Run the Application as a JBoss Service</title>
+
+ <para>To run the application as a shared JBoss service, you first need to change the <varname>jboss.home</varname> property in the <varname>examples/build.properties</varname> file and point it to your local JBoss installation. Then, you run <varname>ant deploy</varname> to copy the <varname>example-simple.beans</varname> file into the <varname>deploy</varname> directory of your JBoss instance. If the server is already running, the <varname>.beans</varname> file is automatically deployed and you will see the <varname>SimpleBean</varname> constructor message printed out in the console window. If the server is not running, you will see the message confirming the creation of the <varname>Simple</varname> object when you start up the server the next time.</para>
+
+ <para>To remove the <varname>.beans</varname> package from the server, just run <varname>ant undeploy</varname> in the example directory.</para>
+
+ </section>
+
+ <section>
+ <title>Other Bundled Examples</title>
+
+ <para>Besides the <varname>simple</varname> example, the Microcontainer distribution bundles other examples to illustrate various aspects of the framework. We will cover those examples in more detail in <xref linkend="basics"/>. Each example is in a subfolder under the <varname>examples/</varname> directory with the following structure:</para>
+
+ <programlisting>readme.txt - a short description of the example including the expected output
+build.xml - the ant build script
+src/resources/META-INF/jboss-beans.xml - the MicroContainer configuration for the example
+src/main - the java source for the example</programlisting>
+
+ <para>Here is a list of those examples.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>simple: a simple example to make sure you have everything
+ working</para>
+ </listitem>
+
+ <listitem>
+ <para>constructor: simple constructor configuration</para>
+ </listitem>
+
+ <listitem>
+ <para>factory: construction using factories</para>
+ </listitem>
+
+ <listitem>
+ <para>properties: property configuration</para>
+ </listitem>
+
+ <listitem>
+ <para>injection: referencing other beans</para>
+ </listitem>
+
+ <listitem>
+ <para>collections: creating collections</para>
+ </listitem>
+
+ <listitem>
+ <para>lifecycle: the create/start/stop/destroy lifecycle</para>
+ </listitem>
+
+ <listitem>
+ <para>locator: implementing the locator pattern with the Microcontainer</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The JBoss Microcontainer uses any logging mechanism supported by
+ org.jboss.logging. e.g. if you want to use log4j, add log4j.jar and a
+ directory containing either a log4j.properties or log4j.xml to the
+ classpath. The default distribution uses the "null" logging implementation,
+ which is why the examples all use System.out.println().</para>
+
+ <para>This just skims the surface of the MicroContainer, showing the most
+ common usecases. Other more complicated examples can be found in the tests
+ (available from cvs).</para>
+
+ </section>
+</chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/examples.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/installation.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/installation.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/installation.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="installation">
+ <title>Download and Installation</title>
+
+ <para>First you need download JBoss Microcontainer release from <ulink
+ url="http://www.jboss.com/downloads/index">http://www.jboss.com/downloads/index</ulink></para>
+
+ <para>Unpack the archive which will give you a microcontainer-x.y.z
+ directory with the following subfolders:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>docs/api - javadocs for the microcontainer</para>
+ </listitem>
+
+ <listitem>
+ <para>docs/gettingstarted - this getting started documentation</para>
+ </listitem>
+
+ <listitem>
+ <para>docs/licences - the licenses for the software</para>
+ </listitem>
+ <listitem>
+ <para>examples - the examples explained in the next chapter</para>
+ </listitem>
+
+ <listitem>
+ <para>lib - the libraries required to run the microcontainer</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>You will also need a JDK of version 1.4.x+ and a copy of Apache Ant
+ 1.6+</para>
+
+ <para>If you want to run the examples inside JBoss AS, you will need to
+ download JBoss-4.0.3 or later <ulink
+ url="http://www.jboss.com/products/jbossas/downloads">http://www.jboss.com/products/jbossas/downloads</ulink></para>
+</chapter>
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/installation.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/introduction.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/introduction.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/introduction.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="introduction">
+ <title>Introduction to the JBoss Microcontainer</title>
+
+ <para>The JBoss Microcontainer provides an environment to configure and manage POJOs (plain old java objects). It is designed to reproduce the existing JBoss JMX Microkernel but targetted at POJO environments. As such it can be used standalone outside the JBoss Application Server.</para>
+
+ <para>At its core, the JBoss Microcontainer is a generic "dependency injection" framework. It's primary function is to instantiate objects, figure out their dependencies (e.g., object A must be instantiated before object B), and then manage the relationship between those objects (e.g., object A is a property of object B). With the JBoss Microcontainer, you can build applications or shared services using simple POJOs. The JBoss Microcontainer is responsible for assembling the POJOs together according to an externally defined XML configuration file. It decouples the components in an application and makes the application easy to unit-test.</para>
+
+ <para>The JBoss Microcontainer is a big object factory that manages objects. In this sense, it is similar to existing dependency injection frameworks such as the Spring framework and HiveMind framework. However, JBoss Microcontainer also has several important new features that set it apart from existing frameworks.</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>JBoss Microcontainer supports life cycles for POJO components. It gives you fine-grained control over exactly how the objects are created, instantiated, and destroyed.</para></listitem>
+ <listitem><para>JBoss Microcontainer manages dependencies between objects. For instance, you can declare that object A must be instantiated before object B can be created.</para></listitem>
+ <listitem><para>JBoss Microcontainer integrates with the JBoss AOP (Aspect Oriented Programming) framework. In the JBoss Microcontainer configuration file, you can easily wire aspects as services to POJOs.</para></listitem>
+ <listitem><para>JBoss Microcontainer is embedded in JBoss AS 4.0.3 and above. It is the ideal choice if you need to develop shared services in JBoss AS.</para></listitem>
+ </itemizedlist>
+
+ <para>Of course, you can also run JBoss Microcontainer outside of the JBoss AS. For instance, you can run it in a Java SE (e.g., Swing) application or in the Tomcat servlet container. So, JBoss Microcontainer primarily targets three types of developers.</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>Framework developers can use JBoss Microcontainer to assemble custom server frameworks. For instance, the JBoss embeddable EJB3 framework is based on the Microcontainer.</para></listitem>
+ <listitem><para>JBoss application developers can develop POJO services that nicely integrate into the server and can be shared across applications.</para></listitem>
+ <listitem><para>Application developers can write lightweight applications that makes use of services from a variety of sources (e.g., transaction service from JBoss, persistence service from Hibernate, and HTTP service from Tomcat).</para></listitem>
+ </itemizedlist>
+
+ <para>A typical JBoss Microcontainer application or service include a set of POJOs that complete business tasks, as well as an XML configuration file called <varname>META-INF/jboss-beans.xml</varname> on the class path. The <varname>jboss-beans.cml</varname> file tells the JBoss Microcontianer how to assemble those POJOs together. For deployment, you can JAR the POJO classes, as well as the <varname>META-INF/jboss-beans.xml</varname> file together in a <varname>.beans</varname> archive file (see <xref linkend="packaging"/>).</para>
+
+ <para>This document takes you through some example deployments into
+ JBoss-4.0.3+ explaining how to configure POJOs and link them together
+ through injection. Later it shows how to do the same thing outside the
+ application server.</para>
+
+</chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/introduction.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/packaging.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/packaging.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/packaging.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="packaging">
+ <title>Packaging</title>
+
+ <para>We had a brief discussion on the <varname>.beans</varname> archive in <xref linkend="examples"/>. In this chapter, we will go into more depth on the packaging topic. As we will see later in <xref linkend="standalone"/>, the packaging is more of a convention rather than a requirement. The convention is recommended since it allows "deployments" to be used both standalone and inside JBoss AS.</para>
+
+ <para>The basic structure of microcontainer deployment is a <varname>.beans</varname> file (see below). The <varname>.beans</varname> can also be unpacked in a directory structure that looks the jar file. It contains a <varname>META-INF/jboss-beans.xml</varname> to describe what you want it to do. The contents of this xml file are described in <xref linkend="basics"/>. Finally, the <varname>.beans</varname> archive contains the classes and any resources just like any other jar file.</para>
+
+ <programlisting>
+example.beans/
+example.beans/META-INF/jboss-beans.xml
+example.beans/com/acme/SomeClass.class
+ </programlisting>
+
+ <para>If you want to include a <varname>.beans</varname> file in an <varname>.ear</varname> deployment, you will need to reference in <varname>META-INF/jboss-app.xml</varname>.</para>
+
+ <programlisting>
+<?xml version='1.0' encoding='UTF-8'?>
+
+<!DOCTYPE jboss-app
+ PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN"
+ "http://www.jboss.org/j2ee/dtd/jboss-app_4_0.dtd"
+>
+
+<jboss-app>
+
+ <module><service>example.beans</service></module>
+
+</jboss-app>
+ </programlisting>
+
+</chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/packaging.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Added: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/standalone.xml
===================================================================
--- projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/standalone.xml (rev 0)
+++ projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/standalone.xml 2007-03-20 04:19:01 UTC (rev 61482)
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="standalone">
+ <title>Standalone</title>
+
+ <para>In <xref linkend="examples"/>, we briefly discussed how to run a microcontainer application by loading the <varname>StandaloneBootstrap</varname> class, which in turn wraps the <varname>BasicBootstrap</varname> and <varname>BeanXMLDeployer</varname> utility classes. In this chapter, we will look into the source code of <varname>StandaloneBootstrap</varname> and see exactly how it works. While the <varname>StandaloneBootstrap</varname> class is sufficient for most use case scenarios, you do not have to use it. You can trivially write your own class that uses the <varname>BasicBootstrap</varname> and <varname>BeanXMLDeployer</varname>.</para>
+
+ <programlisting>
+package org.jboss.kernel.plugins.bootstrap.standalone;
+
+import java.net.URL;
+import java.util.Enumeration;
+import java.util.List;
+import java.util.ListIterator;
+
+import org.jboss.kernel.plugins.bootstrap.basic.BasicBootstrap;
+import org.jboss.kernel.plugins.deployment.xml.BeanXMLDeployer;
+import org.jboss.kernel.spi.deployment.KernelDeployment;
+import org.jboss.util.collection.CollectionsFactory;
+
+public class StandaloneBootstrap extends BasicBootstrap
+{
+ /** The deployer */
+ protected BeanXMLDeployer deployer;
+
+ /** The deployments */
+ protected List deployments = CollectionsFactory.createCopyOnWriteList();
+
+ /** The arguments */
+ protected String[] args;
+
+ /**
+ * Bootstrap the kernel from the command line
+ *
+ * @param args the command line arguments
+ * @throws Exception for any error
+ */
+ public static void main(String[] args) throws Exception
+ {
+ StandaloneBootstrap bootstrap = new StandaloneBootstrap(args);
+ bootstrap.run();
+ }
+
+ /**
+ * Create a new bootstrap
+ */
+ public StandaloneBootstrap(String[] args) throws Exception
+ {
+ super();
+ this.args = args;
+ }
+
+ public void bootstrap() throws Throwable
+ {
+ super.bootstrap();
+
+ deployer = new BeanXMLDeployer(getKernel());
+
+ Runtime.getRuntime().addShutdownHook(new Shutdown());
+
+ ClassLoader cl = Thread.currentThread().getContextClassLoader();
+ for (Enumeration e =
+ cl.getResources(StandaloneKernelConstants.DEPLOYMENT_XML_NAME);
+ e.hasMoreElements(); )
+ {
+ URL url = (URL) e.nextElement();
+ deploy(url);
+ }
+ for (Enumeration e = cl.getResources("META-INF/" +
+ StandaloneKernelConstants.DEPLOYMENT_XML_NAME);
+ e.hasMoreElements(); )
+ {
+ URL url = (URL) e.nextElement();
+ deploy(url);
+ }
+
+ // Validate that everything is ok
+ deployer.validate();
+ }
+
+ /**
+ * Deploy a url
+ */
+ protected void deploy(URL url) throws Throwable
+ {
+ log.debug("Deploying " + url);
+ KernelDeployment deployment = deployer.deploy(url);
+ deployments.add(deployment);
+ log.debug("Deployed " + url);
+ }
+
+ /**
+ * Undeploy a deployment
+ */
+ protected void undeploy(KernelDeployment deployment)
+ {
+ log.debug("Undeploying " + deployment.getName());
+ deployments.remove(deployment);
+ try
+ {
+ deployer.undeploy(deployment);
+ log.debug("Undeployed " + deployment.getName());
+ }
+ catch (Throwable t)
+ {
+ log.warn("Error during undeployment: " + deployment.getName(), t);
+ }
+ }
+
+ protected class Shutdown extends Thread
+ {
+ public void run()
+ {
+ log.info("Shutting down");
+ ListIterator iterator =
+ deployments.listIterator(deployments.size());
+ while (iterator.hasPrevious())
+ {
+ KernelDeployment deployment =
+ (KernelDeployment) iterator.previous();
+ undeploy(deployment);
+ }
+ }
+ }
+}
+</programlisting>
+
+ <para>One way to use this class in your own applications would be:</para>
+
+ <programlisting>
+import org.jboss.kernel.plugins.bootstrap.standalone.StandaloneBootstrap
+
+public MyMainClass
+{
+ public static void main(String[] args) throws Exception
+ {
+ StandaloneBootstrap.main(args);
+ // Your stuff here...
+ }
+}</programlisting>
+
+ <para>So what does the standalone bootstrap do?</para>
+
+ <para>First it does the plain bootstrap to get the "kernel" ready. You can
+ think of this a sophisticated form of <varname>ServerLocator</varname> implementation. It then creates a <varname>BeanXMLDeployer</varname> for deploying XML files. Next it adds a shutdown hook, such that deployments are correctly "undeployed" in reverse order to their deployment. Finally, it scans the classpath for <varname>META-INF/jboss-beans.xml</varname> and deploys every instance of that file it finds to populate the "kernel".</para>
+
+ <para>You can of course choose not to use this helper class and instead
+ implement your own processing rules.</para>
+
+</chapter>
\ No newline at end of file
Property changes on: projects/microcontainer/trunk/docs/gettingstarted/src/docbkx/en/modules/standalone.xml
___________________________________________________________________
Name: svn:eol-style
+ native
More information about the jboss-cvs-commits
mailing list