GlassFish Server Open Source Edition 3.1 - Embedded One Pager

1. Introduction

1.1. Project/Component Working Name:

Embedded Glassfish

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

• Bhavanishankara Sapaliga (bhavanishankar@java.net)
• Siraj Ghaffar (sirajg@java.net)
• Amy Roh (amyroh@java.net)

1.3. Date of This Document:

05/19/2010

2. Project Summary

2.1. Project Description:

The objective of the embedded GlassFish project is to enable running of GlassFish in the JVM of the user's application. This means that GlassFish should run inside a user's application, instead of the other way around. No GlassFish installation or configuration should be required. A related objective is that the embedded functionality should work with the regular installation of GlassFish as well. Embedded glassfish would work with the same set of JVMs as regular glassfish.

3.0 introduced the embedded feature for the first time. Objectives of GlassFish Server Open Source Edition 3.1 release are :

1. Formalize the embedded API.
2. Improve parity with regular GlassFish, so that more applications working in regular glassfish, work in embedded mode. This involves testing and fixing issues found while using various components of GlassFish in embedded mode. Priority to be given to web tests, as that seems to be more relevant to embedded users.
3. Look into specific customer use cases and make sure those requirements are met.

2.2. Risks and Assumptions:

1. To improve parity with regular glassfish (2.1/2 above), testing will be done by running devtests in embedded mode.
2. Additional specific customer requirements may result in some changes in plans.

3. Problem Summary

3.1. Problem Area:

Problem areas addresses by embedded are :

• Developer Productivity
• Application Testing
• ISVs - can bundle glassfish as a "library"

Two primary categories of users are expected :

• Maven users, mainly developers who want to run and test their applications in embedded glassfish using the embedded maven plugin
• More advanced users who would want to directly use the Embedded APIs.

3.2. Justification:

Embedded is an important developer feature, used by members of the GlassFish community. It also offers potential opportunities with respect to the ISV use case.

4. Technical Description:

4.1. Details:

4.1.1 Modes and distributions :

• implanted: This uses an existing GlassFish installation and requires having glassfish/lib/embedded/glassfish-embedded-static-shell.jar in your classpath. The JAR itself is an empty shell. The Class-Path entry in META-INF/MANIFEST.MF of the jar has relative references to most of the JARs in the modules directory of the glassfish distribution. The shell jar is part of the glassfish and web distributions. For 3.0, EJB embedded API is supported in this mode only.

• autonomous: This does not require an existing GlassFish installation. When there is no installation pointed to, a temporary file system is created. Applications deployed to the embedded server reside in this directory. For easier distribution this mode is available in all-in-one jar in 3 flavors. These jars are not generated as part of regular glassfish build and are not part of the regular glassfish distribution.

The complete application+runtime bundle can then be deployed using a variety of deployment mechanisms - for example, using maven, an installer, zip or even Java Web Start.

In both the implanted and autonomous modes, a custom domain.xml can be specified.

4.1.2 Embedded API :

The embedded API provides convenient methods to control the life cycle of the embedded server and to deploy applications to it.

This is the common import statement for all the code snippets below:

import org.glassfish.embeddable.GlassFish;
import org.glassfish.embeddable.GlassFishProperties;
import org.glassfish.embeddable.GlassFishRuntime;
import org.glassfish.embeddable.web.Context;
import org.glassfish.embeddable.web.HttpListener;
import org.glassfish.embeddable.web.VirtualServer;
import org.glassfish.embeddable.web.WebContainer;
import org.glassfish.embeddable.web.WebListener;

A sample piece of code that binds the web container to a specific port and deploys a packaged .war to the embedded server.

// Create a Embedded GlassFish instance to listen at 9090 http port
        GlassFishProperties glassfishProperties = new GlassFishProperties();
        glassfishProperties.setPort("http-listener", 9090);
        GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);

        // Start Embedded GlassFish
        glassfish.start();

        // Deploy an application to the Embedded GlassFish
        Deployer deployer = glassfish.getDeployer();
        String appName = deployer.deploy(new File("hello.war"),
                "--contextroot=hello", "--name=app1");

        // Undeploy the application
        deployer.undeploy(appName);

        // Stop Embedded GlassFish
        glassfish.stop();

        // Dispose Embedded GlassFish. This will clean up any temporary file system created by Embedded GlassFish
        glassfish.dispose();

