This chapter tells you everything you need to know to install, build, and run the examples. The following topics are addressed here:
The following software is required to run the examples:
To build, deploy, and run the examples, you need a copy of the Java Platform, Standard Edition 6.0 Development Kit (JDK 6). You can download the JDK 6 software from http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Download the current JDK update that does not include any other software, such as NetBeans IDE or the Java EE SDK.
GlassFish Server Open Source Edition 3.0.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 GlassFish Server and, optionally, NetBeans IDE. To obtain the GlassFish Server, you must install the Java EE 6 Software Development Kit (SDK), which you can download from http://www.oracle.com/technetwork/java/javaee/downloads/index.html. Make sure you download the Java EE 6 SDK, not the Java EE 6 Web Profile SDK.
During the installation of the SDK, do the following.
Configure the GlassFish Server administration user name as admin, and specify no password. This is the default setting.
Accept the default port values for the Admin Port (4848) and the HTTP Port (8080).
Allow the installer to download and configure the Update Tool. If you access the Internet through a firewall, provide the proxy host and port.
This tutorial refers to as-install-parent, the directory where you install the GlassFish Server. For example, the default installation directory on Microsoft Windows is C:\glassfishv3, so as-install-parent is C:\glassfishv3. The GlassFish 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 GlassFish 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
The tutorial example source is contained in the tutorial component. To obtain the tutorial component, use the Update Tool.
If you are behind a firewall that prevents you from using the Update Tool to obtain components, you can obtain the tutorial from the java.net web site.
Start the Update Tool.
Expand the GlassFish Server Open Source Edition node.
Select the Available Add-ons node.
From the list, select the Java EE 6 Tutorial check box.
Click Install.
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.
Updates to the Java EE 6 Tutorial are published periodically. For details on obtaining these updates, see Getting the Latest Updates to the Tutorial.
Follow these steps exactly. If you place the tutorial in the wrong location, the examples will not work.
Open the following URL in a web browser:
Click the Documents & Files link in the left sidebar.
In the table on the Documents & Files page, locate the latest stable version of the Java EE 6 Tutorial zip file.
Right-click the zip file name and save it to your system.
Copy or move the zip file into the GlassFish SDK directory.
By default, this directory is named glassfishv3.
Unzip the zip file.
The tutorial unzips into the directory glassfish/docs/javaee-tutorial.
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.
When you install NetBeans IDE, do not install the version of GlassFish Server that comes with NetBeans IDE. To skip the installation of GlassFish Server, follow these steps.
Click Customize on the first page of the NetBeans IDE Installer wizard.
In the Customize Installation dialog, deselect the check box for GlassFish Server and click OK.
Continue with the installation of NetBeans IDE.
To run the tutorial examples in NetBeans IDE, you must add your GlassFish Server as a server in NetBeans IDE. Follow these instructions to add the GlassFish Server to NetBeans IDE.
Select Tools -> Servers to open the Servers dialog.
Click Add Server.
Under Choose Server, select GlassFish v3 and click Next.
Under Server Location, browse the location of your GlassFish Server installation and click Next.
Under Domain Location, select Register Local Domain.
Click Finish.
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 GlassFish Server.
Start the Update Tool.
Expand the GlassFish Server Open Source Edition node.
Select the Available Add-ons node.
From the list, select the Apache Ant Build Tool check box.
Click Install.
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.
To use the ant command, add as-install/ant/bin to your PATH environment variable.
To start the GlassFish 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 GlassFish Server instances managed by one administration server. Associated with a domain are the following:
The GlassFish 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 GlassFish 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. The output also goes into the server log, which is located in domain-dir/logs/server.log.
Or, on Windows, choose 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 GlassFish Server, open a terminal window or command prompt and execute:
asadmin stop-domain domain1 |
Or, on Windows, choose Start -> All Programs -> Java EE 6 SDK -> Stop Application Server.
When the server has stopped, you will see the following output:
Domain domain1 stopped. |
To administer the GlassFish Server and manage users, resources, and Java EE applications, use the Administration Console tool. The GlassFish 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 Start -> All Programs -> Java EE 6 SDK -> Administration Console.
Click the Services tab.
Expand the Servers node.
Right-click the GlassFish Server instance and select View Admin Console.
NetBeans IDE uses your default web browser to open the Administration Console.
The GlassFish Server includes the Java DB database server.
To start the Java DB 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 included with the GlassFish Server, see http://www.oracle.com/technetwork/java/javadb/overview/index.html.
To stop the database using NetBeans IDE, right-click Java DB and choose Stop Server.
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.
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: web pages, style sheets, tag files, and images (web applications only)
web/WEB-INF: configuration files for web applications (web applications only)
nbproject: NetBeans project files
Examples that have multiple application modules packaged into an EAR file 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.
Check for any updates to the tutorial by using the Update Center included with the Java EE 6 SDK.
Open the Services tab in NetBeans IDE and expand Servers.
Right-click the GlassFish v3 instance and select View Update Center to display the Update Tool.
Select Available Updates in the tree to display a list of updated packages.
Look for updates to the Java EE 6 Tutorial (javaee-tutorial) package.
If there is an updated version of the Tutorial, select Java EE 6 Tutorial (javaee-tutorial) and click Install.
This section explains how to determine what is causing an error in your application deployment or execution.
One way to debug applications is to look at the server log in domain-dir/logs/server.log. The log contains output from the GlassFish 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://download.oracle.com/javase/6/docs/technotes/guides/logging/index.html) and from web components with the ServletContext.log method.
If you start the GlassFish 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 GlassFish Server in the background, debugging information is available only in the log. You can view the server log with a text editor or with the Administration Console log viewer.
Select the GlassFish Server node.
Click the View Log Files button.
The log viewer opens and displays the last 40 entries.
To display other entries, follow these steps.
The GlassFish Server supports the Java Platform Debugger Architecture (JPDA). With JPDA, you can configure the GlassFish Server to communicate debugging information using a socket.
Enable debugging in the GlassFish Server using the Administration Console:
Expand the Configuration node.
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 GlassFish Server or another service.
Select the Debug Enabled check box.
Click the Save button.
Stop the GlassFish Server and then restart it.