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. The examples 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:

http://java.sun.com/javase/downloads/index_jdk5.jsp

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:

http://java.sun.com/javaee/downloads/index.html 

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:

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 is C:\Sun\SDK, so <JAVAEE_HOME> is C:\Sun\SDK.

Add the <JAVAEE_HOME>/bin directory to your PATH 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 the ant command, add <JAVAEE_HOME>/lib/ant/bin to your PATH 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.

  1. Select ToolsRight ArrowServer Manager to open the Server Manager dialog.
  2. Click Add Server.
  3. Under Server, select Sun Java System Application Server and click Next.
  4. Under Platform Location, enter the location of your Application Server installation.
  5. Select Register Local Default Domain and click Next.
  6. Under Admin Username and Admin Password, enter the admin name and password you specified while installing the Application Server.
  7. 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 to build.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:


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 is C:\Sun\SDK, you must set javaee.home as follows:

javaee.home = C:\\Sun\\SDK

or

javaee.home=C:/Sun/SDK


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:

Examples 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 a build subdirectory and to copy and compile files into that directory; a dist subdirectory, which holds the packaged module file; and a client-jar directory, which holds the retrieved application client JAR.