The examples for each chapter reside in a sub-directory in the source bundle. The index below indicates the location of each numbered example within the example source code bundle.
In addition, the examples
have been configured with an Ant build script, based on a template
provided among the Ant examples. You can use the Ant
scripts to compile, assemble, deploy and run the examples in your
development environment. There is a main build.xml file
at the top of the examples directory, that can be used to perform
all these tasks against all of the examples. If you're only interested
in exploring a particular chapter, you can use the build.xml file
found in each chapter sub-directory to work with just that chapter's
examples.
We've gone to some lengths to ensure that the examples will be portable across different J2EE environments. We have only done complete testing of the examples using the JBoss 4 application server and Axis 1.2 web service engine. So unless you have a need to use a specific application server or web service engine, we suggest that you explore the examples in that environment, at least to start.
In either case, before you can use the build scripts, you have to configure them. If you want to just dig in and look at the code, the sections below indicate where to find the source for the examples in each chapter. If you want to build and run the examples using the Ant build scripts, start by reading over the Ant Template Guide. Then run through the following steps.
In order for the build scripts to work, you'll need to download Ant, as well as the required libraries used by the examples (as indicated in each section of the index below). Some chapters require a full J2EE 1.4-compatible application server. Some also require access to a relational database along with the appropriate JDBC driver. Note that some of the examples only require a web container, such as Tomcat, and others are standalone examples that don't require an application server at all. But in order to run all of the examples, you'll need a full J2EE server, such as JBoss, Geronimo, WebLogic, etc.
In addition to the software above, the EJB-related
tasks in the build scripts require the Apache
BCEL library. The ejbjar task uses BCEL
to determine what dependent classes to include in ejb-jar files.
You should download this library and ensure it's in your Ant runtime
classpath. The easiest way to do this is to copy the jar file into
your ANT_HOME/lib directory.
JBoss oddities: If you are using JBoss 4.0.2 or
later, be sure to go into the server/default/deploy/jbossweb-tomcat55.sar/META-INF/jboss-service.xml file, and change the value of the UseJBossWebLoader attribute to
true. Between 4.0.1 and 4.0.2, the JBoss gang decided to change the
fundamental classloading defaults in their server, which throws lots
of generic J2EE applications (like those making local EJB calls from
web components) for a loop. Changing this configuration parameter
(mostly) restores the previous behavior.
Once you've acquired the necessary software, you need to configure
the build scripts to tell them where the libraries are, how to connect
to the database, and which J2EE server you are using. As detailed
in the Ant Template Guide, at a minimum you'll need to specify the
location of the code libraries you downloaded by adding the necessary
property override(s) to the local-build.properties file, and you'll
need to indicate the necessary configuration parameters for the application
server you are using in the same local-build.properties file.
For most purposes, the only targets you'll need to use with the
examples are deploy-app (to build and deploy each chapter's
examples), and run-examples (to run examples, in those
chapters where the examples can be run). If the examples include
web interfaces that are deployed, then the URLs for the examples
will be printed by the Ant script after deploy-app finishes.
In some
cases, other targets might be handy -- the unit tests in Ch. 18,
for example, are run using the run-tests target.
Refer to the Ant
Template Guide for
descriptions of these other targets.
You can run a target in all the chapter sub-directories by using
the top-level build.xml file, or you can go into a specific chapter
sub-directory and run the target only with those examples. The top-level
build.xml simply exercises all the other build scripts in the sub-directories
for you, to make it easy to compile all the book's code, for example.
This chapter describes the overall J2EE assembly and deployment model. The examples demonstrate assembly of web and EJB component modules into full applications.
The examples in this chapter are sample deployment descriptors with no code of their own. However, the deployment descriptors shown here are the basis for deployment descriptors for examples in Chapters 12, 18 and 21.
Examples directory: ch03-Servlets
The examples for this chapter only require a web container or web-container-enabled
application server. The server must be compliant with the Servlet
2.4 specification. Most if not all of the examples will
also work in a Servlet 2.3 environment, but the web.xml deployment descriptors will need to be adjusted slightly.
No additional software libraries are required.
Examples directory: ch04-JSP
The examples for this chapter only require a web container or
web-container-enabled application server. The server must be compliant
with the Servlet 2.4 and JSP 2.0 specifications. Most if not all
of the examples will also work in a Servlet 2.3 and JSP 1.2 environment,
but the web.xml deployment descriptors will need to be adjusted
slightly.
No additional software libraries are required.
All other un-numbered examples from the chapter can be found
in the web and src/java directories
in this chapter sub-directory.
Examples directory: ch05-JSF
The examples for this chapter require a web container or
web-container-enabled application server. The server must be compliant
with the Servlet 2.4 and JSP 2.0 specifications. Most if not all
of the examples will also work in a Servlet 2.3 and JSP 1.2 environment,
but the web.xml deployment descriptors will need to
be adjusted slightly.
These examples also require a JSF 1.1 implementation. The examples
were developed using the Sun
JSF 1.1 reference implementation,
and smoke-tested against the Apache
MyFaces JSF implementation. Once you've downloaded either one,
be sure to set either the sun.jsf.* or myfaces.jsf.* properties
in the
build.properties file, and override if needed in your local-build.properties.
If you're using the same versions specified there, and if they
are unpacked in the lib.dir directory, you shouldn't
need to add anything to your local-build.properties.
The ch05-JSF/build.xml file is configured to use the
Sun JSF implementation by default. If you want to use MyFaces instead,
you'll need to adjust the java.compile.classpath path
variable near the top of the build file, and also adjust the list
of jars included in the war file in the create-wars target
near the end of the build file. You'll also need to uncomment the
MyFaces listener at the bottom of the config/web.xml deployment
descriptor.
If you are using JBoss 4.0.3 or later, then the Apache MyFaces
JSF implementation is included in the server (yet another major
change made in a sub-minor JBoss release). To avoid conflicts with
the installed JSF libraries, you should remove any JSF libraries
from the create-wars target.
Also, you will need to un-comment the MyFaces listener in the config/web.xml.
Examples directory: ch06-EJB
The examples in this chapter require an EJB 2.1-compliant container, as found in J2EE 1.4-compliant application servers like JBoss 4, Geronimo 1.0, WebLogic 9, etc.
The EJB components also require access to a suitable relational
database, to support the JDBC DataSource resources
specified in their deployment descriptors. The SQL required to
create the database can be found in the file ch06-EJB/src/sql/profile.sql.
The deployment descriptors reference this DataSource using
the JNDI name jdbc/ProfileDB, so a DataSource resource
needs to be mapped to this JNDI name in the overall application
server resource space.
Sample clients for each of the EJB components can be found in
each sub-package of the example source. The jndi.properties used
to run the clients will need to be set up to suit the application
server you are using, so that the clients can access the server's
JNDI service to access the EJB homes.
Examples directory: ch07-XML
The examples in this chapter only require a JAXP 1.2-compliant
environment. If you are running
these examples in a Java 1.4 runtime, then a suitable JAXP implementation
should be in the runtime already. If you need a separate JAXP implementation
for some reason, then your best bet is the Apache
Xerces and Xalan libraries. You will need to add these libraries to the build script
yourself, though, by adding them to the java.compile.classpath path
variable near the beginning of the ch07-XML/build.xml file.
Examples directory: ch08-JDBC
The JDBC examples only require the JDBC API (built into the Java
core runtime), and a suitable database driver. Each example has
slightly different requirements, as described below. In each case,
you'll need to make sure that the JDBC drivers are included in
the java.compile.classpath path definition near the top of the
ch08-JDBC/build.xml build file.
Example 8-1 requires a JDBC-ODBC
bridge driver (included in most, but not all, Java runtime environments),
and an ODBC DSN named "companydb", configured to connect to any
suitable database engine. The target database must have an appropriate
"employees" table created in it. See ch08-JDBC/src/sql/employees.sql for
the SQL needed to create the necessary table.
Example 8-2 requires
a MySQL database named
"test" with an appropriate "people" table created in the schema,
and a JDBC 3.0-compliant MySQL JDBC driver, such as the MySQL
Connector. See ch08-JDBC/src/sql/people.sql for
the SQL needed to create the necessary table. Note that the
SQL contained in this file contains MySQL-specific syntax,
and won't work in other databases.
Example 8-3 requires an Oracle database with the TNS name "customerdb",
with an appropriate "customers" table created in the schema. You'll
need an Oracle JDBC driver as well, available from the
Oracle
site. See ch08-JDBC/src/sql/customers.sql for
the SQL needed to create the necessary table.
Examples directory: ch09-JNDI
These examples require the JNDI API (included in the core Java runtime environment), and an LDAP server. In order to exercise all of the examples, you'll need both read and write access to the server. Some of the examples will work against other types of directories, such as the local file system (using the JNDI file system provider), a CORBA Naming Service, or an Active Directory server. But some of the later examples demonstrate LDAP-specific JNDI extensions, so they will only work with an LDAP-compliant server, such as the open source OpenLDAP server.
The JNDI server you want to use is configured using the ch09-JNDI/config/jndi.properties file.
When you run the run-examples target in the build script, this
properties file is added to the runtime classpath in order to pick
up the standard JNDI runtime properties. The default properties
file bundled here uses Sun's
file system provider to run the examples
against your local filesystem. You'll need to download the provider
and then set up the jndi.fs.* properties from the
top-level build.properties file. If you
want to use a different type of JNDI server, such as an LDAP server,
you'll need to adjust the jndi.properties to suit, and add the
provider's classes to the java.compile.classpath path
variable near the top of the ch09-JNDI/build.xml file.
Examples directory: ch10-Security
The examples in this chapter require a full J2EE server, since they use both web components and EJB components to demonstrate J2EE security features. No other additional software is needed.
The examples depend on a set of roles used to control access,
as detailed in the various deployment descriptors. They are referenced
using the names vip, buyer, seller,
admin and TaxServiceUserRole.
These roles will need to be mapped to actual group/role definitions
in the security services of your application server. These mappings
will need to be included with the application in order for the examples
to deploy and run cleanly. Sample files showing how these role mappings
might be made for a WebLogic server are provided with the deployment
descriptors in the config directory.
Examples directory: ch11-JMS
These examples require a J2EE server with the appropriate JMS
resources configured. You will need at least one Topic and one Queue,
with corresponding factories. Each example client uses command-line
arguments for the JNDI names of the JMS Destination and ConnectionFactory resources, so you can configure these any way you want, or even
use default JMS resources if your application server provides them.
You'll also need to make sure that the jndi.properties file in
the CLASSPATH when running the clients is configured to reference
the JNDI service of the application server with the JMS resources.
Examples directory: ch12-WebServices
The examples in this chapter require a J2EE application server
(both web and EJB components are used in the examples). They also
require a web service engine, such as Axis.
These examples have been tested using the Axis 1.2 engine. If you
want to use a different web service engine, you'll need to create
a suitable web service engine config file for the Ant build script,
based on the wse-configs/wse-axis-config.xml.
If you use the suggested JBoss 4 environment, and the Axis web
service engine, then be sure to disable the internal JBoss web
service engine by moving/removing the server/default/deploy/jboss-wsee.sar directory
(assuming you are using the "default" server instance).
Examples directory: ch13-RMI
These examples only require a Java runtime environment.
Examples directory: ch14-CORBA
These examples only require a Java runtime environment.
Examples directory: ch15-JavaMail
The examples in this chapter require an implementation of
the JavaMail API. This is available bundled with most J2EE application
servers, like JBoss, Geronimo and WebLogic, or as a separate
download from Sun. JavaMail also requires the Java Activation
Framework (JAF), which is also bundled with application servers,
or downloadable
separately from Sun. If you have configured the
build scripts to use one of the application server configurations,
then the JavaMail and JAF implementations should be included in
the classpath for you. If you'd like to experiment with these examples
without an application server, then you'll need to download the
JavaMail and JAF implementations and add them to the java.compile.classpath path variable in ch15-JavaMail/build.xml.
If you want to try running these examples, be sure to review the source and adjust the hardcoded string literals there. These specify the various email servers, accounts and addresses used to send/receive email.
Examples directory: ch16-Transactions
The examples in this chapter require a full J2EE application server, since they use both web and EJB components.
The entity EJB components require a database initialized using
the SQL found in ch16-Transactions/src/sql/sem.sql. The database
is accessed using a DataSource that is expected to reside under
the name jdbc/semJDBCDataSource in the JNDI service, so this will
need to be mapped to an appropriate DataSource in the application
server's configuration.
Both the web and EJB components access JMS resources as well,
as detailed in the various deployment descriptors. The components
expect to find an XA-enabled ConnectionFactory under
the JNDI name
jms/semConnectionFactory, a Queue destination
under the JNDI name jms/semConnectionFactory, and
another Queue under the JNDI name jms/semPersonQueue.
These JNDI names will have to be mapped to appropriate JMS resources
in the application server configuration.
Examples directory: ch17-Ant
The examples in this chapter require Ant 1.6. To run the enterprise-level Ant targets and the portable Ant template, you'll need a full J2EE application server, such as JBoss.
Examples directory: ch18-JUnitCactus
The examples in this chapter use require JUnit
3.8.1 and Cactus
1.6 or greater. Once you've downloaded these, check the junit.* and cactus.* properties defined in the top-level build.properties file, and make any necessary overrides in your local-build.properties.
In order to use the Ant examples in the chapter, you'll need to
enable your Ant environment with the JUnit and Cactus libraries.
The easiest way to do this is to copy the JUnit and Cactus libraries
(all of the jars referenced in the build properties mentioned above)
into your ANT_HOME/lib directory, where ANT_HOME is wherever you've
installed Ant. If you are using an IDE like Eclipse to run your
Ant builds, you'll need to adjust its internal configuration to
include the JUnit and Cactus libraries in the Ant runtime.
You'll also need to adjust the ch18-JUnitCactus/config/persondao.xml file, to ensure that the xml-file value points to the people-data.xml file contained in the same config directory. This file contains
the sample data loaded by the application.
The example unit tests can be exercised using the run-tests target.
This build the application, run the local unit tests (examples
18-1 through 18-3), then deploy the test-enabled application archive
and run the server-side Cactus tests (examples 18-7 through 18-11).
Examples directory: ch19-Struts
The examples in this chapter require Apache
Struts 1.2. You'll also need to download the Apache
Jakarta Commons-Lang 2.0 library. After downloading the Struts package,
check the struts.* properties
defined in the top-level build.properties file, and
make any necessary overrides in your local-build.properties.
Examples directory: ch20-Hibernate
The examples in this chapter require Hibernate
3.0. After downloading
Hibernate, check the hibernate.* properties in the top-level build.properties file and make any necessary overrides in your local-build.properties.
The examples also require a relational database configured with
the schema elements contained in the ch20-Hibernate/src/sql/university.sql file.
Examples directory: ch21-Annotations
The examples in the first half of this chapter (21-1 through 21-12)
require XDoclet
1.2. After downloading the software, check the xdoclet.* properties
in the top-level build.properties file, and make any
necessary overrides
in your local-build.properties file.
The examples in the second half of the chapter (21-13 through
21-16) only require a Java 5.0 environment. If you want to run
these examples, make sure that your Ant environment is running
in a Java 5.0 runtime.
Examples directory: appA-Deployment