GlassFish - World's first Java EE 7 Application Server


Embeddable GlassFish One Pager

[

Unknown macro: {TableOfContents title=' '}

|(TableOfContentstitle='')]

1. Introduction

1.1. Project/Component Working Name:

  1. Embedded GlassFish

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

Byron Nevins

byron.nevins@sun.com

1.3. Date of This Document:

Started: July 14, 2008

2. Project Summary

2.1. Project Description:

Embedded GlassFish - GlassFish can run inside any user-provided JVM. No GlassFish installation or configuration is required. This allows a user to run GlassFish inside their application rather than the other way around.

2.1.1 General Requirements

  • A properly configured user-supplied Java application must be able to start, stop and deploy applications to a GlassFish server embedded in the same JVM.

2.2 Risks and Assumptions:

2.2.1 Risks and Assumptions:

Kohsuke has already completed proof-of-concept testing. So Embedded has been proven to be possible.

There is little risk in the usual sense because

  1. This is a brand new feature. No risk of breaking the old implementation.
  2. The feature will be designed to be as separated as possible from V3 core.

That being said there will be an ever-present risk of changes in V3 core causing problems in embedded.
E.g. if new code is added to the web container that insists on finding a file at a certain location relative to the installation directory, then the embedded scenario will break since there is no installation directory. The solution here is to have thorough embedded test cases that are run all the time to catch new problems in core in the bud.

2.2.2 Assumptions:

Embedded GlassFish is not designed for use by Java ME.
Embeddable GlassFish will support servlets and web services, only, for the prelude release.

3. Problem Summary

3.1. Problem Area:

There are several needs (rather than problems per se) that this project addresses:

  • Developer Productivity
  • Application Testing

3.2. Justification:

Embedded GlassFish is a long sought after feature for developers.
It will compete head-on with Jetty but will offer much more functionality. I.e. Jetty supports embedded servlets while Embedded GlassFish supports EJB, servlets, JSPs, scripting, etc.

In addition to using Embedded GlassFish permanently for an application, it will also be very useful for earlier stages of development and for testing.
E.g. a web service or servlet or EJB can have unit tests that test both the client and the server in the same JVM with zero required external configuration. GlassFish does not even need to be installed. The tests can even be run automatically with every build as a unit test.

4. Technical Description:

4.1. Details:

4.1.1 History

Embeddable GlassFish was created as a java.net project in April 2008 by Kohsuke Kawaguchi. The current project supports embedded servlets. Our plan is to build on this initial version for the prelude release.

4.1.2 How a developer uses Embeddable GlassFish

4.1.2.1 Classpath, binaries

In the diagram above, Modules of Your Choice are the core V3 modules required for the user's applications. The manner in which these modules are provided depends on the type of developer.
There are 2 main categories of targeted developers:

  • Maven Developers
  • Non-Maven developers

The Maven developers will most likely prefer setting up the V3 module dependencies directly in their pom files and then let Maven figure out all the dependencies, download the right jars and create the correct classpath.

Conversely the Non-Maven developers will not want to have to deal with downloading many jar files and adding them to their classpath. For these users we provide "all-in-one" jars. In this case the user can run the application easily from Ant or even the command line. Embedded GlassFish requires a minimum of 2 jar files in addition to the user's jars: the Embedded GlassFish API jar and at least one GlassFish Component. The current GlassFish Components are:

  • Web
  • Ejb
  • Scripting
  • Jpa
  • Jdbc

Only the Web Component will be supported in Prelude.

Note: I am using the word Component here to refer in a one-to-one manner to the contents of IPS packages
See the packaging section for more details

4.1.2.2 Runtime

At runtime the user calls into the Embedded GlassFish API to start the server, deploy applications and stop the server. See the API section for details.

4.1.3 How Embeddable Works

There are very straight forward implementation strategies that can be imagined. E.g. we could create a temporary domain on disk, then start a normal Implanted GlassFish instance that starts that domain. Then we deploy the application to that temporary domain. After running, the temporary domain is scrubbed off the disk. This technique works, and it was tested out. We felt this solution was wanting. Creating a domain is slow (several seconds) but more importantly we want a solution with these two crucial constraints:

  • No GlassFish installation is needed or used
  • No Domain is needed or used

