gettingstarted.xml
25.1 KB
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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<chapter id="gettingstarted">
<title>Getting started with Weld</title>
<para>
Weld comes with two starter example applications, in addition to more specialized examples. The first,
<literal>weld-numberguess</literal>, is a web (war) example containing only non-transactional managed beans.
This example can be run on a wide range of servers, including JBoss AS, GlassFish, Apache Tomcat, Jetty, Google
App Engine, and any compliant Java EE 6 container. The second example, <literal>weld-translator</literal>, is
an enterprise (ear) example that contains session beans. This example must be run on JBoss AS 6.0, Glassfish 3.0
or any compliant Java EE 6 container.
</para>
<para>
Both examples use JSF 2.0 as the web framework and, as such, can be found in the <literal>examples/jsf</literal>
directory of the Weld distribution.
</para>
<section id="prerequisites">
<title>Prerequisites</title>
<para>
To run the examples with the provided build scripts, you'll need the following:
</para>
<itemizedlist>
<listitem>
<para>the latest release of Weld, which contains the examples</para>
</listitem>
<listitem>
<para>Ant 1.7.0, to build and deploy the examples</para>
</listitem>
<listitem>
<para>a supported runtime environment (minimum versions shown)</para>
<itemizedlist>
<listitem>
<para>JBoss AS 6.0.0,</para>
</listitem>
<listitem>
<para>GlassFish 3.0,</para>
</listitem>
<listitem>
<para>Apache Tomcat 6.0.x (war example only), or</para>
</listitem>
<listitem>
<para>Jetty 6.1.x (war example only)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>(optionally) Maven 2.x, to run the examples in an embedded servlet container</para>
</listitem>
</itemizedlist>
<note>
<para>
You'll need a full install of Ant 1.7.0. Some linux distributions only supply a partial installation of Ant
which cause the build to fail. If you encounter problems, verify that ant-nodeps.jar is on the classpath.
</para>
</note>
<para>
In the next few sections, you'll be using the Ant command (<literal>ant</literal>) to invoke the Ant build script
in each example to compile, assemble and deploy the example to JBoss AS and, for the war example, Apache Tomcat.
You can also deploy the generated artifact (war or ear) to any other container that supports Java EE 6, such as
GlassFish 3.
</para>
<para>
If you have Maven installed, you can use the Maven command (<literal>mvn</literal>) to compile and assemble the
standalone artifact (war or ear) and, for the war example, run it in an embedded container.
</para>
<para>The sections below cover the steps for deploying with both Ant and Maven in detail. Let's start with JBoss AS.</para>
</section>
<section id="jbossas">
<title>Deploying to JBoss AS</title>
<para>
To deploy the examples to JBoss AS, you'll need <ulink url="http://jboss.org/jbossas/">JBoss AS
6.0.0</ulink> or above. If a release of the JBoss AS 6.0 line isn't yet available, you can download a
<ulink url="http://hudson.jboss.org/hudson/view/JBoss%20AS/job/JBoss-AS-6.0.x/">nightly snapshot</ulink>.
The reason JBoss AS 6.0.0 or above is required is because it's the first release that has both CDI and
Bean Validation support built-in, making it close enough to Java EE 6 to run the examples. The good news is
that there are no additional modifications you have to make to the server. It's ready to go!
</para>
<para>
After you have downloaded JBoss AS, extract it. (We recommended renaming the folder to include the
<literal>as</literal> qualifier so it's clear that it's the application server). You can move the extracted
folder anywhere you like. Wherever it lays to rest, that's what we'll call the JBoss AS installation
directory, or <literal>JBOSS_HOME</literal>.
</para>
<programlisting><![CDATA[$> unzip jboss-6.0.*.zip
$> mv jboss-6.0.*/ jboss-as-6.0]]></programlisting>
<para>
In order for the build scripts to know where to deploy the example, you have to tell them where to find your
JBoss AS installation (i.e., <literal>JBOSS_HOME</literal>). Create a new file named <literal>local.build.properties</literal>
in the examples directory of the Weld distribution and assign the path of your JBoss AS installation to the
property key <literal>jboss.home</literal>, as follows:
</para>
<programlisting><![CDATA[jboss.home=/path/to/jboss-as-6.0]]></programlisting>
<para>
You're now ready to deploy your first example!
</para>
<para>
Switch to the <literal>examples/jsf/numberguess</literal> directory and execute the Ant
<literal>deploy</literal> target:
</para>
<programlisting><![CDATA[$> cd examples/jsf/numberguess
$> ant deploy]]></programlisting>
<para>
If you haven't already, start JBoss AS. You can either start JBoss AS from a Linux shell:
</para>
<programlisting><![CDATA[$> cd /path/to/jboss-as-6.0
$> ./bin/run.sh]]></programlisting>
<para>
a Windows command window:
</para>
<programlisting><![CDATA[$> cd c:\path\to\jboss-as-6.0\bin
$> run]]></programlisting>
<para>
or you can start the server using an IDE, like Eclipse.
</para>
<note>
<para>
If you are using Eclipse, you should seriously consider installing the <ulink
url="http://www.jboss.org/tools">JBoss Tools</ulink> add-ons, which include a wide variety of tooling for
JSR-299 and Java EE development, as well as an enhanced JBoss AS server view.
</para>
</note>
<para>
Wait a few seconds for the application to deploy (or the application server to start) and see if you can
determine the most efficient approach to pinpoint the random number at the local URL <ulink
url="http://localhost:8080/weld-numberguess">http://localhost:8080/weld-numberguess</ulink>.
</para>
<tip>
<para>
The Ant build script includes additional targets for JBoss AS to deploy and undeploy the archive in either
exploded or packaged format and to tidy things up.
</para>
<itemizedlist>
<listitem>
<para>
<literal>ant restart</literal> - deploy the example in exploded format to JBoss AS
</para>
</listitem>
<listitem>
<para>
<literal>ant explode</literal> - update an exploded example, without restarting the deployment
</para>
</listitem>
<listitem>
<para>
<literal>ant deploy</literal> - deploy the example in compressed jar format to JBoss AS
</para>
</listitem>
<listitem>
<para>
<literal>ant undeploy</literal> - remove the example from JBoss AS
</para>
</listitem>
<listitem>
<para>
<literal>ant clean</literal> - clean the example
</para>
</listitem>
</itemizedlist>
</tip>
<para>
The second starter example, <literal>weld-translator</literal>, will translate your text into Latin. (Well,
not really, but the stub is there for you to implement, at least. Good luck!) To try it out, switch to the
translator example directory and execute the deploy target:
</para>
<programlisting><![CDATA[$> cd examples/jsf/translator
$> ant deploy]]></programlisting>
<note>
<para>
The translator uses session beans, which are packaged in an EJB module within an ear. Java EE 6 will allow
session beans to be deployed in war modules, but that's a topic for a later chapter.
</para>
</note>
<para>
Again, wait a few seconds for the application to deploy (if you're really bored, read the log messages), and
visit <ulink url="http://localhost:8080/weld-translator">http://localhost:8080/weld-translator</ulink> to begin
pseudo-translating.
</para>
</section>
<section id="glassfish">
<title>Deploying to GlassFish</title>
<para>
Deploying to GlassFish should be easy, right? After all, it's the Java EE 6 reference implementation. Since
it's the Java EE 6 reference implementation, that means it also bundles the JSR-299 reference implementation,
Weld! So yes, it's very easy.
</para>
<para>
To deploy the examples to GlassFish, you'll need the final <ulink
url="https://glassfish.dev.java.net/">GlassFish V3</ulink> release (the preview release won't do). If the final
release isn't yet available, you can download a <ulink
url="http://download.java.net/glassfish/v3/promoted/">promoted build</ulink> in the meantime. Select the b69
preview release or above that ends in either <literal>-unix.sh</literal> or <literal>-windows.exe</literal>
depending on your platform. After the download is complete, execute the installer. On Linux/Unix, you'll need
to first make the script executable.
</para>
<programlisting><![CDATA[$> chmod 755 glassfish-v3-b69-unix.sh
$> ./glassfish-v3-b69-unix.sh]]></programlisting>
<para>
On Windows you can just click on the executable. Follow the instructions in the installer. It will create a
single domain named <literal>domain1</literal>. You'll use that domain to deploy the example. We recommend that
you choose <literal>7070</literal> as the main HTTP port to avoid conflicts with a running instance of JBoss AS
(or Apache Tomcat).
</para>
<para>
If you've deployed either of the starter examples, <literal>weld-numberguess</literal> or
<literal>weld-translator</literal>, to JBoss AS, then you already have the deployable artifact you need.
If not, switch to either of the two directories and build it.
</para>
<programlisting><![CDATA[$> cd examples/jsf/numberguess (or examples/jsf/translator)
$> ant package]]></programlisting>
<para>
The deployable archive for the <literal>weld-numberguess</literal>, named <literal>weld-numberguess.war</literal>,
ends up in the example's <literal>target</literal> directory. The archive for the <literal>weld-translator</literal>
example, named <literal>weld-translator.ear</literal>, ends up in the example's <literal>ear/target</literal> directory.
All you need to do now is deploy them to GlassFish.
</para>
<para>
You deploy applications to GlassFish using the <ulink url="http://localhost:4848">GlassFish Admin
Console</ulink>. To get the Admin Console running, you need to start a GlassFish domain, in our case
<literal>domain1</literal>. Switch to the <literal>bin</literal> folder in the directory where you
installed GlassFish and execute the following command:
</para>
<programlisting><![CDATA[$> asadmin start-domain domain1]]></programlisting>
<para>
After a few seconds you can visit the Admin Console in the browser at the URL <ulink
url="http://localhost:4848">http://localhost:4848</ulink>. In the tree on the left-hand
side of the page, click on "Applications", then click on the "Deploy..." button under
the heading "Applications" and select the deployable artifact for either of the two examples.
The deployer should recognize that you have selected a Java EE artifact and allow you to
start it. You can see the examples running at either <ulink
url="http://localhost:7070/weld-numberguess">http://localhost:7070/weld-numberguess</ulink> or <ulink
url="http://localhost:7070/weld-translator">http://localhost:7070/weld-translator</ulink>,
depending on which example you deployed.
</para>
<para>
The reason the same artifact can be deployed to both JBoss AS and GlassFish, without any modifications, is
because all of the features being used are part of the standard platform. And what a capable platform it has
become!
</para>
</section>
<section id="tomcat">
<title>Deploying to Apache Tomcat</title>
<para>
Servlet containers are not required to support Java EE services like CDI. However, you can use CDI in a
servlet container like Tomcat by embedding a standalone CDI implementation such as Weld.</para>
<para>
Weld comes with a servlet listener which bootstraps the CDI environment, registers the <literal>BeanManager</literal>
in JNDI and provides injection into servlets. Basically, it emulates some of the work done by the Java EE
container. (But you don't get enterprise features such as session beans and container-managed transactions.)
</para>
<para>
Let's give the Weld servlet extension a spin on Apache Tomcat. First, you'll need to download Tomcat 6.0.18 or
later from <ulink url="http://tomcat.apache.org/download-60.cgi">tomcat.apache.org</ulink> and extract it.
</para>
<programlisting><![CDATA[$> unzip apache-tomcat-6.0.18.zip]]></programlisting>
<para>
You have two choices for how you can deploy the application to Tomcat. You can deploy it by pushing the
artifact to the hot deploy directory using Ant or you can deploy to the server across HTTP using a Maven
plugin. The Ant approach doesn't require that you have Maven installed, so we'll start there. If you want to
use Maven, you can just skip ahead.
</para>
<section id="tomcat-ant">
<title>Deploying with Ant</title>
<para>
In order for Ant to push the artifact to the Tomcat hot deploy directory, it needs to know where the Tomcat
installation is located. Again, we need to set a property in the <literal>local.build.properties</literal>
file in the examples directory of the Weld distribution. If you haven't yet created this file, do so now.
Then assign the path of your Tomcat installation to the property key <literal>tomcat.home</literal>.
</para>
<programlisting><![CDATA[tomcat.home=/path/to/apache-tomcat-6]]></programlisting>
<para>
Now you're ready to deploy the numberguess example to Tomcat!
</para>
<para>
Change to the <literal>examples/jsf/numberguess</literal> directory again and run the Ant <literal>deploy</literal>
target for Tomcat:
</para>
<programlisting><![CDATA[$> cd examples/jsf/numberguess
$> ant tomcat.deploy]]></programlisting>
<tip>
<para>
The Ant build script includes additional targets for Tomcat to deploy and undeploy the archive in either
exploded or packaged format. They are the same target names used for JBoss AS, prefixed with "tomcat.".
</para>
<itemizedlist>
<listitem>
<para>
<literal>ant tomcat.restart</literal> - deploy the example in exploded format to Tomcat
</para>
</listitem>
<listitem>
<para>
<literal>ant tomcat.explode</literal> - update an exploded example, without restarting the deployment
</para>
</listitem>
<listitem>
<para>
<literal>ant tomcat.deploy</literal> - deploy the example in compressed jar format to Tomcat
</para>
</listitem>
<listitem>
<para>
<literal>ant tomcat.undeploy</literal> - remove the example from Tomcat
</para>
</listitem>
</itemizedlist>
</tip>
<para>
If you haven't already, start Tomcat. You can either start Tomcat from a Linux shell:
</para>
<programlisting><![CDATA[$> cd /path/to/apache-tomcat-6
$> ./bin/start.sh]]></programlisting>
<para>
a Windows command window:
</para>
<programlisting><![CDATA[$> cd c:\path\to\apache-tomcat-6\bin
$> start]]></programlisting>
<para>
or you can start the server using an IDE, like Eclipse.
</para>
<para>
Wait a few seconds for the application to deploy (or the application server to start) and see if you can figure
out the most efficient approach to pinpoint the random number at the local URL
<ulink url="http://localhost:8080/weld-numberguess">http://localhost:8080/weld-numberguess</ulink>!
</para>
</section>
<section id="tomcat-maven">
<title>Deploying with Maven</title>
<para>
You can also deploy the application to Tomcat using Maven. This section is a bit more advanced, so skip it
unless you're itching to use Maven natively. Of course, you'll first need to make sure that you have Maven
installed on your path, similar to how you setup Ant.
</para>
<para>
The Maven plugin communicates with Tomcat over HTTP, so it doesn't care where you have installed Tomcat.
However, the plugin configuration assumes you are running Tomcat in its default configuration, with a hostname
of localhost and port <literal>8080</literal>. The <literal>readme.txt</literal> file in the example directory
has information about how to modify the Maven settings to accommodate a different setup.
</para>
<para>
To allow Maven to communicate with Tomcat over HTTP, edit the <literal>conf/tomcat-users.xml</literal> file in
your Tomcat installation and add the following line:
</para>
<programlisting role="XML"><![CDATA[<user username="admin" password="" roles="manager"/>]]></programlisting>
<para>
Restart Tomcat. You can now deploy the application to Tomcat with Maven using this command:
</para>
<programlisting><![CDATA[$> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
<para>
Once the application is deployed, you can redeploy it using this command:
</para>
<programlisting><![CDATA[$> mvn tomcat:redeploy -Ptomcat]]></programlisting>
<para>
The <literal>-Ptomcat</literal> argument activates the <literal>tomcat</literal> profile defined in the Maven POM
(<literal>pom.xml</literal>). Among other things, this profile activates the Tomcat plugin.
</para>
<para>
Rather than shipping the container off to a standalone Tomcat installation, you can also execute the
application in an embedded Tomcat 6 container:
</para>
<programlisting><![CDATA[$> mvn war:inplace tomcat:run -Ptomcat]]></programlisting>
<para>
The advantage of using the embedded server is that changes to assets in <literal>src/main/webapp</literal> take effect
immediately. If a change to a webapp configuration file is made, the application may automatically redeploy
(depending on the plugin configuration). If you make a change to a classpath resource, you need to execute a
build:
</para>
<programlisting><![CDATA[$> mvn compile war:inplace -Ptomcat]]></programlisting>
<para>
There are several other Maven goals that you can use if you are hacking on the example, which are documented in
the example's <literal>readme.txt</literal> file.
</para>
</section>
</section>
<section id="jetty">
<title>Deploying to Jetty</title>
<!-- subsections? -->
<para>
Support for Jetty in the examples is a more recent addition. Since Jetty is traditionally used with Maven,
there are no Ant targets. You must invoke the Maven build directly to deploy the examples to Jetty out of the
box. Also, only the <literal>weld-numberguess</literal> example is configured for Jetty support at the time of
writing.
</para>
<para>
If you've read through the entire Tomcat section, then you're all ready to go. The Maven build parallels the
embedded Tomcat deployment. If not, don't worry. We'll still go over everything that you need to know again
in this section.
</para>
<para>
The Maven POM (<literal>pom.xml</literal>) includes a profile named <literal>jetty</literal> that activates the
Maven Jetty plugin, which you can use
to start Jetty in embedded mode and deploy the application in place. You don't need anything else installed
except to have the Maven command (<literal>mvn</literal>) on your path. The rest will be downloaded from the
internet when the
build is run.
</para>
<para>
To run the <literal>weld-numberguess</literal> example on Jetty, switch to the example directory and execute
the <literal>inplace</literal> goal of the Maven war plugin followed by the <literal>run</literal> goal of
the Maven Jetty plugin with the <literal>jetty</literal> profile enabled, as follows:
</para>
<programlisting><![CDATA[$> cd examples/jsf/numberguess
$> mvn war:inplace jetty:run -Pjetty]]></programlisting>
<para>
The log output of Jetty will be shown in the console. Once Jetty reports that the application has deployed, you
can access it at the following local URL: <ulink
url="http://localhost:9090/weld-numberguess">http://localhost:9090/weld-numberguess</ulink>. The port is
defined in the Maven Jetty plugin configuration within the <literal>jetty</literal> profile.
</para>
<para>
Any changes to assets in <literal>src/main/webapp</literal> take effect immediately. If a change to a webapp
configuration file is made, the application may automatically redeploy. The redeploy behavior can be fined-tuned
in the plugin configuration. If you make a change to a classpath resource, you need to execute a build and the
<literal>inplace</literal> goal of the Maven war plugin, again with the <literal>jetty</literal> profile enabled.
</para>
<programlisting><![CDATA[$> mvn compile war:inplace -Pjetty]]></programlisting>
<para>
The <literal>war:inplace</literal> goal copies the compiled classes and jars inside <literal>src/main/webapp</literal>,
under <literal>WEB-INF/classes</literal> and <literal>WEB-INF/lib</literal>, respectively, mixing source and compiled
files. However, the build does work around these temporary files by excluding them from the packaged war and cleaning
them during the Maven clean phase.
</para>
<para>
You have two options if you want to run the example on Jetty from the IDE. You can either install the
m2eclispe[link] plugin and run the goals as described above. Your other option is to start the Jetty container
from a Java application.
</para>
<para>
First, initialize the Eclipse project:
</para>
<programlisting><![CDATA[$> mvn clean eclipse:clean eclipse:eclipse -Pjetty-ide]]></programlisting>
<para>
Next, assemble all the necessary resources under <literal>src/main/webapp</literal>:
</para>
<programlisting><![CDATA[$> mvn war:inplace -Pjetty-ide]]></programlisting>
<para>
Now, you are ready to run the server in Eclipse. Import the project into your Eclipse workspace using "Import
Existing Project into Workspace. Then, find the start class in <literal>src/jetty/java</literal> and run its
main method as a Java Application. Jetty will launch. You can view the application at the following local URL: <ulink
url="http://localhost:8080">http://localhost:8080</ulink>. Pay particular attention to the port in the URL and
the lack of a trailing context path.
</para>
<para>
Now that you have gotten the starter applications deployed on the server of your choice, you probably want to
know a little bit about how they actually work.
</para>
</section>
<!--
vim:et:ts=3:sw=3:tw=120
-->
</chapter>