Using the Tutorial Examples

This chapter tells you everything you need to know to install, build, and run the tutorial examples.

For additional samples, see the GlassFish samples at https://github.com/eclipse-ee4j/glassfish-samples/tree/master/ws/jakartaee9

Required Software

The following software is required to run the examples:

Java Platform, Standard Edition

To build, deploy, and run the examples, you need a copy of the Java Platform, Standard Edition Development Kit (JDK). You must use JDK 8 Update 20 or above. You can download JDK software from https://www.oracle.com/technetwork/java/javase/downloads/index.html.

Eclipse Glassfish Server

GlassFish Server 6.0 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run the examples, you need a copy of GlassFish Server and, optionally, NetBeans IDE. You can download GlassFish Server from https://glassfish.org/download.

GlassFish Server Installation Tips

GlassFish Server is installed from a ZIP file. It sets the default administration user name as admin with no required password. The Admin Port is set to 4848, and the HTTP Port is set to 8080.

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

After you install 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

Jakarta EE Tutorial Examples

The tutorial example codes are located at https://github.com/eclipse-ee4j/jakartaee-examples

Clone or download this repository to your preferred location, this path is referenced in the tutorial as the jakartaee-examples directory.

Apache 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 Jakarta 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 https://netbeans.apache.org/download/index.html.

To Add GlassFish Server as a Server Using 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 GlassFish Server to NetBeans IDE.

  1. From the Tools menu, choose Servers.

  2. In the Servers wizard, click Add Server.

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

  4. Under Server Location, browse to the GlassFish Server installation and click Next.

  5. Under Domain Location, select Register Local Domain.

  6. Click Finish.

Apache Maven

Maven is a Java technology-based build tool developed by the Apache Software Foundation and is used to build, package, and deploy the tutorial examples. To run the tutorial examples from the command line, you need Maven 3.0 or higher. If you do not already have Maven, you can install it from:

https://maven.apache.org

Be sure to add the maven-install/bin directory to your path.

If you are using NetBeans IDE to build and run the examples, it includes a copy of Maven.

Starting and Stopping GlassFish Server

You can start and stop GlassFish Server using either NetBeans IDE or the command line.

To Start GlassFish Server Using NetBeans IDE

  1. Click the Services tab.

  2. Expand Servers.

  3. Right-click the GlassFish Server instance and select Start.

To Stop GlassFish Server Using NetBeans IDE

To stop GlassFish Server using NetBeans IDE, right-click the GlassFish Server instance and select Stop.

To Start GlassFish Server Using the Command Line

To start GlassFish Server from the command line, 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. The following elements are associated with a domain:

  • The GlassFish Server port number: The default is 8080.

  • The administration server’s port number: The default is 4848.

  • An administration user name and password: The default user name is admin, and by default no password is required.

You specify these values when you install GlassFish Server. The examples in this tutorial assume that you chose the default ports as well as the default user name and lack of password.

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.

To Stop GlassFish Server Using the Command Line

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

asadmin stop-domain domain1

Starting the Administration Console

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

To Start the Administration Console Using NetBeans IDE

  1. Click the Services tab.

  2. Expand Servers.

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

NetBeans IDE uses your default web browser to open the Administration Console.

Starting and Stopping Apache Derby

GlassFish Server includes Apache Derby.

To Start Derby Using Command Line

To start Derby from the command line, open a terminal window or command prompt, change to the as-install/bin directory, and execute:

asadmin start-database

To Stop Derby Using Command Line

To stop Derby from the command line, open a terminal window or command prompt, change to the as-install/bin directory, and execute:

asadmin stop-database

For information about Apache Derby included with GlassFish Server, see the Release Notes that are located in the as-install/javadb/ directory.

To Start Derby Using NetBeans IDE

When you start GlassFish Server using NetBeans IDE, the database server starts automatically. If you ever need to start the server manually, however, follow these steps.

  1. Click the Services tab.

  2. Expand Databases.

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

To Stop Derby Using NetBeans IDE

To stop the database using NetBeans IDE, right-click Java DB and select Stop Server.

Building the Examples

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

Tutorial Example Directory Structure

To facilitate iterative development and keep application source files separate from compiled files, the tutorial examples use the Maven application directory structure.

Each application module has the following structure:

  • pom.xml: Maven build file

  • src/main/java: Java source files for the module

  • src/main/resources: configuration files for the module, with the exception of web applications

  • src/main/webapp: web pages, style sheets, tag files, and images (web applications only)

  • src/main/webapp/WEB-INF: configuration files for web applications (web applications only)

When an example has multiple application modules packaged into an EAR file, its submodule directories use the following naming conventions:

  • example-name-app-client: application clients

  • example-name-ejb: enterprise bean JAR files

  • example-name-war: web applications

  • example-name-ear: enterprise applications

  • example-name-common: library JAR containing components, classes, and files used by other modules

The Maven build files (pom.xml) distributed with the examples contain goals to compile and assemble the application into the target directory and deploy the archive to GlassFish Server.

Jakarta EE Maven Archetypes in the Tutorial

Some of the chapters have instructions on how to build an example application using Maven archetypes. Archetypes are templates for generating a particular Maven project. The Tutorial includes several Maven archetypes for generating Jakarta EE projects.

Installing the Tutorial Archetypes

You must install the included Maven archetypes into your local Maven repository before you can create new projects based on the archetypes. You can install the archetypes using NetBeans IDE or Maven.

Installing the Tutorial Archetypes Using NetBeans IDE

  1. From the File menu, choose Open Project.

  2. In the Open Project dialog box, navigate to:

jakartaee-examples/tutorial

  1. Select the archetypes folder.

  2. Click Open Project.

  3. In the Projects tab, right-click the archetypes project and select Build.

Installing the Tutorial Archetypes Using Maven

  1. In a terminal window, go to:

jakartaee-examples/tutorial/archetypes/

  1. Enter the following command:

mvn install

Debugging Jakarta EE Applications

This section explains 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 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 https://docs.oracle.com/javase/8/docs/technotes/guides/logging/index.html) and from web components with the ServletContext.log method.

If you use NetBeans IDE, logging output appears in the Output window as well as the server log.

If you start 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 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.

To Use the Administration Console Log Viewer

  1. Select the GlassFish Server node.

  2. Click View Log Files.
    The log viewer opens and displays the last 40 entries.

  3. To display other entries, follow these steps:

    1. Click Modify Search.

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

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

Using a Debugger

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

To Debug an Application Using a Debugger

  1. Follow these steps to enable debugging in GlassFish Server using the Administration Console:

    1. Expand the Configurations node, then expand the server-config node.

    2. Select the JVM Settings node. The default debug options are set to:

      -agentlib:jdwp=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 GlassFish Server or another service.

    3. Select the Debug Enabled check box.

    4. Click Save.

  2. Stop GlassFish Server and then restart it.