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

<chapter id="examples">
   <title>Starting Examples</title>

   <section>
      <title>A Simple IoC 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 us 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>
<![CDATA[

   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>
<![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>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 the Microcontainer API for the
         <varname>Simple</varname>
         object. 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 on 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>
<![CDATA[

   <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>
         target compiles the Java source files into class files under the
         <varname>build</varname>
         directory. Then, the
         <varname>dist</varname>
         target packages the class files and the
         <varname>META-INF/jboss-beans.xml</varname>
         file together in a JAR file named
         <varname>example-simple.jar</varname>
         in the
         <varname>dist</varname>
         directory.
      </para>

      <para>In the next two sections, let's discuss how to run the newly created
         application both as a standalone Java SE application and as a service in the JBoss AS.
      </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 in the source code repository).</para>

  </section>
</chapter>