Sample of using embedded server with an existing domain.xml. Any custom port configuration can be done in the domain.xml that is passed in here.

// Create a Embedded GlassFish instance using a preconfigured domain.xml
        GlassFishProperties glassfishProperties = new GlassFishProperties();
        glassfishProperties.setConfigFileURI(new File("myExistingdomain.xml").toURI().toString()); // this is the only change to the above code.
        GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);

        // Start Embedded GlassFish
        glassfish.start();

        // Deploy an application to the Embedded GlassFish
        Deployer deployer = glassfish.getDeployer();
        String appName = deployer.deploy(new File("hello.war"),
                "--contextroot=hello", "--name=app1");

        // Undeploy the application
        deployer.undeploy(appName);

        // Stop Embedded GlassFish
        glassfish.stop();

        // Dispose Embedded GlassFish. This will clean up any temporary file system created by Embedded GlassFish
        glassfish.dispose();

Scattered Archive sample :

// Create a Embedded GlassFish instance to listen at 9090 http port
        GlassFishProperties glassfishProperties = new GlassFishProperties();
        glassfishProperties.setPort("http-listener", 9090);
        GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);

        // Start Embedded GlassFish
        glassfish.start();

        // Deploy a scattered application to the Embedded GlassFish
        Deployer deployer = glassfish.getDeployer();

         // Build a scattered web archive.
         ScatteredArchive archive = new ScatteredArchive("testapp", ScatteredArchive.Type.WAR);
         // target/classes directory contains my complied servlets
         archive.addClassPath(new File("target", "classes"));
         // resources/sun-web.xml is my WEB-INF/sun-web.xml
         archive.addMetadata(new File("resources", "sun-web.xml"));
         // resources/web.xml is my WEB-INF/web.xml
         archive.addMetadata(new File("resources", "web.xml"));

        // Deploy the scattered web archive.
        String appName = deployer.deploy(archive.toURI(), "--contextroot=hello");

        // Undeploy the scattered web application
        deployer.undeploy(appName);

        // Stop Embedded GlassFish
        glassfish.stop();

        // Dispose Embedded GlassFish. This will clean up any temporary file system created by Embedded GlassFish
        glassfish.dispose();

Sample of using embedded web API to create an application context and add a http listener for it.

// Create a Embedded GlassFish instance which listens at 9090 http port
        GlassFishProperties glassfishProperties = new GlassFishProperties();
        glassfishProperties.setPort("http-listener", 9090);
        GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish(glassfishProperties);

        // Start Embedded GlassFish
        glassfish.start();

        /* Create an application context and a http listener */
        // Get WebContainer service
        WebContainer webContainer = glassfish.getService(WebContainer.class);

        // Create a http listener to listen at port 9292 and add it to the web container.
        HttpListener httpListener = webContainer.createWebListener(
                "test-listener", HttpListener.class);
        httpListener.setPort(9292);
        webContainer.addWebListener(httpListener);

        // Create a web application context
        Context context = webContainer.createContext(new File("/tmp/hello-app"));
        webContainer.addContext(context, "hello");

        // With that, you can access http://localhost:9292/hello

        // Stop Embedded GlassFish
        glassfish.stop();

        // Dispose Embedded GlassFish. This will clean up any temporary file system created by Embedded GlassFish
        glassfish.dispose();

4.1.3 Tooling :

Maven plugin

3.0 introduced a maven plugin that allows users to start, stop and configure the server and to deploy and undeploy applications. Following are the various goals supported by the plugin. The artifactID for the plugin is glassfish-embedded-maven-plugin. The various parameters used in different goals are summarized below :

Following is a summary for the various plugin goals :

• embedded-glassfish:run

The goal will start the server, deploy the application and will keep running. The user can chose to redeploy while the plugin is running, if changes are made to the application. It is interactive - when the user presses "Enter" on console the application is redeployed.

Parameters :

app, serverID, containerType, installRoot, instanceRoot, configFile, port, name, contextRoot, precompileJsp, dbVendorName, createTables, dropTables, autoDelete.

