1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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>
|