This means, for instance, that

  • There is no applications directory
  • There is no file that contains password(s)
  • There is no default default-web.xml file
  • There is no instance root directory

Core V3 code is making assumptions such as:

  • There exists a file on disk named domain.xml that needs to be parsed
  • There exists a file on disk named default-web.xml that we need to parse defaults from

Embeddable needs to find all such dependencies on files and redirect to a temporary file or an in-memory representation or a resource inside the API jar.
This is exactly what was done for the April release of the first version of Embeddable Glassfish.

EXAMPLE
A default-web.xml is stored inside the API jar as a resource. The V3 class, WebDeployer, has code that looks on disk for the default-web.xml file. What we do is create a subclass, WebDeployer2, which uses the default-web.xml inside the API jar.
V3's architecture lends itself to easily do this. The HK2 InhabitantsParser instance contains the WebDeployer class. We remove that class and replace it with WebDeployer2. Now the rest of V3 will seamlessly work with our subclass.

4.1.4 Stretch Goals for Prelude

We will attempt to offer support for an Embedded EJB Container. We can not know if it is possible to do this properly in the brief time allotted. It is dependent on how many issues EJB container has with not having the usual installation file structure in place. I.e. it is dependent on unknowns.

4.1.5 Technical and Future Issues

  • All-In-One Jar files Currently this is straight forward since we are providing the web tier only in one large jar file. In later versions we will have to work out the details on how to do this. I.e. shall it be a core jar with one extra jar per V3 functionality module, or will we create many combinations of different modules?
  • Changes in the Core versus Changes in Embedded
    We will gradually remove dependence on file systems in core V3 by virtualizing and centralizing access to such resources. This will make the code cleaner and easier to understand in both Embedded and Core. The main theme is to not treat core Code as untouchable and force Embedded to go through hoops trying to conform to core. Rather we will make judicious targeted changes to core when required.
  • Configuration - The Prelude release of Embedded will support configuring the Embedded server by direct Java API method calls. One can easily imagine a point where the configuration of the Embedded server is too complicated for this approach to be convenient, but not complicated enough to use Implanted GlassFish or a regular server with a full domain.xml configuration file. We will offer support for using a user-supplied domain.xml file instead of the default one inside the api jar file.
    • Note that the Admin Commands and AdminAdapter will be unavailable in prelude.
    • AMX will be available from EmbeddableGlassFish Prelude.
  • Logging - Currently the V3 LogManagerService is dropped from the Embedded runtime. Logging messages are sent to the stdout of the JVM. We may want to add an API to log to external files.
  • Branding - A developer should be able to completely hide the fact that GlassFish is running inside. Log Messages and everything else should reflect the user's choice of name.

4.1.6 Example Usage Code

Here is example java code that will do the following:

  • Start an Embedded GlassFish server
  • Setup the HTTP listener port to 9999
  • Deploy MyWebApp
  • Wait for a key press from the console
  • Undeploy MyWebApp
  • Stop Embedded GlassFish
import org.glassfish.embed.GFApplication;
import org.glassfish.embed.GlassFish;
.......

public static void main(String[] args) throws Exception {
        GlassFish.setLogLevel(INFO);
        GlassFish glassfish = new GlassFish(9999);
        GFApplication app = glassfish.deploy(new File("MyWebApp.war"));
        System.out.println("Ready - Hit a key to stop the server and exit...");
        new BufferedReader(new InputStreamReader(System.in)).readLine();
        app.undeploy();
        glassfish.stop();
    }

Here is an example that does the same thing using a ScatteredWar:

import org.glassfish.embed.GFApplication;
import org.glassfish.embed.GlassFish;
import org.glassfish.embed.ScatteredWar;
.......

