1 Oracle GlassFish Server 3.1.2 Embedded Server Guide

Installation Root Directory

The installation root directory, represented as as-install, is the parent of the directory that embedded 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:

• domains

• lib

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

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 only if you have a valid nonembedded GlassFish Server domain directory and are using glassfish-embedded-static-shell.jar.

If domain-dir is not specified, GlassFish Server creates a directory named gfembedrandom-numbertmp in a temporary directory, where random-number is a randomly generated 19-digit number. GlassFish Server 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.

The 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 setConfigFileURI method of the GlassFishProperties class as described in Creating and Configuring an Embedded GlassFish Server.

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-nucleus.jar

Corresponds to the nucleus distribution. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/glassfish-embedded-nucleus/.

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-web/.

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-all/.

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. Reference this file from the as-install/lib/embedded directory of a nonembedded GlassFish Server installation. Do not move this file or it will not work. 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 (JDBC) 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.

The following topics are addressed here:

• Creating and Configuring an Embedded GlassFish Server

• Running an Embedded GlassFish Server

setInstallRoot(String as-install)

setInstanceRoot(String domain-dir)

setConfigFileURI(String configFileURI)

setConfigFileReadOnly(boolean readOnly)

...
import org.glassfish.embeddable.*;
...
    GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish();
    glassfish.start();
...

...
import org.glassfish.embeddable.*;
...
    BootstrapProperties bootstrapProperties = new BootstrapProperties();
    bootstrapProperties.setInstallRoot("C:\\samples\\test\\applicationserver");    
    GlassFishRuntime glassfishRuntime = GlassFishRuntime.bootstrap(bootstrapProperties);

    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setInstanceRoot("C:\\samples\\test\\applicationserver\\domains\\domain1");
    GlassFish glassfish = glassfishRuntime.newGlassFish(glassfishProperties);

    glassfish.start();

...

...
import org.glassfish.embeddable.*;
...
    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setPort("http-listener", 8080);
    glassfishProperties.setPort("https-listener", 8181);
...

...
import org.glassfish.embeddable.*;
...
    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setPort("http-listener", 8080);
    glassfishProperties.setPort("https-listener", 8181);
    ...
    GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);
    glassfish.start();
...

...
import java.io.BufferedReader;
...
import org.glassfish.embeddable.*;
...
    System.out.println("Press Enter to stop server");
        // wait for Enter
    glassfish.stop(); // Stop Embedded GlassFish Server
...

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.

The following topics are addressed here:

• To Deploy an Application From an Archive File or a Directory

• Undeploying an Application

• Creating a Scattered Archive

• Creating a Scattered Enterprise Archive

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

...
import java.io.File;
...
import org.glassfish.embeddable.*;
...
    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setPort("http-listener", 8080);
    glassfishProperties.setPort("https-listener", 8181);
    ...
    GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);
    glassfish.start();
    File war = new File("c:\\samples\\simple.war");
    Deployer deployer = glassfish.getDeployer();
    deployer.deploy(war, "--name=simple", "--contextroot=simple", "--force=true");
    // deployer.deploy(war) can be invoked instead. Other parameters are optional.
...

...
import org.glassfish.embeddable.*;
...
    deployer.undeploy(war, "--droptables=true", "--cascade=true");
...

ScatteredArchive(String name, 
ScatteredArchive.Type type)

ScatteredArchive(String name, 
ScatteredArchive.Type type,
File topDir)

addClassPath(File path)

addMetaData(File path)

addMetaData(File path,
String name)

toURI()

...
import java.io.File;
...
import org.glassfish.embeddable.*;
...
    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setPort("http-listener", 9090);
    GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);
    glassfish.start();
    Deployer deployer = glassfish.getDeployer();
    ScatteredArchive archive = new ScatteredArchive("testapp", ScatteredArchive.Type.WAR);
    // target/classes directory contains complied servlets
    archive.addClassPath(new File("target", "classes"));
    // resources/sun-web.xml is the WEB-INF/sun-web.xml
    archive.addMetadata(new File("resources", "sun-web.xml"));
    // resources/web.xml is the WEB-INF/web.xml
    archive.addMetadata(new File("resources", "web.xml"));
    // Deploy the scattered web archive.
    String appName = deployer.deploy(archive.toURI(), "--contextroot=hello");

    deployer.undeploy(appName);
    glassfish.stop();
    glassfish.dispose();
