test

Oracle GlassFish Server 3.0.1 Embedded Server Guide

Oracle GlassFishTM Server 3.0.1 Embedded Server Guide

This document explains how to use embedded Oracle GlassFish Server to run applications in embedded GlassFish Server and to develop applications in which GlassFish Server is embedded. This document is for software developers who are developing applications to run in embedded GlassFish Server. The ability to program in the Java TM language is assumed.

This document addresses the following topics:

Introduction to Embedded GlassFish Server

Embedded Oracle GlassFish Server enables you to use GlassFish Server as a library. Embedded GlassFish Server also enables you to run GlassFish Server inside any Virtual Machine for the JavaTM platform (Java Virtual Machine or JVMTMmachine).

No installation or configuration of embedded GlassFish Server is required. The ability to run GlassFish Server inside applications without installation or configuration simplifies the process of bundling GlassFish Server with applications.

Note –

Embedded GlassFish Server does not run on the Java Platform, Micro Edition (Java ME platform).

You can use embedded GlassFish Server in the following ways:

Embedded GlassFish Server provides a plug-in for Apache Maven. This plug-in simplifies the testing of applications by enabling you to build an application and run it with GlassFish Server on a single system. Testing and debugging are simplified because the need for an installed and configured GlassFish Server is eliminated. Therefore, you can run unit tests automatically in every build.

Note –

Using Embedded GlassFish Server does not involve any use of OSGi technology.

Including the GlassFish Server Embedded Server API in Applications

Oracle GlassFish Server provides an application programming interface (API) for developing applications in which GlassFish Server is embedded. For details, see the org.glassfish.api.embedded.* packages at https://glassfish.dev.java.net/nonav/docs/v3/api/.

Developing an application in which GlassFish Server is embedded is explained in the following topics:

Setting the Class Path

To enable your applications to locate the class libraries for embedded GlassFish Server, add one of the following JAR files to your class path:

glassfish-embedded-web.jar

Contains classes needed for deploying Java EE web applications. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/.

glassfish-embedded-all.jar

Contains classes needed for deploying all Java EE application types. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/.

glassfish-embedded-static-shell.jar

Contains references to classes needed for deploying all Java EE application types. Must be used with a nonembedded installation of GlassFish Server. Obtain this file from the as-install/glassfish/lib/embedded directory of a nonembedded GlassFish Server installation. For an explanation of as-install, see Installation Root Directory.

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 (JDBCTM) driver JAR files in the class path.

Creating, Starting, and Stopping Embedded GlassFish Server

Before you can run applications, you must set up and run the embedded GlassFish Server. This section includes the following topics:

Creating and Configuring an Embedded GlassFish Server

To create and configure an embedded GlassFish Server, perform these tasks:

  1. Instantiate the org.glassfish.api.embedded.Server.Builder class.

  2. Invoke any methods for configuration settings that you require. This is optional.

  3. Invoke one of the build methods to create a Server object.

The methods of this class for setting the server configuration are listed in the following table. The default value of each configuration setting is also listed.

Table 1 Constructor and Methods of the Server.Builder Class

Purpose 

Method 

Default Value 

Creates a server builder and names the server 

 

Server.Builder(java.lang.String id)

None 

References an embedded file system 

 

embeddedFileSystem(EmbeddedFileSystem file-system)

None 

Enables verbose mode 

 

verbose(boolean enabled)

true

Enables logging 

 

logger(boolean enabled)

true

Specifies a log file 

 

logFile(File log-file)

domain-dir/logs/server.log (see Instance Root Directory)

Creates a server 

 

build()

None 

Creates a server with properties 

 

build(Properties properties)

None 

Example 1 Creating an Embedded GlassFish Server

This example shows code for creating a server and enabling logging.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    builder.logger(true);
    ...
    Server server = builder.build();
...

Specifying an Embedded GlassFish Server File System

Specifying an embedded file system for an embedded GlassFish Server is optional. What you don't specify is created automatically and used transparently by the server. An embedded file system enables you to do the following:

