The Java EE 5 Tutorial

Chapter 2 Using the Tutorial Examples

This chapter tells you everything you need to know to install, build, and run the examples. It covers the following topics:

Required Software

The following software is required to run the examples.

Tutorial Bundle

The tutorial example source is contained in the tutorial bundle. To obtain the tutorial bundle, go to http://java.sun.com/javaee/5/docs/tutorial/information/download.html. The tutorial bundle is a zip file that you can unzip in a location of your choice.

After you have installed the tutorial bundle, the example source code is in the tut-install/javaeetutorial5/examples/ directory, where tut-install is the directory where you installed the tutorial. The examples directory contains subdirectories for each of the technologies discussed in the tutorial.

Java Platform, Standard Edition

To build, deploy, and run the examples, you need a copy of Java Platform, Standard Edition 5.0 or Java Platform, Standard Edition 6.0 (J2SE 5.0 or JDK 6). You can download the J2SE 5.0 software from http://java.sun.com/javase/downloads/index_jdk5.jsp. You can download the JDK 6 software from http://java.sun.com/javase/downloads/.

Download the current JDK update that does not include any other software (such as NetBeans or Java EE).

Sun Java System Application Server 9.1

Sun Java System Application Server 9.1 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 IDE. You can download the Application Server from http://java.sun.com/javaee/downloads/.

Scroll down to the section entitled Download the Components Independently and click the Download link next to Sun Java System Application Server 9.1 (based on GlassFish V2).

Note –

You can also run the tutorial examples using Sun Java System Application Server 9.0, or using GlassFish V2.

Refer to the Java EE Tutorial Compatibility Wiki page for information about the versions of the Application Server and the Sun GlassFish Enterprise Server with which the tutorial examples have been tested.

Application Server Installation Tips

During the installation of the Application Server:

Accept the default admin user name, and specify a password. The default user name is admin. Remember the password you specify (for example, adminadmin). You will need this user name and password.
Select the Don't Prompt for Admin User Name and Password radio button.
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 Application Server as as-install. For example, the default installation directory on Microsoft Windows is C:\Sun\AppServer, so as-install is C:\Sun\AppServer.

After you install the Application Server, add the following directories to your PATH to avoid having to specify the full path when you use commands:

as-install/bin
as-install/lib/ant/bin

NetBeans IDE

The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise applications. NetBeans IDE supports the Java EE 5 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans IDE.

You can download NetBeans IDE from http://www.netbeans.org/.

Refer to the Java EE Tutorial Compatibility Wiki page for information about the versions of NetBeans IDE with which the tutorial examples have been tested.

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 as-install/lib/ant/bin to your PATH environment variable.

Starting and Stopping the Application Server

To start the Application Server, open a terminal window or command prompt and execute the following:

asadmin start-domain --verbose domain1

A domain is a set of one or more Application Server instances managed by one administration server. Associated with a domain are the following:

The Application Server’s port number. The default is 8080.
The administration server’s port number. The default is 4848.
An administration user name and password.

You specify these values when you install the Application Server. The examples in this tutorial assume that you chose the default ports.

With no arguments, the start-domain command initiates the default domain, which is domain1. The --verbose flag causes all logging and debugging output to appear on the terminal window or command prompt (it will also go into the server log, which is located in domain-dir/logs/server.log).

Or, on Windows, you can choose:

Programs -> Sun Microsystems -> Application Server PE 9 -> Start Default Server

After the server has completed its startup sequence, you will see the following output:

Domain domain1 started.

To stop the Application Server, open a terminal window or command prompt and execute:

asadmin stop-domain domain1

Or, on Windows, choose:

Programs -> Sun Microsystems -> Application Server PE 9 -> Stop Default Server

When the server has stopped you will see the following output:

Domain domain1 stopped.

Starting the Admin Console

To administer the Application Server and manage users, resources, and Java EE applications, use the Admin Console tool. The Application Server must be running before you invoke the Admin Console. To start the Admin Console, open a browser at http://localhost:4848/asadmin/.

On Windows, from the Start menu, choose:

