test

The Java EE 6 Tutorial, Volume I

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.

JavaTM Platform, Standard Edition

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

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

Java EE 6 Software Development Kit (SDK)

Sun GlassFishTM Enterprise Server v3 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 Enterprise Server and, optionally, NetBeans IDE. To obtain the Enterprise Server, you must install the Java EE 6 Software Development Kit (SDK), which you can download from http://java.sun.com/javaee/downloads/. Make sure you download the Java EE 6 SDK, not the Java EE 6 Web Profile SDK.

SDK Installation Tips

During the installation of the SDK:

This tutorial refers to the directory where you install the Enterprise Server as as-install-parent. For example, the default installation directory on Microsoft Windows is C:\glassfishv3, so as-install-parent is C:\glassfishv3. The Enterprise Server itself is installed in as-install, the glassfish directory under as-install-parent. So on Microsoft Windows, as-install is C:\glassfishv3\glassfish.

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

as-install-parent/bin
as-install/bin

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. To run the tutorial examples, you need Ant 1.7.1. If you do not already have Ant 1.7.1, you can install it from the Update Tool that is part of the Enterprise Server.

ProcedureTo Obtain Apache Ant

  1. Start the Update Tool.

    • From the command line, type the command updatetool.

    • On a Windows system, select the following:

      Start -> All Programs -> Java EE 6 SDK -> Start Update Tool

  2. Expand the GlassFish v3 node.

  3. Select the Available Add-ons node.

  4. From the list, select the Apache Ant Build Tool checkbox.

  5. Click Install.

  6. Accept the license agreement.

    After installation, Apache Ant appears in the list of installed components. The tool is installed in the as-install-parent/ant directory.

Next Steps

To use the ant command, add as-install/ant/bin to your PATH environment variable.

Java EE 6 Tutorial Component

The tutorial example source is contained in the tutorial component. To obtain the tutorial component, use the Update Tool.

ProcedureTo Obtain the Tutorial Component

  1. Start the Update Tool.

    • From the command line, type the command updatetool.

    • On a Windows system, select the following:

      Start -> All Programs -> Java EE 6 SDK -> Start Update Tool

  2. Expand the GlassFish v3 node.

  3. Select the Available Add-ons node.

  4. From the list, select the Java EE 6 Tutorial checkbox.

  5. Click Install.

  6. Accept the license agreement.

    After installation, the Java EE 6 Tutorial appears in the list of installed components. The tool is installed in the as-install/docs/javaee-tutorial directory. This directory contains two subdirectories, docs and examples. The examples directory contains subdirectories for each of the technologies discussed in the tutorial.

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 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans IDE.

To run the tutorial examples, you need the latest version of NetBeans IDE. You can download NetBeans IDE from http://www.netbeans.org/downloads/index.html.

ProcedureTo Add Enterprise Server as a Server in NetBeans IDE

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

  1. Select Tools -> Servers to open the Servers dialog.

  2. Click Add Server.

  3. Under Server, select GlassFish v3 and click Next.

  4. Under Server Location, enter the location of your Enterprise Server installation and click Next.

  5. Select Register Local Default Domain.

  6. Click Finish.

Starting and Stopping the Enterprise Server

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


asadmin start-domain --verbose

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

You specify these values when you install the Enterprise 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, choose the following:

Start -> All Programs -> Java EE 6 SDK -> Start Application Server

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


Domain domain1 started.

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


asadmin stop-domain domain1

Or, on Windows, choose the following:

Start -> All Programs -> Java EE 6 SDK -> Stop Application Server

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


Domain domain1 stopped.

Starting the Administration Console

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

Or, on Windows, choose the following:

Start -> All Programs -> Java EE 6 SDK -> Administration Console

ProcedureTo Start the Administration Console in NetBeans IDE

  1. Click the Services tab.

  2. Expand the Servers node.

  3. Right-click the Enterprise Server instance and select View Admin Console

    Note –

    You must configure a web browser with NetBeans IDE in order for the Administration Console to be started from within NetBeans IDE.

Starting and Stopping the Java DB Database Server

The Enterprise 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

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


asadmin stop-database

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

    To start the database server using NetBeans IDE, follow these steps:

  1. Click the Services tab.

  2. Expand the Databases node.

  3. Right-click Java DB and choose Start Server.

To stop the database using NetBeans IDE, choose Stop Server.

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.

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.

Getting the Latest Updates to the Tutorial

Check for any updates to the tutorial by using the Update Center included with the Java EE 6 SDK.

ProcedureTo Update the Tutorial through the Update Center

  1. Open the Services tab in NetBeans IDE and expand Servers.

  2. Right-click the GlassFish v3 instance and select View Update Center to display the Update Tool.

  3. Select Available Updates in the tree to display a list of updated packages.

  4. Look for updates to the Java EE 6 Tutorial (javaee-tutorial) package.

  5. If there is an updated version of the Tutorial , select Java EE 6 Tutorial (javaee-tutorial) and click Install.

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 Enterprise 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 Enterprise 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 Enterprise 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 Administration Console log viewer.

    To use the log viewer:

  1. Select the Enterprise Server node.

  2. Click the View Log Files button. The log viewer will open and display the last 40 entries.

    If you wish to display other entries:

  1. Click the Modify Search button.

  2. Specify any constraints on the entries you want to see.

  3. Click the Search button at the top of the log viewer.

Using a Debugger

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

    To debug an application using a debugger:

  1. Enable debugging in the Enterprise Server using the Administration Console:

    1. Expand the Configuration node.

    2. Select the JVM Settings node. 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 Enterprise Server or another service.

    3. Select the Debug Enabled check box.

    4. Click the Save button.

  2. Stop the Enterprise Server and then restart it.