To specify an embedded file system for embedded GlassFish Server, perform these tasks:

  1. Instantiate the org.glassfish.api.embedded.EmbeddedFileSystem.Builder class.

  2. Invoke any methods for configuration settings that you require. This is optional.

  3. Invoke the build method to create an EmbeddedFileSystem object.

If you are including the glassfish-embedded-static-shell.jar file in your class path, the methods of the EmbeddedFileSystem.Builder class can only point to the referenced installation. These methods cannot create or delete any directories or files.

The methods of the EmbeddedFileSystem.Builder class for setting the embedded file system configuration are listed in the following table. The default value of each configuration setting is also listed.

Table 2 Constructor and Methods of the EmbeddedFileSystem.Builder Class

Purpose 

Method 

Default Value 

Creates an embedded file system builder 

 

EmbeddedFileSystem.Builder()

None 

Deletes embedded file system files when the server is stopped 

Caution – Caution –

Do not set autoDelete to true if you are using installRoot to refer to a preexisting GlassFish Server installation.

 

autoDelete(boolean enabled)

false

Creates a new or references an existing Installation Root Directory 


installRoot(java.io.File install-root)

In order of precedence: 

  • glassfish.embedded.tmpdir system property value

  • user.dir system property value

  • Current directory

Creates or references an Installation Root Directory in which the embedded server and file system use different class loaders if cooked-mode is false

 

installRoot(java.io.File install-root, 
boolean cooked-mode)

Same as the other installRoot method, cooked-mode is true

Creates a new or references an existing Instance Root Directory 


instanceRoot(java.io.File instance-root)

as-install/domains/domain1

Creates a new or references an existing configuration file 

 

configurationFile(java.io.File config-file)

domain-dir/config/domain.xml

Creates or references a configuration file that is read-only if read-only is true

 

configurationFile(java.io.File config-file 
boolean read-only)

domain-dir/config/domain.xml, read-only is false

Creates an embedded file system 

 

build()

None 

Example 2 Creating an Embedded File System

This example shows code for creating an embedded file system whose configuration information is stored in the file C:\samples\test\applicationserver\domains\domain1\config\domain.xml. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import java.io.File;
...
import org.glassfish.api.embedded.*;
...
    File installDir = new File("c:\\samples\\testapp\\applicationserver");
    File domainDir = new File(installDir, "domains\\domain1");
        ...
    File domainConfig = new File(domainDir, "config");
    File domainXml = new File(domainConfig, "domain.xml");
    ...
    Server.Builder builder = new Server.Builder("test");
    ...
    EmbeddedFileSystem.Builder efsb = new EmbeddedFileSystem.Builder();
    efsb.installRoot(installDir);
    efsb.instanceRoot(domainDir);
    efsb.configurationFile(domainXml);
    EmbeddedFileSystem efs = efsb.build();
    builder.embeddedFileSystem(efs);
    ...
    Server server = builder.build();
...

Installation Root Directory

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

Specify the installation root directory if any of the following conditions applies:

Note –

If the instance root directory is also specified, configuration files for the domain are obtained from the instance root directory, not the domains directory under the installation root directory.

How embedded Oracle GlassFish Server uses the installation root directory depends on the content of this directory:

If the installation root directory is not specified, embedded Oracle GlassFish Server creates a directory named gfembedrandom-numbertmp in the current working directory, where random-number is a randomly generated 19-digit number. Embedded Oracle GlassFish Server then copies configuration files into this directory.

Instance Root Directory

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

Specify the instance root directory if any of the following conditions applies:

How embedded Oracle GlassFish Server uses the instance root directory depends on the content of this directory:

If the instance root directory is not specified, embedded Oracle GlassFish Server uses the domains subdirectory of the installation root directory for domain configuration files.

Using an Existing domain.xml File

Using an existing domain.xml file avoids the need to configure embedded GlassFish Server 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 GlassFish Server. To specify an existing domain.xml file, invoke the installRoot, instanceRoot, or configurationFile method of the EmbeddedFileSystem.Builder class or a combination of these methods.