• embedded-glassfish:start

This will start the embedded server with specified container(s)

Parameters :

serverID, installRoot, instanceRoot, configFile, port, containerType, autoDelete

• embedded-glassfish:deploy

Parameters :

Deploys the specified archive to the embedded server.

serverID, name, app, contextRoot , precompileJsp, createTables, dbVendorName, createTables

• embedded-glassfish:undeploy

Parameters :

serverID, name, dropTables, cascade - if no name is specifed all applications will be undeployed.

• embedded-glassfish:stop

serverID

• embedded-glassfish:admin

Runs appserver administration commands in embedded. Either command+commandParameters or commandLine should be specified.

Ant tasks

3.1 will also support ant tasks for embedded. These are expected to be mostly used for running dev tests in embedded mode. Following is a summary of the tasks :

• glassfish-embedded-start :
serverID, port, installRoot, instanceRoot, configFile, containerType, autoDelete.

• glassfish-embedded-stop :
serverID

• glassfish-embedded-deploy :
name, app, contextRoot , precompileJsp, createTables, dbVendorName, createTables

• glassfish-embedded-undeploy :
serverID, name, cascade

• glassfish-embedded-admin :
serverID, command, commandParameters, commandLine

4.2. Bug/RFE Number(s):

P1-P3 bugs in the embedded category filed in issuetracker will be addressed.

4.3. In Scope:

Priority would be given to technologies related to web profile, since that appears to be the more relevant to most users.

4.4. Out of Scope:

Clustering will not be supported in embedded mode.

4.5. Interfaces:

Interfaces may be commands, files, directory structure, ports,
DTD/Schema, tools, APIs, CLIs, etc.
Note: In lieu of listing the interfaces in the one pager, providing
a link to another specification which defines the interfaces
is acceptable.

4.5.1 Public Interfaces

List new, public interfaces this project exports.

• Interface: Embedded API
• Interface: glassfish-embedded-plugin, a maven plugin for embedded, documented in section 4.1.3
• Interface: Ant tasks, documented in section 4.1.3

4.5.2 Private Interfaces

None identified at this time.

4.5.3 Deprecated/Removed Interfaces:

None identified at this time

4.6. Doc Impact:

Embedded API usage and maven plugin will need to be documented

4.7. Admin/Config Impact:

None

Identify changes to GUIs, CLI, agents, plugins...
None

4.8. HA Impact:

None

4.9. I18N/L10N Impact:

Some user visible messages will need to be localized.

4.10. Packaging, Delivery & Upgrade:

4.10.1. Packaging

• What packages does this proposal impact? None
• How will the packages be impacted? None
• Will new IPS/pkg(5) packages need to be created? New IPS package for ant-tasks.

4.10.2. Delivery

• glassfish-embedded-static-shell is part of glassfish and web distributions.
• glassfish-embedded-all.jar, glassfish-embedded-web and glassfish-embedded-nucleus.jar are downloadable separately. The download locations are specified in section 4.1.1. These would additionally be available from Update Center.
• The embedded maven plugin, glassfish-embedded-maven-plugin, is released separately and is available from maven repository.
• Embedded ant tasks will be available from the update center.

What impact will this proposal have on product installation?
None

4.10.3. Upgrade and Migration:

No impact on upgrade and migration.

4.11. Security Impact:

None

4.12. Compatibility Impact

None

4.13. Dependencies:

• WebTier - WEB-6
• EJB
• Connectors/resource - JCA-5
• Security - SEC-017
• JPA

4.14. Testing Impact:

Existing dev tests from various components will be used to test embedded. These tests will run in an optional embedded mode. Priority will be given to running web dev tests.

5. Reference Documents:

• Project details including milestone details : Project Page

6. Schedule:

6.1. Projected Availability:

Milestone 7. Refer to the Milestone Planning Document for more details.

Please note that the ScatteredArchive class is present in the org.glassfish.embedded.api package in Glassfish 3.1-SNAPSHOT as of 2011-01-31, even though the Javadoc says it should be in the org.glassfish.embeddable.archive package. Posted by ljnelson at Jan 31, 2011 10:13