public static void main(String[] args) throws Exception {
        GlassFish.setLogLevel(INFO);
        GlassFish glassfish = new GlassFish(9999);
        File appDir = new File("MyWebApp");
        ScatteredWar war = new ScatteredWar(
                "MyWebApp",
                new File(appDir,"web"),
                new File(appDir,"web.xml"),
                Collections.singleton(
                    new File(appDir,"target/classes").toURI().toURL())
            );
        GFApplication app = glassfish.deploy(war);
        System.out.println("Ready - Hit a key to stop the server and exit...");
        new BufferedReader(new InputStreamReader(System.in)).readLine();
        app.undeploy();
        glassfish.stop();
    }

4.1.7 Deployment of Web Apps

  • ScatteredWar Deployment is fully supported.
  • Directory Deployment is fully supported
  • Web archive (war) Deployment is fully supported
  • Web Archive Files are exploded to a temp directory and are cleaned up upon exiting

4.1.8 Logging

Embedded does not use the V3 Logging Service. Instead the user can configure logging output in the standard SE way. We will format the logging output to look just like V3

4.1.9 OSGi

In the prelude release we will not support embedding into a JVM that has a user-supplied OSGi container.
The Final Release will support this.

4.2. Bug/RFE Number(s):

4.3. In Scope:

N/A

4.4. Out of Scope:

Administration of an Embedded GlassFish server, other than what was discussed above, is not supported.

4.5. Interfaces:

4.5.1 Exported Interfaces

4.5.2 Imported interfaces

N/A

4.5.3 Other interfaces (Optional)

N/A

4.6. Doc Impact:

  • The JavaDoc already exists but needs some fine-tuning
  • We need documentation on how to use Embedded GlassFish including descriptions of samples. This will also be the location of rules and regulations such as "Do not create your own NamingManager"
  • We will supply documentation on how to make a V3 Module embeddable – Post-Prelude
  • A document that describes how to convert a Jetty app to an Embeddable GlassFish app (post -prelude)

4.7. Admin/Config Impact:

Stretch Goal: Provide support for specifying a URL of file path of a user-provided domain.xml file.

4.8. HA Impact:

None

4.9. I18N/L10N Impact:

The usual internationalization of error messages and Exception messages.

4.10. Packaging & Delivery:

First of all, the user that wants to use Maven for everything is already covered. No packages or delivery are needed.
For the non-Maven developer or the developer that prefers to download everything we have these requirements:

  • glassfish-embedded-api.jar (raw API only)
  • glassfish-embedded-nucleus.jar * (contains raw API and the equivalent of a nucleus v3 distribution)
  • glassfish-embedded-web.jar (web tier)
  • glassfish-embedded-ejb.jar (ejb tier)
  • glassfish-embedded-jpa.jar (Persistence support with EclipseLink)
  • glassfish-embedded-jdbc.jar (JDBC support)
  • glassfish-embedded-scripting.jar (Scripting support)
  • glassfish-embedded-all.jar (all-in-one jar)

Examples

To run Web Applications the user would need these jars in the classpath

  1. glassfish-embedded-nucleus.jar
  2. glassfish-embedded-web.jar

To run Ejb Applications the user would need these jars in the classpath

  1. glassfish-embedded-nucleus.jar
  2. glassfish-embedded-ejb.jar

To run an absolute bare bones EJB tier for Local EJB: support

  1. glassfish-embedded-api.jar
  2. glassfish-embedded-ejb.jar

The IPS Components must be delivered as flattened jar files, one per component (currently web, ejb, scripting, jpa and jdbc)

4.11. Security Impact:

No known impact

4.12. Compatibility Impact

N/A – New Feature

4.13. Dependencies:

None

5. Reference Documents:

Kohsuke's Blog
ServerSide Blog
java.net Embeddable GlassFish project site
javadoc for the Embedded API
V3 Overview
Arun Gupta's Embedded Sample Blog
Forum Thread on this Document
Packaging Specifications - Version 5 used for this document

6. Schedule:

August 8 2008 - Feature Complete
August 15 2008 - Final Prelude Release

6.1. Projected Availability:

Prelude Version: August 15, 2008


Attachments:
model.png (image/png)
webdeployer.jpg (image/pjpeg)