Programs -> Sun Microsystems -> Application Server PE 9 -> Application Server

Starting and Stopping the Java DB Database Server

The Application Server includes the Java DB database.

To start the Java DB database server, open a terminal window or command prompt and execute:

asadmin start-database

On Windows, from the Start menu, choose:

Programs -> Sun Microsystems -> Application Server PE 9 -> Start Java DB

To stop the Java DB server, open a terminal window or command prompt and execute:

asadmin stop-database

On Windows, from the Start menu, choose:

Programs -> Sun Microsystems -> Application Server PE 9 -> Stop Java DB

For information about the Java DB database included with the Application Server, see http://developers.sun.com/javadb/.

Building the Examples

The tutorial examples are distributed with a configuration file for either NetBeans IDE or Ant. Directions for building the examples are provided in each chapter. Either NetBeans IDE or Ant may be used to build, package, deploy, and run the examples.

Building the Examples Using NetBeans IDE

To run the tutorial examples in NetBeans IDE, you must register your Application Server installation as a NetBeans Server Instance. Follow these instructions to register the Application Server in NetBeans IDE.

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 created when you installed 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 tut-install/javaeetutorial5/examples/bp-project/ directory. You must create this file before you can run the examples. Copy the file build.properties.sample to build.properties and edit it to reflect your environment. The tutorial examples use the Java BluePrints build system and application layout structure.

To run the Ant scripts, you must set common build properties in the file tut-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 the javaee.home property to include the libraries in as-install/lib/ in the classpath. All examples that run on the Application Server include the Java EE library archive, as-install/lib/javaee.jar. in the build classpath. Some examples use additional libraries in as-install/lib/; the required libraries are enumerated in the individual technology chapters.

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\AppServer, you must set javaee.home to javaee.home = C:\\Sun\\AppServer or javaee.home=C:/Sun/AppServer.
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 Application Server, and set the admin user’s password in the admin-password.txt file in the tut-install/javaeetutorial5/examples/common/ directory to the value you specified when you installed the Application Server.
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 file
src/java: Java source files for the module
src/conf: configuration files for the module, with the exception of web applications
web: JSP and HTML pages, style sheets, tag files, and images
web/WEB-INF: configuration files for web applications
nbproject: NetBeans project files

Examples that have multiple application modules packaged into an enterprise application archive (or EAR) have submodule directories that use the following naming conventions:

example-name-app-client: Application clients
example-name-ejb: Enterprise bean JAR files
example-name-war: web applications

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.

Debugging Java EE Applications

This section describes how to determine what is causing an error in your application deployment or execution.

Using the Server Log

One way to debug applications is to look at the server log in domain-dir/logs/server.log. The log contains output from the Application Server and your applications. You can log messages from any Java class in your application with System.out.println and the Java Logging APIs (documented at http://java.sun.com/javase/6/docs/technotes/guides/logging/index.html) and from web components with the ServletContext.log method.

If you start the Application Server with the --verbose flag, all logging and debugging output will appear on the terminal window or command prompt and the server log. If you start the Application Server in the background, debugging information is only available in the log. You can view the server log with a text editor or with the Admin Console log viewer.

To use the log viewer:

Select the Application Server node.
Select the Logging tab.
Click the Open Log Viewer button. The log viewer will open and display the last 40 entries.

If you wish to display other entries:

Click the Modify Search button.
Specify any constraints on the entries you want to see.
Click the Search button at the bottom of the log viewer.

Using a Debugger

The Application Server supports the Java Platform Debugger Architecture (JPDA). With JPDA, you can configure the Application Server to communicate debugging information using a socket.

To debug an application using a debugger:

Enable debugging in the Application Server using the Admin Console:
1. Select the Application Server node.
2. Select the JVM Settings tab. The default debug options are set to:
  -Xdebug -Xrunjdwp:transport=dt_socket,server=y, suspend=n,address=9009
  As you can see, the default debugger socket port is 9009. You can change it to a port not in use by the Application Server or another service.
3. Check the Enabled box of the Debug field.
4. Click the Save button.
Stop the Application Server and then restart it.