test

Oracle GlassFish Server 3.0.1 Embedded Server Guide

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.