Eclipse GlassFish Embedded Server Guide, Release 7

The Eclipse GlassFish documentation set describes deployment planning and system installation. For an introduction to Eclipse GlassFish, refer to the books in the order in which they are listed in the following table.

The following tutorials explain how to develop Jakarta EE applications:

Javadoc tool reference documentation for packages that are provided with Eclipse GlassFish is available as follows.

For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see the NetBeans Documentation, Training & Support page.

For information about the Derby database for use with the Eclipse GlassFish, see the Derby page.

The Jakarta EE Samples project is a collection of sample applications that demonstrate a broad range of Jakarta EE technologies. The Jakarta EE Samples are bundled with the Jakarta EE Software Development Kit (SDK) and are also available from the repository (https://github.com/eclipse-ee4j/glassfish-samples).

The following table describes the typographic changes that are used in this book.

The following table explains symbols that might be used in this book.

The following table describes the default paths and file names that are used in this book.

The installation root directory, represented as as-install, is the parent of the directory that embedded Eclipse GlassFish uses for configuration files. This directory corresponds to the base directory for an installation of Eclipse GlassFish. Configuration files are contained in the following directories in the base directory for an installation of Eclipse GlassFish:

Specify the installation root directory only if you have a valid nonembedded Eclipse GlassFish installation and are using glassfish-embedded-static-shell.jar.

The instance root directory, also known as the domain directory, represented as domain-dir, is the parent directory of a server instance directory. Embedded Eclipse GlassFish uses the server instance directory for domain configuration files.

If domain-dir is not specified, Eclipse GlassFish creates a directory named gfembedrandom-numbertmp in a temporary directory, where random-number is a randomly generated 19-digit number. Eclipse GlassFish then copies configuration files into this directory. The temporary directory is the value of the system property java.io.tmpdir. You can override this value by specifying the glassfish.embedded.tmpdir property in the GlassFishProperties class or as a system property.

Using an existing domain.xml file avoids the need to configure embedded Eclipse GlassFish programmatically in your application. Your application obtains domain configuration data from an existing domain.xml file. You can create this file by using the administrative interfaces of an installation of nonembedded Eclipse GlassFish. To specify an existing domain.xml file, invoke the setConfigFileURI method of the GlassFishProperties class as described in Creating and Configuring an Embedded Eclipse GlassFish.

--properties=FILE

Load properties from a file. This option can be repeated to load properties from multiple files. The propertes in the file can be any of the following: - Any properties supported by Embedded $Eclipse GlassFish. - Any command line options with the name of the option as the key, without the initial hyphens, and the value of the option as the value. - Keys that start with the "command." prefix, followed by any text. The value will be treated as a command to execute at startup. - Keys that start with the "deploy." prefix, followed by any text. The value will be treated as an application to deploy at startup, as if it was specified on the command line. For example, the $Eclipse GlassFish domain directory can be specified with the usual Embedded $Eclipse GlassFish property "glassfish.embedded.tmpdir=myDomainDir", as well as with the property "domainDir=myDomainDir" that represents the "--domainDir=myDomainDir" command-line option. A command to deploy an application can be specified via a property key "command.deploy.app=deploy --contextroot=app myapp.war". An application to deploy at startup with the default deploy behavior can be specified via a property key "deploy.app=myapp.war". The property "properties" can also be defined in this file, pointing to another file. In that case, properties will be loaded also from that file.

-p=PORT, --httpPort=PORT, --port=PORT

Bind the HTTP listener to the specified port. If not set, the HTTP listener binds to port 8080 by default, unless it’s disabled by the --noListener argument.

--httpsPort=PORT_NUMBER

Bind the HTTPS listener to the specified port. If not set, the HTTPS listener is disabled by default.

--domainConfigFile=FILE

Set the location of domain configuration file (i.e., domain.xml) using which Embedded Eclipse GlassFish should run.

--domainDir=DIRECTORY, --instanceRoot=DIRECTORY

Set the instance root (a.k.a. domain dir) using which Embedded Eclipse GlassFish should run.

--noListener, `--noPort

Disable the HTTP listener, which is by default enabled and bound to port 8080.

--autoDeployDir=DIRECTORY

Files and directories in this directory will be deployed as applications (in random order), as if they were specified on the command line.

--logLevel=LEVEL

Set the log level of all loggers to LEVEL

--logProperties=FILE

Set logging properties from file FILE

--noInfo

Disable printing information about deployed applications after startup

--shut-down, --shutdown, --stop

Shut down GlassFish and the whole JVM process after server is started and initialized. This is useful to start the server, perform some action during startup (e.g. during application dpeloyment), and shot down the application cleanly. Also useful for Class Data Sharing and similar startup optimizations - to start the server, get it to a ready state (applications deployed, etc.), and then shut down cleanly, so that the JVM can store the cached data.

--help

Print help information

Any argument that doesn’t start with a hyphen (-), is treated as follows:

To enable your applications to locate the class libraries for embedded Eclipse GlassFish, add a JAR file corresponding to one of the Embedded Eclipse GlassFish editions to your class path.

In addition, add to the class path any other JAR files or classes upon which your applications depend. For example, if an application uses a database other than Java DB, include the Java DataBase Connectivity (JDBC) driver JAR files in the class path.

Before you can run applications, you must set up and run the embedded Eclipse GlassFish.

The following topics are addressed here:

Deploying an application installs the files that comprise the application into Embedded Eclipse GlassFish and makes the application ready to run. By default, an application is enabled when it is deployed.

The following topics are addressed here:

For general information about deploying applications in Eclipse GlassFish, see the Eclipse GlassFish Application Deployment Guide.

Running asadmin commands from an application enables the application to configure the embedded Eclipse GlassFish to suit the application’s requirements. For example, an application can run the required asadmin commands to create a JDBC technology connection to a database.

For more information about configuring embedded Eclipse GlassFish, see the Eclipse GlassFish Administration Guide. For detailed information about asadmin commands, see Section 1 of the Eclipse GlassFish Reference Manual.

The org.glassfish.embeddable package contains classes that you can use to run asadmin commands. Use the following code examples as templates and change the command name, parameter names, and parameter values as needed.

Example 1-10 Running an asadmin create-jdbc-resource Command

This example shows code for running an asadmin create-jdbc-resource command. Code for creating and starting the server is not shown in this example. For an example of code for creating and starting the server, see Example 1-4.

Example 1-11 Running an asadmin set-log-level Command

This example shows code for running an asadmin set-log-level command. Code for creating and starting the server is not shown in this example. For an example of code for creating and starting the server, see Example 1-4.

For another way to change log levels, see Changing Log Levels in Embedded Eclipse GlassFish.

Example 1-12 Using an Existing domain.xml File and Deploying an Application From an Archive File

This example shows code for the following:

Setting up your Maven environment enables Maven to download the required embedded Eclipse GlassFish distribution file when you build your project. Setting up your Maven environment also identifies the plug-in that enables you to build and start an unpackaged application with a single Maven goal.

Before You Begin

Ensure that Apache Maven (http://maven.apache.org/) is installed.

Example 1-13 POM File for Configuring Maven to Use Embedded Eclipse GlassFish

This example shows a POM file for configuring Maven to use embedded Eclipse GlassFish.

If you are using Maven to manage the development of your application, you can use a Maven goal to build and start the application in embedded Eclipse GlassFish.

Before You Begin

Ensure that your Maven environment is configured, as described in To Set Up Your Maven Environment.

An application that was built and started from Maven continues to run in Embedded Eclipse GlassFish until Embedded Eclipse GlassFish is stopped. While the application is running, you can test changes to the application by redeploying it.

To redeploy, in the window from where the application was built and started from Maven, press Enter.

You can use the following Maven goals to test your applications with embedded Eclipse GlassFish:

Properties that can be passed to the EJBContainer#createEJBContainer(Properties) method are summarized in the following table. All properties are in the org.glassfish.ejb.embedded.glassfish package. For example, the full name of the installation.root property is org.glassfish.ejb.embedded.glassfish.installation.root.

Table 1-11 EJB 3.1 Embeddable API Properties

When using Maven with the EJB 3.1 Embeddable API and Embedded Eclipse GlassFish, you cannot use the features of the Maven plug-in. You must start and stop Embedded Eclipse GlassFish manually or programmatically outside of Maven.

Example 1-14 Maven POM File for Using the EJB 3.1 Embeddable API with Embedded Eclipse GlassFish

This example shows a POM file for configuring Maven to use the EJB 3.1 Embeddable API with Embedded Eclipse GlassFish.

If you are using glassfish-embedded-static-shell.jar, you can omit the dependency element with the javaee-api artifactId and the pluginRepositories element.

Set the S1AS_HOME environment variable to the installation root directory before running the mvn clean verify command.