Running an Embedded GlassFish Server

After you create an embedded GlassFish Server as described in Creating and Configuring an Embedded GlassFish Server, you can perform operations such as:

Setting the Port of an Embedded GlassFish Server From an Application

You must set the server's HTTP port. If you do not set the port, your application fails to start and throws an exception. You can set the port directly or indirectly.

Example 3 Starting an Embedded GlassFish Server

This example shows code for setting the port of an embedded GlassFish Server. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    ...
    Server server = builder.build();
    server.createPort(8080);
...

Starting an Embedded GlassFish Server From an Application

To start an embedded GlassFish Server, invoke the start method of the Server object.

Example 4 Starting an Embedded GlassFish Server

This example shows code for setting the port and starting an embedded GlassFish Server. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    ...
    Server server = builder.build();
    server.createPort(8080);
    server.start();
...

Stopping an Embedded GlassFish Server From an Application

The API for embedded GlassFish Server provides a method for stopping an embedded server. Using this method enables your application to stop the server in an orderly fashion by performing any necessary cleanup steps before stopping the server, for example:

To stop an embedded GlassFish Server, invoke the stop method of an existing Server object.

Example 5 Stopping an Embedded GlassFish Server

This example shows code for prompting the user to press the Enter key to stop an embedded GlassFish Server. When a user presses Enter, the application undeploys any deployed applications before stopping the server. For more information about undeploying applications, see Undeploying an Application. Code for creating a Server object is not shown in this example. For an example of code for creating a Server object, see Example 1.

...
import java.io.BufferedReader;
...
import org.glassfish.api.embedded.*;
...
    EmbeddedDeployer deployer = server.getDeployer();
    ...
    System.out.println("Press Enter to stop server");
        // wait for Enter
    new BufferedReader(new java.io.InputStreamReader(System.in)).readLine();
    deployer.undeployAll();
    server.stop();
...

Deploying and Undeploying an Application in an Embedded GlassFish Server

Deploying an application installs the files that comprise the application into Embedded GlassFish Server and makes the application ready to run. By default, an application is enabled when it is deployed. You can perform operations such as:

For general information about deploying applications in GlassFish Server, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

ProcedureTo Deploy an Application From an Archive File or a Directory

An archive file contains the resources, deployment descriptor, and classes of an application. The content of the file must be organized in the directory structure that the Java EE specifications define for the type of archive that the file contains. For more information, see Chapter 2, Deploying Applications, in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Deploying an application from a directory enables you to deploy an application without the need to package the application in an archive file. The contents of the directory must match the contents of the expanded Java EE archive file as laid out by the GlassFish Server. The directory must be accessible to the machine on which the deploying application runs. For more information about the requirements for deploying an application from a directory, see To Deploy an Application or Module in a Directory Format in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

  1. Invoke the addContainer method of the Server object to get an instance of the org.glassfish.api.embedded.ContainerBuilder class.

    Instantiate ContainerBuilder.Type.web, ContainerBuilder.Type.ejb, or ContainerBuilder.Type.all.

  2. Instantiate the java.io.File class to represent the archive file or directory.

  3. Invoke the getDeployer method of the Server object to get an instance of the org.glassfish.api.embedded.EmbeddedDeployer class.

  4. Instantiate a org.glassfish.api.deployment.DeployCommandParameters class.

    To use the default parameter settings, instantiate an empty DeployCommandParameters class. For information about the fields in this class that you can set, see the descriptions of the equivalent deploy(1) command parameters.

  5. Invoke the deploy(File archive, DeployCommandParameters params) method of the instance of the EmbeddedDeployer object.

    Specify the java.io.File and DeployCommandParameters class instances you created previously as the method parameters.

Example 6 Deploying an Application From an Archive File

This example shows code for deploying an application from the archive file c:\samples\simple.war and setting the contextroot parameter of the DeployCommandParameters class. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import java.io.File;
...
import org.glassfish.api.deployment.*;
...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    ...
    Server server = builder.build();
    server.addContainer(ContainerBuilder.Type.web);
    server.createPort(8080);
    server.start();

    File war = new File("c:\\samples\\simple.war");
    EmbeddedDeployer deployer = server.getDeployer();
    DeployCommandParameters params = new DeployCommandParameters();
    params.contextroot = "simple";
    deployer.deploy(war, params);
