About the Examples
This section tells you everything you need to know to install, build, and run the examples.
Required Software
The following software is required to run the examples.
Tutorial Bundle
The tutorial example source is contained in the tutorial bundle. If you are viewing this online, you need to click on the Download link at the top of any page.
After you have installed the tutorial bundle, the example source code is in the
<
INSTALL
>/javaeetutorial5/examples/
directory, where<
INSTALL
>
is the directory where you installed the tutorial. Theexamples
directory contains subdirectories for each of the technologies discussed in the tutorial.Java 2 Platform, Standard Edition
To build, deploy, and run the examples, you need a copy of Java 2 Platform, Standard Edition 5.0 (J2SE 5.0). You can download the J2SE 5.0 software from:
Download the current JDK update that does not include any other software (such as NetBeans or Java EE).
Java EE 5 SDK with NetBeans 5.5
The Sun Java System Application Server Platform Edition 9 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run the examples, you need a copy of the Application Server and, optionally, NetBeans 5.5. You can download the Application Server from:
Scroll down to the section entitled "Java EE 5 SDK Update 2" and click the Download with Tools button. This SDK contains Sun Java System Application Server Platform Edition 9 Update 1 and NetBeans 5.5.
Java EE 5 SDK Installation Tips
In the Admin configuration pane of the SDK installer:
- Accept the default admin user name and password. The user name is
admin
, and the password isadminadmin
. You will need this user name and password to log in to the Admin Console.- Note the HTTP port at which the server is installed. This tutorial assumes that you are accepting the default port of 8080. If 8080 is in use during installation and the installer chooses another port or if you decide to change it yourself, you will need to update the common build properties file (described in the next section) and the configuration files for some of the tutorial examples to reflect the correct port.
This tutorial refers to the directory where you install the Java EE 5 SDK as
<
JAVAEE_HOME
>
. For example, the default installation directory on Microsoft Windows isC:\Sun\SDK
, so<
JAVAEE_HOME
>
isC:\Sun\SDK
.Add the
<
JAVAEE_HOME
>/bin
directory to yourPATH
environment variable.NetBeans 5.5
The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise applications. Net-Beans 5.5 supports the Java EE 5 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans 5.5.
Apache Ant
Ant is a Java technology-based build tool developed by the Apache Software Foundation (
http://ant.apache.org
), and is used to build, package, and deploy the tutorial examples. Ant is included with the Application Server. To use theant
command, add<
JAVAEE_HOME
>/lib/ant/bin
to yourPATH
environment variable.Registry Server
You need a registry server to run the examples discussed in Chapter 19. Instructions for obtaining and setting up a registry server are provided in Chapter 19.
Building the Examples
The tutorial examples are distributed with a configuration file for either NetBeans 5.5 or Ant. Directions for building the examples are provided in each chapter. Either NetBeans 5.5 or Ant may be used to build, package, deploy, and run the examples.
Building the Examples Using NetBeans 5.5
To run the tutorial examples in NetBeans 5.5, you must register your Application Server installation as a NetBeans Server Instance. Follow these instructions to register the Application Server in NetBeans 5.5.
- Select Tools
Server Manager to open the Server Manager dialog.
- Click Add Server.
- Under Server, select Sun Java System Application Server and click Next.
- Under Platform Location, enter the location of your Application Server installation.
- Select Register Local Default Domain and click Next.
- Under Admin Username and Admin Password, enter the admin name and password you specified while installing the Application Server.
- Click Finish.
Building the Examples on the Command-Line Using Ant
Build properties common to all the examples are specified in the
build.properties
file in the<
INSTALL
>/javaeetutorial5/examples/bp-project/
directory. You must create this file before you can run the examples. We've included a sample file,build.properties.sample
, that you should rename tobuild.properties
and edit to reflect your environment. The tutorial examples use the Java BluePrints (http://java.sun.com/reference/blueprints/
) build system and application layout structure.To run the Ant scripts, you must set common build properties in the file
<
INSTALL
>/javaeetutorial5/examples/bp-project/build.properties
as follows:
- Set the
javaee.home
property to the location of your Application Server installation. The build process uses thejavaee.home
property to include the libraries in<
JAVAEE_HOME
>/lib/
in the classpath. All examples that run on the Application Server include the Java EE library archive--<
JAVAEE_HOME
>/lib/javaee.jar
--in the build classpath. Some examples use additional libraries in<
JAVAEE_HOME
>/lib/
; the required libraries are enumerated in the individual technology chapters.<
JAVAEE_HOME
>
refers to the directory where you have installed the Application Server.
Note: On Windows, you must escape any backslashes in the
javaee.home
property with another backslash or use forward slashes as a path separator. So, if your Application Server installation isC:\Sun\SDK
, you must setjavaee.home
as follows:javaee.home = C:\\Sun\\SDK
orjavaee.home=C:/Sun/SDK
- Set the
javaee.tutorial.home
property to the location of your tutorial. This property is used for Ant deployment and undeployment.For example, on UNIX:
javaee.tutorial.home=/home/username/javaeetutorial5
On Windows:
javaee.tutorial.home=C:/javaeetutorial5
Do not install the tutorial to a location with spaces in the path.
- If you did not accept the default values for the admin user and password, set the
admin.user
property to the value you specified when you installed the Java EE 5 SDK, and set the admin user's password in theadmin-password.txt
file in the<
INSTALL
>/javaeetutorial5/examples/common
directory to the value you specified when you installed the Java EE 5 SDK.- If you did not use port 8080, set the
domain.resources.port
property to the value specified when you installed the Application Server.Tutorial Example Directory Structure
To facilitate iterative development and keep application source separate from compiled files, the tutorial examples use the Java BluePrints application directory structure.
Each application module has the following structure:
build.xml
: Ant build filesrc/java
: Java source files for the modulesrc/conf
: configuration files for the module, with the exception of web applicationsweb
: JSP and HTML pages, style sheets, tag files, and imagesweb/WEB-INF
: configuration files for web applicationsnbproject
: NetBeans project filesExamples that have multiple application modules packaged into an enterprise application archive (or EAR) have submodule directories that use the following naming conventions:
The Ant build files (
build.xml
) distributed with the examples contain targets to create abuild
subdirectory and to copy and compile files into that directory; adist
subdirectory, which holds the packaged module file; and aclient-jar
directory, which holds the retrieved application client JAR.