...

ScatteredEnterpriseArchive(String name)

addArchive(File archive)

addArchive(File archive,
String name)

addArchive(URI URI)

addArchive(URI URI,
String name)

addMetaData(File path)

addMetaData(File path,
String name)

toURI()

...
import java.io.File;
...
import org.glassfish.embeddable.*;
...
    GlassFishProperties glassfishProperties = new GlassFishProperties();
    glassfishProperties.setPort("http-listener", 9090);
    GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);
    glassfish.start();
    Deployer deployer = glassfish.getDeployer();

    // Create a scattered web application.
    ScatteredArchive webmodule = new ScatteredArchive("testweb", ScatteredArchive.Type.WAR);
    // target/classes directory contains my complied servlets
    webmodule.addClassPath(new File("target", "classes"));
    // resources/sun-web.xml is my WEB-INF/sun-web.xml
    webmodule.addMetadata(new File("resources", "sun-web.xml"));
 
    // Create a scattered enterprise archive.
    ScatteredEnterpriseArchive archive = new ScatteredEnterpriseArchive("testapp");
    // src/application.xml is my META-INF/application.xml
    archive.addMetadata(new File("src", "application.xml"));
    // Add scattered web module to the scattered enterprise archive.
    // src/application.xml references Web module as "scattered.war". 
    //Hence specify the name while adding the archive.
    archive.addArchive(webmodule.toURI(), "scattered.war");
    // lib/mylibrary.jar is a library JAR file.
    archive.addArchive(new File("lib", "mylibrary.jar"));
    // target/ejbclasses contain my compiled EJB module.
    // src/application.xml references EJB module as "ejb.jar". 
    //Hence specify the name while adding the archive.
    archive.addArchive(new File("target", "ejbclasses"), "ejb.jar");
 
    // Deploy the scattered enterprise archive.
    String appName = deployer.deploy(archive.toURI());

    deployer.undeploy(appName);
    glassfish.stop();
    glassfish.dispose();
...

Running asadmin Commands Using the GlassFish Server Embedded Server API

Running asadmin 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 Administration Guide. For detailed information about asadmin commands, see Section 1 of the Oracle GlassFish Server 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.

...
import org.glassfish.embeddable.*;
...
    String command = "create-jdbc-resource";
    String poolid = "--connectionpoolid=DerbyPool";
    String dbname = "jdbc/DerbyPool";
    CommandRunner commandRunner = glassfish.getCommandRunner();
    CommandResult commandResult = commandRunner.run(command, poolid, dbname);
...

...
import org.glassfish.embeddable.*;
...
    String command = "set-log-level";
    String weblevel = "javax.enterprise.system.container.web=FINE";
    CommandRunner commandRunner = glassfish.getCommandRunner();
    CommandResult commandResult = commandRunner.run(command, weblevel);
...

Sample Applications