...

Undeploying an Application

Undeploy an application when the application is no longer required to run in GlassFish Server. For example, before stopping GlassFish Server, undeploy all applications that are running in GlassFish Server.

Note –

If you reference a nonembedded GlassFish Server installation using the glassfish-embedded-static-shell.jar file and do not undeploy your applications in the same server life cycle in which you deployed them, expanded archives for these applications remain under the domain-dir/applications directory.

To undeploy an application, invoke the undeploy method of an existing EmbeddedDeployer object. In the method invocation, pass the name of the application and the name of its DeployCommandParameters class as parameters. Both are specified when the application is deployed.

To undeploy all deployed applications, invoke the undeployAll method of an existing EmbeddedDeployer object. This method takes no parameters.

Example 7 Undeploying an Application

This example shows code for undeploying the application that was deployed in Example 6.

...
import org.glassfish.api.deployment.*;
...
import org.glassfish.api.embedded.*;
...
    deployer.undeploy(war, params);
...

Running asadmin Commands Using the GlassFish Server Embedded Server API

Running asadmin(1M) commands from an application enables the application to configure the embedded GlassFish Server 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 GlassFish Server, see the Oracle GlassFish Server 3.0.1 Administration Guide. For detailed information about asadmin commands, see Section 1 of the Oracle GlassFish Server 3.0.1 Reference Manual.

Note –

Ensure that your application has started an embedded GlassFish Server before the application attempts to run asadmin commands. For more information, see Running an Embedded GlassFish Server.

The org.glassfish.api.admin 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 8 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 4.

...
import org.glassfish.api.embedded.*;
import org.glassfish.api.admin.*;
...
    String command = "create-jdbc-resource";
    ParameterMap params = new ParameterMap();
    params.add("connectionpoolid", "DerbyPool");
    params.add("jndi_name", "jdbc/DerbyPool");
    CommandRunner runner = server.getHabitat().getComponent(CommandRunner.class);
    ActionReport report = server.getHabitat().getComponent(ActionReport.class);
    runner.getCommandInvocation(command, report).parameters(params).execute();
...
Example 9 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 4.

...
import org.glassfish.api.embedded.*;
import org.glassfish.api.admin.*;
...
    String command = "set-log-level";
    ParameterMap params = new ParameterMap();
    params.add("javax\.enterprise\.system\.container\.web", "FINE");
    CommandRunner runner = server.getHabitat().getComponent(CommandRunner.class);
    ActionReport report = server.getHabitat().getComponent(ActionReport.class);
    runner.getCommandInvocation(command, report).parameters(params).execute();
...

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

Sample Applications

Example 10 Using an Existing domain.xml File and Deploying an Application From an Archive File

This example shows code for the following:

The files that this example uses are organized as follows:

import java.io.File;
import java.io.BufferedReader;
import org.glassfish.api.deployment.*;
import org.glassfish.api.embedded.*;

public class Main {
        
     /**
     * @param args the command line arguments
     */

    public static void main(String[] args) {
        File installDir = new File ("c:\\myapp\\embeddedserver");
        File war = new File("c:\\samples\\simple.war");
        try {
            Server.Builder builder = new Server.Builder("test");
            ...
            EmbeddedFileSystem.Builder efsb = new EmbeddedFileSystem.Builder();
            efsb.autoDelete(false);
            efsb.installRoot(installDir);
            EmbeddedFileSystem efs = efsb.build();
            builder.embeddedFileSystem(efs);
            ...
            Server server = builder.build();
            server.addContainer(ContainerBuilder.Type.web);
            server.createPort(8080);
            server.start();
            
            EmbeddedDeployer deployer = server.getDeployer();
            DeployCommandParameters params = new DeployCommandParameters();
            deployer.deploy(war, params);
        }
        catch (Exception e) {
            e.printStackTrace();
        }

        System.out.println("Press Enter to stop server");
        // wait for Enter
        new BufferedReader(new java.io.InputStreamReader(System.in)).readLine();
        try {
            deployer.undeployAll();
            server.stop();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}

ProcedureTo Run Embedded GlassFish Server from the Command Line

After you have written a class that uses the GlassFish ServerEmbedded Server API to start the server, deploy your applications, and stop the server, you can run this class at the command line.

Before You Begin

Ensure that the following prerequisites are met:

  1. Run embedded GlassFish Server in the Java application launcher, specifying the applications to deploy.


    java -jar glassfish-embedded-jar embedded-class
    glassfish-embedded-jar

    The full path to the file that contains your distribution of embedded GlassFish Server: glassfish-embedded-web.jar, glassfish-embedded-all.jar, or glassfish-embedded-static-shell.jar.

    embedded-class

    A user-created class file with a main method that uses the Embedded Server API to start the server, deploy your applications, and stop the server.

    The applications continue to run in embedded GlassFish Server until embedded GlassFish Server is stopped.

Example 11 Running Embedded GlassFish Server

This example shows the command for running embedded GlassFish Server as follows:


java -jar glassfish-embedded-all.jar myembed.class

Testing Applications with the Maven Plug-in for Embedded GlassFish Server

If you are using Apache Maven, the plug-in for embedded GlassFish Server simplifies the testing of applications. This plug-in enables you to build and start an unpackaged application with a single Maven goal.

Testing applications with the Maven plug-in involves the following tasks:

Predefined Maven goals for embedded GlassFish Server are described in Maven Goals for Embedded GlassFish Server.

To use Maven with Embedded GlassFish Server and the EJBTM 3.1 Embeddable API, see Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server.

ProcedureTo Set Up Your Maven Environment

Setting up your Maven environment enables Maven to download the required embedded GlassFish Server 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 is installed.

  1. Identify the Maven plug-in for embedded GlassFish Server.

    Add the following plugin element to your POM file:

    ...
        ...
        <plugins>
            ...
            <plugin>
                <groupId>org.glassfish</groupId>
                <version>version</version>
            </plugin>
            ...
        </plugins>
...
    version

    The version to use. The version of the final promoted build for this release is 3.0-74b.

  2. Configure the embedded-glassfish goal prefix, the application name, and other standard settings.

    Add the following configuration element to your POM file:

    ...
        <plugins>
            ...
            <plugin>
                ...
                <configuration>
                    <goalPrefix>embedded-glassfish</goalPrefix>
                    ...
                    <app>test.war</app>
                    <port>8080</port> 
                    <contextRoot>test</contextRoot> 
                    <autoDelete>true</autoDelete>
                    ...
                </configuration>
                ...
            </plugin>
            ...
        </plugins>
...

    In the app parameter, substitute the archive file or directory for your application. The optional port, contextRoot, and autoDelete parameters show example values. For details, see Maven Goals for Embedded GlassFish Server.

  3. Configure Maven goals.

    Add execution elements to your POM file:

    ...
        <plugins>
            ...
            <plugin>
                ...
                <executions>
                    <execution>
                        <phase>install</phase>
                        <goals>
           	                 <goal>goal</goal>
                        </goals>
                    </execution>
                </executions>
                ...
            </plugin>
            ...
        </plugins>
...
    goal

    The goal to use. See Maven Goals for Embedded GlassFish Server.

  4. Configure the repository.

    Add the following repository element to your POM file:

    <pluginRepositories>
    <pluginRepository>
        <id>maven2-repository.dev.java.net</id>
        <name>Java.net Repository for Maven</name>
        <url>http://download.java.net/maven/glassfish/</url>
    </pluginRepository>
</pluginRepositories>
Example 12 POM File for Configuring Maven to Use Embedded GlassFish Server

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

<?xml version="1.0" encoding="UTF-8"?>
<!--
Line breaks in the following element are for readability purposes only
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>org.glassfish</groupId>
  <artifactId>maven-glassfish-plugin-tester</artifactId>
  <version>3.0-74b</version>
  <name>Maven test</name>
  <build>
    <plugins>
      <plugin>
        <groupId>org.glassfish</groupId>
        <artifactId>maven-embedded-glassfish-plugin</artifactId>
        <version>3.0-74b</version>
        <configuration>
          <goalPrefix>embedded-glassfish</goalPrefix>
          <app>test.war</app>
          <port>8080</port> 
          <contextRoot>test</contextRoot> 
          <autoDelete>true</autoDelete>
       </configuration>
       <executions>
          <execution>
             <phase>install</phase>
             <goals>
           	    <goal>run</goal>
             </goals>
          </execution>
       </executions>
     </plugin>
    </plugins> 
  </build>
  <pluginRepositories>
      <pluginRepository>
          <id>maven2-repository.dev.java.net</id>
          <name>Java.net Repository for Maven</name>
          <url>http://download.java.net/maven/glassfish/</url>
      </pluginRepository>
  </pluginRepositories>
</project>

ProcedureTo Build and Start an Application From Maven

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 GlassFish Server.

Before You Begin

Ensure that your Maven environment is configured.

  1. Include the path to the Maven executable file mvn in your path statement.

  2. Ensure that the JAVA_HOME environment variable is defined.

  3. Create a directory for the Maven project for your application.

  4. Copy to your project directory the POM file that you created in To Set Up Your Maven Environment.

  5. Run the following command in your project directory:


    mvn install

    This command performs the following actions:

    • Installs the Maven repository in a directory named .m2 under your home directory.

    • Starts embedded GlassFish Server.

    • Deploys your application.

    The application continues to run in embedded GlassFish Server until embedded GlassFish Server is stopped.

ProcedureTo Stop Embedded GlassFish Server

  1. Change to the root directory of the Maven project for your application.

  2. Run the Maven goal to stop the application in embedded GlassFish Server.


    mvn embedded-glassfish:stop

    This runs the stop method of the Server object and any other methods that are required to shut down the server in an orderly fashion. See Stopping an Embedded GlassFish Server From an Application.

ProcedureTo Redeploy an Application That Was Built and Started From Maven

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

  1. In the window from where the application was built and started from Maven, press Enter.

Maven Goals for Embedded GlassFish Server

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

embedded-glassfish:run Goal

This goal starts the server and deploys an application. You can redeploy if you change the application. The application can be a packaged archive or a directory that contains an exploded application. You can set the parameters described in the following table.

Table 3 embedded-glassfish:run Parameters

Parameter 

Default 

Description 

serverID

maven

(optional) The ID of the server to start. 

containerType

all

(optional) The container to start: web, ejb, jpa, or all.

installRoot

In order of precedence: 

  • glassfish.embedded.tmpdir system property value

  • user.dir system property value

  • Current directory

(optional) The Installation Root Directory.

instanceRoot

as-install/domains/domain1

(optional) The Instance Root Directory

configFile

domain-dir/config/domain.xml

(optional) The configuration file. 

port

None. Must be set explicitly or defined in the configuration file. 

(optional) The HTTP port. 

app

None. 

The archive file or directory for the application to be deployed. 

name

In order of precedence: 

  • The application-name or module-name in the deployment descriptor.

  • The name of the archive file without the extension or the directory name.

For more information, see Naming Standards in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

(optional) The name of the application. 

contextRoot

The name of the application. 

(optional) The context root of the application. 

precompileJsp

false

(optional) If true, JSP pages are precompiled during deployment.

createTables

Value of the create-tables-at-deploy attribute in sun-ejb-jar.xml.

(optional) If true, creates database tables during deployment for beans that are automatically mapped by the EJB container.

autoDelete

false

(optional) If true, deletes the contents of the Instance Root Directory when the server is stopped.

Caution – Caution –

Do not set autoDelete to true if you are using installRoot to refer to a preexisting GlassFish Server installation.

embedded-glassfish:start Goal

This goal starts the server. You can set the parameters described in the following table.

Table 4 embedded-glassfish:start Parameters

Parameter 

Default 

Description 

serverID

maven

(optional) The ID of the server to start. 

containerType

all

(optional) The container to start: web, ejb, jpa, or all.

installRoot

In order of precedence: 

  • glassfish.embedded.tmpdir system property value

  • user.dir system property value

  • Current directory

(optional) The Installation Root Directory.

instanceRoot

as-install/domains/domain1

(optional) The Instance Root Directory

configFile

domain-dir/config/domain.xml

(optional) The configuration file. 

port

None. Must be set explicitly or defined in the configuration file. 

(optional) The HTTP port. 

autoDelete

false

(optional) If true, deletes the contents of the Instance Root Directory when the server is stopped.

Caution – Caution –

Do not set autoDelete to true if you are using installRoot to refer to a preexisting GlassFish Server installation.

embedded-glassfish:deploy Goal

This goal deploys an application. You can redeploy if you change the application. The application can be a packaged archive or a directory that contains an exploded application. You can set the parameters described in the following table.

Table 5 embedded-glassfish:deploy Parameters

Parameter 

Default 

Description 

app

None. 

The archive file or directory for the application to be deployed. 

name

In order of precedence: 

  • The application-name or module-name in the deployment descriptor.

  • The name of the archive file without the extension or the directory name.

For more information, see Naming Standards in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

(optional) The name of the application. 

contextRoot

The name of the application. 

(optional) The context root of the application. 

precompileJsp

false

(optional) If true, JSP pages are precompiled during deployment.

createTables

Value of the create-tables-at-deploy attribute in sun-ejb-jar.xml.

(optional) If true, creates database tables during deployment for beans that are automatically mapped by the EJB container.

embedded-glassfish:undeploy Goal

Note –

If you reference a nonembedded GlassFish Server installation using the glassfish-embedded-static-shell.jar file and do not undeploy your applications in the same server life cycle in which you deployed them, expanded archives for these applications remain under the domain-dir/applications directory.

This goal undeploys an application. You can set the parameters described in the following table.

Table 6 embedded-glassfish:undeploy Parameters

Parameter 

Default 

Description 

name

If the name is omitted, all applications are undeployed. 

The name of the application. 

dropTables

Value of the drop-tables-at-undeploy attribute in sun-ejb-jar.xml.

(optional) If true, and deployment and undeployment occur in the same JVM session, database tables that were automatically created when the bean(s) were deployed are dropped when the bean(s) are undeployed.

If true, the name parameter must be specified or tables may not be dropped.

cascade

false

(optional) If true, deletes all connection pools and connector resources associated with the resource adapter being undeployed.

If false, undeployment fails if any pools or resources are still associated with the resource adapter.

This attribute is applicable to connectors (resource adapters) and applications with connector modules. 

embedded-glassfish:stop Goal

This goal stops the server. You can set the parameters described in the following table.

Table 7 embedded-glassfish:stop Parameters

Parameter 

Default 

Description 

serverID

maven

(optional) The ID of the server to stop. 

Using the EJB 3.1 Embeddable API with Embedded GlassFish Server

The EJB 3.1 Embeddable API is designed for unit testing of EJB modules. You must use this API with a pre-installed, nonembedded GlassFish Server instance. However, you can take advantage of the embedded GlassFish Server's ease of use by referencing the nonembedded GlassFish Server instance with the glassfish-embedded-static-shell.jar file.

Embedded GlassFish Server is not related to the EJB 3.1 Embeddable API, but you can use these APIs together.

The Maven plug-in does not apply to embeddable EJB applications. However, you can use Maven with the POM file shown in Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server.

The EJB 3.1 Embeddable API is described in Java Specification Request (JSR) 318. An ejb-embedded sample is included in the samples available at Java EE 6 Downloads or Code Samples.

ProcedureTo Use the EJB 3.1 Embeddable API with Embedded GlassFish Server

  1. To specify GlassFish Server as the Container Provider, include glassfish-embedded-static-shell.jar in the class path of your embeddable EJB application.

    See Setting the Class Path and Section 22.3.3 of the EJB 3.1 Specification, Embeddable Container Bootstrapping.

  2. Configure any required resources.

    For more information about configuring resources, see the Administration Console Online Help or Part III, Resources and Services Administration, in Oracle GlassFish Server 3.0.1 Administration Guide. The jdbc/__default Java DB database is preconfigured with all distributions of GlassFish Server.

  3. Invoke one of the createEJBContainer methods.

    Note –

    Do not deploy your embeddable EJB application or any of its dependent Java EE modules before invoking one of the createEJBContainer methods. These methods perform deployment in the background and do not load previously deployed applications or modules.

  4. To change the Instance Root Directory, set the org.glassfish.ejb.embedded.glassfish.instance.root system property value by using the createEJBContainer(Map<?, ?> properties) method.

    The default Instance Root Directory location is as-install/domains/domain1. This system property applies only to embeddable EJB applications used with nonembedded GlassFish Server.

  5. Close the EJB container properly to release all acquired resources and threads.

Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server

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

Example 13 Maven POM File for Using the EJB 3.1 Embeddable API with Embedded GlassFish Server

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

<!--
Line breaks in the following element are for readability purposes only
-->
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.glassfish</groupId>
    <artifactId>maven-glassfish-plugin-tester</artifactId>
    <version>3.0-74b</version>
    <name>Maven test</name>
    <dependencies>
        <dependency>
            <groupId>org.glassfish.extras</groupId>
            <artifactId>glassfish-embedded-all</artifactId>
            <version>3.0</version>
        </dependency>
<!--
        The javaee-api is stripped of any code and is just used to compile your
        application. The scope provided in Maven means that it is used for compiling,
        but is also available when testing. For this reason, the javaee-api needs to
        be below the embedded Glassfish dependency. The javaee-api can actually be 
        omitted when the embedded Glassfish dependency is included, but to keep your
        project Java-EE 6 rather than GlassFish 3, specification is important.
-->
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>6.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <pluginRepositories>
        <pluginRepository>
            <id>maven2-repository.dev.java.net</id>
            <name>Java.net Repository for Maven</name>
            <url>http://download.java.net/maven/glassfish/</url>
        </pluginRepository>
    </pluginRepositories>
</project>

Changing Log Levels in Embedded GlassFish Server

To change log levels in Embedded GlassFish Server, you can follow the steps in this section or you can use the Embedded Server API as shown in Example 9. For more information about GlassFish Server logging, see Chapter 7, Administering the Logging Service, in Oracle GlassFish Server 3.0.1 Administration Guide.

ProcedureTo Change Log Levels in Embedded GlassFish Server

  1. Ensure that you have write permission access to the $JAVA_HOME/jre/lib/logging.properties file.

  2. Use a text editor to edit the $JAVA_HOME/jre/lib/logging.properties file.

  3. Change the java.util.logging.ConsoleHandler.level log level to FINE or FINEST.

  4. Add GlassFish Server log levels to the end of the file and adjust them as necessary.

    For example, add javax.enterprise.system.tools.deployment.level=FINE.

Restrictions for Embedded GlassFish Server

The glassfish-embedded-web.jar file for embedded GlassFish Server supports only these features of nonembedded GlassFish Server:

The other embedded GlassFish Server JAR files, glassfish-embedded-all.jar and glassfish-embedded-static-shell.jar, support all features of nonembedded GlassFish Server with these exceptions:

Embedded GlassFish Server requires no installation or configuration. As a result, the following files and directories are absent from the file system until embedded GlassFish Server is started:

When embedded GlassFish Server is started, the base installation directory that GlassFish Server uses depends on the options with which GlassFish Server is started. For more information, see Specifying an Embedded GlassFish Server File System. If necessary, embedded GlassFish Server creates a base installation directory. Embedded GlassFish Server then copies the following directories and their contents from the Java archive (JAR) file in which embedded GlassFish Server is distributed:

If necessary, GlassFish Server also creates an instance root directory.