import java.io.File;
import java.io.BufferedReader;
import org.glassfish.embeddable.*;

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

    public static void main(String[] args) {
        File configFile = new File ("c:\\myapp\\embeddedserver\\domains\\domain1\\config\\domain.xml");
        File war = new File("c:\\samples\\simple.war");
        try {
            GlassFishRuntime glassfishRuntime = GlassFishRuntime.bootstrap();
            ...
            GlassFishProperties glassfishProperties = new GlassFishProperties();
            glassfishProperties.setConfigFileURI(configFile.toURI());
            glassfishProperties.setConfigFileReadOnly(false);
            ...
            GlassFish glassfish = glassfishRuntime.newGlassFish(glassfishProperties);
            glassfish.start();
            
            Deployer deployer = glassfish.getDeployer();
            deployer.deploy(war, "--force=true");
        }
        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 {
            glassfish.dispose();
            glassfishRuntime.shutdown();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}

To 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>
                   <artifactId>maven-embedded-glassfish-plugin</artifactId>
                   <version>version</version>
               </plugin>
               ...
           </plugins>
   ...
   

   version

   The version to use. The version of the final promoted build for this release is 3.1. The Maven plug-in is not bound to a specific version of GlassFish Server. You can specify the version you want to use. If no version is specified, a default version, 3.1 for this release, is used.

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>target/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. Perform advanced plug-in configuration. This step is optional.

   Add the following configuration element to your POM file:

   ...
           <plugins>
               ...
               <plugin>
                   ...
                   <configuration>
                       <goalPrefix>embedded-glassfish</goalPrefix>
                       <app>target/test.war</app>
                       <name>test</name>
                       <contextRoot>test</contextRoot>
                       <ports>
                           <http-listener>8080</http-listener>
                           <https-listener>8181</https-listener>
                       </ports>
                       <bootstrapProperties>
                           <property>test_key=test_value</property>
                       </bootstrapProperties>
                       <bootstrapPropertiesFile>bootstrap.properties</bootstrapPropertiesFile>
                       <glassfishProperties>
   <property>embedded-glassfish-config.server.jms-service.jms-host.default_JMS_host.port=17676</property>
                       </glassfishProperties>
                       <glassfishPropertiesFile>glassfish.properties</glassfishPropertiesFile>
                       <systemProperties>
                           <property>ANTLR_USE_DIRECT_CLASS_LOADING=true</property>
                       </systemProperties>
                       <systemPropertiesFile>system.properties</systemPropertiesFile>
                   </configuration>
                   <executions>
                       <execution>
                           <goals>
                               <goal>start</goal>
                               <goal>deploy</goal>
                               <goal>undeploy</goal>
                               <goal>stop</goal>
                           </goals>
                       </execution>
                   </executions>
               </plugin>
               ...
           </plugins>
   ...
   

4. 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.

5. 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>
   

<?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.1</version>
  <name>Maven test</name>
  <build>
    <plugins>
      <plugin>
        <groupId>org.glassfish</groupId>
        <artifactId>maven-embedded-glassfish-plugin</artifactId>
        <version>3.1</version>
        <configuration>
          <goalPrefix>embedded-glassfish</goalPrefix>
          <app>target/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>

To 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, as described in To Set Up Your Maven Environment.

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.

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

To 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.

To redeploy, 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

• embedded-glassfish:start Goal

• embedded-glassfish:deploy Goal

• embedded-glassfish:undeploy Goal

• embedded-glassfish:stop Goal

• embedded-glassfish:admin Goal

To 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 or glassfish-embedded-all.jar in the class path of your embeddable EJB application.

   Reference the glassfish-embedded-static-shell.jar file from the as-install/lib/embedded directory of a GlassFish Server installation. Do not move this file or it will not work.

   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 "Resources and Services Administration" in Oracle GlassFish Server Administration Guide. The jdbc/__default Java DB database is preconfigured with all distributions of GlassFish Server. However, if you are using glassfish-embedded-static-shell.jar, you must start the database manually.

   If your embeddable EJB application uses Java Persistence, you do not need to specify a JDBC resource. See Default Java Persistence Data Source for Embedded 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 if a nonembedded installation is referenced. 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.

EJB 3.1 Embeddable API Properties

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.

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.

<!--
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>my-ejb-app-tester</artifactId>
    <version>3.1</version>
    <name>Maven test</name>
    <dependencies>
        <dependency>
            <groupId>org.glassfish.extras</groupId>
            <artifactId>glassfish-embedded-static-shell</artifactId>
            <version>${project.version}</version>
            <scope>system</scope>
            <systemPath>
                ${env.S1AS_HOME}/lib/embedded/glassfish-embedded-static-shell.jar
            </systemPath>
        </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>