GlassFish Wiki: Gfv3DeploymentOnePager

Not logged in|Log in

Glassfish Wiki » Gfv3DeploymentOnePager

By any use of this Wiki, you acknowledge and agree to be bound by this website's Terms of Use.

Your trail: GlassFishWiki > Products > Frameworks

Home Index Changes Prefs Log in »

Deployment One Pager

Deployment

1. Introduction

1.1. Project/Component Working Name:

Deployment

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

Tim Quinn (timothy.quinn@sun.com)
Hong Zhang (hong.zhang@sun.com)

1.3. Date of This Document:

Initial Draft: 12/15/2008
Second draft (incorporated comments from user/forum): 01/15/2009

2. Project Summary

2.1. Project Description:

JavaEE 6 compliance
General deployment functionality
Extensibility interfaces relevant to deployment
Application management (app config customization)

2.2. Risks and Assumptions:

Note any risks, and assumptions that must be considered along with the proposal. Include technical risks.

3. Problem Summary

3.1. Problem Area:

JavaEE 6 compliance

We need to be JavaEE 6 compliant, implement all the requirements from JavaEE 6 specifications.

General deployment functionality

We need to continue providing the equivalent functionality as in v2 with the new modularized code base.

Extensibility I/Fs

Container developers must be able to extend GlassFish by building new container types. These deployment-related interfaces define a service provider interface (SPI) which container developers implement so as to plug into the GlassFish deployment infrastructure that is shared by all container types.

Application management (note - not for v3 EA/JavaOne release)

Application developers and administrators want to be able to deploy an application, then customize configuration information that is specific to that application type. As an initial example implementation for the web app type, v3 allows users to customize the env entry values and context param values for a web app after deployment. Specifically, users can

modify the values of existing env entries or context param settings,
add new env entries or context params that are not present in the application's descriptor, and
can suppress the effect of an env entry or context param that is present in the descriptor.

(This last feature is not truly “deleting” the item from the descriptor, although the net effect is the same.)

3.2. Justification:

JavaEE 6 compliance

Glassfish application server needs to be JavaEE 6 compliant.

General deployment functionality

Carry forward existing v2 functionality.

Extensibility I/Fs

Greatly simplify ability to plug in new container types.

App mgt

Ease-of-use for fine-tuning app configuration after deployment without requiring the user to edit the deployment descriptors, repackage, and redeploy the application.

4. Technical Description:

4.1. Details:

JavaEE 6 compliance

As specified from JavaEE 6 specifications. The relevant specifications are:
Java Platform, Enterprise Edition 6 specification

JavaEE Application Deployment JSR88 specification

Common Annotations for the Java Platform 1.6 Specification

Java Servlet 3.0 Specification

Enterprise JavaBeans 3.1 Specification

JavaEE Connector Architecture 1.6 Specification

General deployment functionality

In the area of providing equivalent deployment functionality as in v2:

Various JavaEE module types (connector module, web module, ejb module, application client module and enterprise application) can be deployed through these mechanisms as described in v2. In v3 prelude, only web module was supported.

Archive deployment: deploy the application as an archive.
Directory deployment: deploy the application in a directory format.
Dynamic Reloading: redeploy the application by creating/modifying a special .reload file in the applications repository.
Automatic deployment: drop the application archive in the autodeploy directory.
Using a deployment plan: deploy a portable archive along with a deployment plan containing application server specific deployment descriptors.
JSR88 deployment (this was not supported in v3 preclude).

Please refer to v2 doc for the details of the above mechanisms. One exception here, the application's repository for standalone modules has moved from $DOMAIN_DIR/applications/j2ee-modules to $DOMAIN_DIR/applications. And the application's repository for enterprise applications has moved from $DOMAIN_DIR/applications/j2ee-applications to $DOMAIN_DIR/applications. So in the dynamic application reloading case, the path of the .reload file needs to change accordingly.

We continue supporting the same set of operations to manipulate the application lifecycle as in v2: deploy/redeploy, undeploy, enable, disable. These are the limitations/additions in this release:

We supported the majority of the v2 deployment options in this release. Options that are not yet supported ("--verify" and "--availabilityenabled") are implemented as no-op.
A new deployment option "--type" is added in this release to indicate the archive type. Right now the only possible value for this option is "osgi".
A new redeploy command is added which is equivalent to deploy --force=true for a previously-deployed application. Redeploy supports the same options and argument as the deploy command. The redeploy command's "path" option is optional for directory redeployment. The detail of the redeploy command will be documented in the man page.

Extensibility I/Fs

The GF v3 prelude Add-on Component Development Guide documentation

describes the interfaces in detail. They are summarized briefly below for convenience. There are no changes to these interface at this point, but we expect these interfaces to evolve through the engineering process of this release.

Once the container developer implements these interfaces, he or she packages the Sniffer into one OSGi module and the other classes into one or more other OSGi modules. (The deployment infrastructure must be able to ask each sniffer implementation if it handles an application being deployed. The other implementation classes for the container type are not needed unless an application of that type has been deployed to the server. The sniffer should be packaged separately from the other classes so GlassFish can load it without loading the other classes related to the same container type.)

public interface org.glassfish.api.container.Container {
    public Class<? extends Deployer> getDeployer();
    public String getName();
}

public interface org.glassfish.api.deployment.ApplicationContainer<T> {
    public T getDescriptor();
    public boolean start(ApplicationContext startupContext) throws Exception;
    public boolean stop(ApplicationContext stopContext);
    public boolean suspend();
    public boolean resume() throws Exception;
    public ClassLoader getClassLoader();
}

public interface org.glassfish.api.container.Sniffer {
    public Class<? extends Annocation>[] getAnnotationTypes();
    public String[] getContainersNames();
    public Map<String,String> getDeploymentConfigurations(ReadableArchive archive);
    public String getModuleType();
    public String[] getURLPatterns();
    public boolean handles(ReadableArchive archive, ClassLoader loader) throws IOException;
    public boolean isUserVisible();
    public Module[] setup(String containerHome, Logger logger);
    public void tearDown();
}

public interface org.glassfish.api.deployment.Deployer<T extends Container, U extends ApplicationContainer> {
    public MetaData getMetaData();
    public <V> V loadMetaData(Class<V> type, DeploymentContext context);
    public boolean prepare(DeploymentContext context);
    public U load(T container, DeploymentContext context);
    public void unload(U appContainer, DeploymentContext context);
    public void clean(DeploymentContext context);
}

public interface org.glassfish.api.deployment.archive.ReadableArchive extends Archive {

    public InputStream getEntry(String name) throws IOException;
    public boolean exists(String name) throws IOException;
    public long getEntrySize(String name);
    public void open(URI uri) throws IOException;
    public ReadableArchive getSubArchive(String name) throws IOException;
    public ReadableArchive getParentArchive();
    public void setParentArchive(ReadableArchive parentArchive);
    public boolean exists();
    public boolean delete();
    public boolean renameTo(String name);
}

public interface org.glassfish.api.deployment.archive.WritableArchive extends Archive {
    public void create(URI uri) throws IOException;
    public void closeEntry(WritableArchive subArchive) throws IOException;
    public OutputStream putNextEntry(String name) throws java.io.IOException;
    public void closeEntry() throws IOException;
    public WritableArchive createSubArchive(String name) throws IOException;
}

public interface org.glassfish.api.deployment.archive.ArchiveHandler {
    public String getArchiveType();
    public String getDefaultApplicationName(ReadableArchive archive);
    public boolean handles(ReadableArchive archive) throws IOException;
    public ClassLoader getClassLoader(ClassLoader parent, ReadableArchive archive);
    public void expand(ReadableArchive source, WritableArchive target) throws IOException;
    public Manifest getManifest(ReadableArchive archive) throws IOException;
}

Application Management (not for EA/JavaOne release)

Container developers can choose what, if any, configuration to expose for post-deployment customization. They make this customization possible by completing the following tasks:

(Note, for completeness, we describe all the aspects of this feature in the following section. The work from the GlassFish side will be shared by different teams: admin, deployment, GUI, and the container teams. The implementation of web module configuration described below is the initial delivery; enhancements and further customizations can be added later.)

1. Declare a Configured interface, representing the module type's customizable configuration, that extends ApplicationConfig and is particular to the container type. For example, here is the definition for the initial web component customization support:

@Configured
public interface WebModuleConfig extends ApplicationConfig ... {
...
   @Element
   public List<EnvEntry> getEnvEntry();

   @Element
   public List<ContextParam> getContextParam();
...
}

The container developer also implements any lower-level interfaces referenced from this interface (EnvEntry and ContextParam in this example).

By defining these interfaces the container developer implicitly extends the domain.xml format as well. Specifically, a container-provided interface which extends ApplicationConfig corresponds to a new child element of <engine> (the <engine> element represents one component of an application that runs inside a single container type). For example, the web container implementation introduces <web-module-config> as a new optional child of <engine> for those <engine> elements that correspond to web components. Because the definitions of and inheritance among the @Configured interfaces determines the domain.xml format the container developer does not need to do any additional work to expand the domain.xml format to allow for customizable configuration.

Note, in v3 prelude the parent node was <application>element. It was changed to <engine> element in this release so it would work for both the standalone and embedded (inside an enterprise application) cases.

Here is what a fragment of domain.xml might look like after a user had customized a web module's configuration:

<application ...>
         <module name="foo">
             <engine sniffer="web">
                 <web-module-config>
                     <env-entry>
                         <env-entry-name>SomeName</env-entry-name>
                         <env-entry-type>java.lang.Integer</env-entry-type>
                         <env-entry-value>7</env-entry-value>
                     </env-entry>
                       ...
                     <context-param>
                         <param-name>greeting</param-name>
                         <param-value>Hello</param-value>
                     </context-param>
                       ...
                 </web-module-config>
             </engine>
         </module>
     </application>

2. Implement the ApplicationContainer interface's start method so that, as part of starting the module, the method retrieves the module-type-specific customization information and uses it to prepare the execution environment for the module. The com.sun.enterprise.web.WebApplication class (which implements ApplicationContainer) illustrates this for the web module type.

3. If desired, create AMX interfaces specific to the new module type with convenience methods for accessing the customizable configuration for the module type. (The com.sun.appserv.management.config.WebModuleConfigConfig interface illustrates this for the web module type.) Defining these interfaces simplifies writing the GUI plug-in. (Note - recent and pending changes to AMX which Lloyd is considering might do away with the specific interfaces.)

4. Implement a GUI plug-in which developers and administrators can use to customize the configuration that is exposed for the given container type. The plug-in uses AMX (either the generic access methods common to all AMX entities or the module-specific AMX interfaces defined above) to retrieve and assign values for the customizable configuration for a given module type. Ideally the plug-in should reside in its own OSGi module or one with few other classes, since the GUI will load and use the plug-in module and we want to keep the admin console footprint as small as possible. (This goal conflicts somewhat with the goal of improving start-up performance by minimizing the total number of modules GlassFish must load and one might need to be traded-off in favor of the other.)

For example, the plug-in for customizing web apps will expose the env entries and context params from the application's descriptor, augmented by the contents of the default-web.xml and the context.xml files. The display to the user will show the value for each env-entry and context-param as the web container would compute it as if it were preparing to start the app. The user will be able to modify the value of an existing item, add a new env-entry or context-param, or mark an existing env-entry or context-param to be ignored (suppressed).

5. Implement commands which developers and administrators can use to customize the configuration. The Add-on Component Development Guide explains this process in detail.

These commands as proposed for this release are listed below and follow the customization guidelines listed in the add-on documentation.

A container offering application configuration will likely provide commands to set, delete, and list the customizable items for that container's module type. Note that the set- and delete-style commands should require the user to identify the configured item uniquely using

the application name and, for submodules within an EAR, the module name (together these compose the operand), and
any required container-specific information.

For example, the web-container-specific information is

the config-type, and
the name of the configured item.

Note that the --config-type option specifies which variety of configuration information is of interest, while the --type option specifies, for creating or setting env-entry items, what env-entry-type setting should be assigned.

All customizations apply to the application. The administrator can customize differently for different targets by using placeholders.

set-web-env-entry --name=name --value=value --type=env-entry-type
  [--description=description] [--ignoreDescriptorItem=true/false] application-name[/module-name]

list-web-env-entry [--name=name] application-name[/module-name]

unset-web-env-entry --name=name application-name[/module-name]

set-web-context-param --name=name --value=value 
  [--description=description] [--ignoreDescriptorItem=true/false] application-name[/module-name]

list-web-context-param [--name=name] application-name[/module-name]

unset-web-context-param --name=name application-name[/module-name]

Note that the design of the commands is generally up to the container developer; the ones described here are our proposal for the initial commands related to web app customization. Even so, most if not all such commands for any container should let the user set overriding values, unset them (that is, remove the customization for a particular element), and list them.

The user specifies the --ignoreDescriptorItem option on the set commands to suppress the effect of the same-named item from the "effective" descriptor. In the web case these values are composed from the module's descriptor, the default-web.xml settings, and the context.xml settings.

We propose separate, component-provided commands rather than generic, GlassFish-implemented commands. Doing so leverages the existing, documented mechanism for extending the command set while no such mechanism exists - yet - for extending existing commands with expanded syntax. At least as importantly, it also allows more user-friendly, container-specific command syntax. In particular, the option names themselves refer to specific aspects of the web module customization. This is more convenient for the user as it collapses the actual implementation hierarchy in the configuration implementation.

Another alternative we considered was a single set of generic, GlassFish-provided commands that would apply to all module customization types. One difficulty with this approach is that the commands would not know about the details of any given container type's configuration structure. This would require a generic way for command users to identify a particular configurable item. We concluded this was user-unfriendly enough that adding new generic commands would not be worthwhile.

Note that users can use the existing dotted notation and/or the proposed path notation with the generic set and list commands to manage post-deployment customization.

The v3 prelude release includes much of the framework for this feature although that release did not expose this feature to the end-user. The GUI and the CLI commands for customizing web applications will be added in this release (post-JavaOne).

4.2. Bug/RFE Number(s):

Extensibility

Feature Issue 4103

App mgt

Feature Issue 4105

4.3. In Scope:

as described above

4.4. Out of Scope:

4.5. Interfaces:

4.5.1 Exported Interfaces

General deployment functionality

Changes from v3 prelude:

Interface: All JavaEE module types (connector module, web module, ejb module, application client module and enterprise application) are supported.
Stability: stable
Former Stability (if changing):

Interface: JSR88 deployment mechanism is now available.
Stability: stable
Former Stability (if changing):

Interface: More options of admin cli deploy command are supported to match v2 functionality: option property.
Stability: stable
Former Stability (if changing):

Changes from v2:

Interface: In admin cli deploy command "asadmin deploy", the default value of the "force" option has changed from "true" to "false". The change for the default value of the "force" option was made to prevent user from overwriting the original application accidentally. A new option "type" is also added to support osgi archive type.
Stability: evolving
Former Stability (if changing):

Interface A new admin cli command "asadmin redeploy" has been added.
Stability: evolving
Former Stability (if changing):

Extensibility

Disclose all interfaces that this project exports.

Interface: extensibility-related Java interfaces (Sniffer, etc.)
Stability: evolving (at this point)
Former Stability (if changing):
Comments: The Java interfaces and the methods defined on them (see the Technical Description) are, at this point, evolving (toward the “stable” end of “evolving”). During the course of v3 prelude engineering these interfaces did change as we understood subtle aspects of extensibility and they might continue to do so through engineering process of this release.

Application Management

For the framework affecting all post-deployment customization, regardless of app type:

Interface: Application and ApplicationConfig @Configured Java interfaces
Stability: evolving
Former Stability (if changing):
Comments: These interfaces are probably rather solid at this point but they may change as we go forward. Application is defined to permit optional ApplicationConfig children and also provides a “duck-typed” method for retrieiving ApplicationConfig children of a given type as a convenience to the ApplicationContainer implementation that needs access to customization data relevant to its container type. These do not depend on the details of container-specific subinterfaces of ApplicationConfig. But we may discover useful enhancements to either or both of these interfaces during engineering work.

For the initial implementation of web app customization:

Interface: Java interfaces (WebModuleConfig, EnvEntry, ContextParam)
Stability: evolving
Former Stability (if changing):
Comments:

Interface: specific items subject to customization
Stability: evolving
Former Stability (if changing):
Comments: Might expand given time and people (and demand)

Interface: customization CLI commands (set/delete/list-web-config)
Stability: evolving
Former Stability (if changing):
Comments: If and when new config items become customizable the commands will evolve to accept the new config-type as well as to allow the user to specify any other information that is specific to the new config items not already handled by existing options.

Interface: GUI plug-in
Stability: evolving
Former Stability (if changing):
Comments:

Interface: domain.xml
Stability: evolving
Former Stability (if changing):
Comments: While we discourage users from directly accessing it, domain.xml is in fact an exported interface. The app management feature evolves domain.xml by potentially allowing containers to add container-specific customization data as child elements below <engine>. The specific changes which support web app customization indeed represent evolution in the domain.xml interface.

4.5.2 Imported interfaces

General deployment functionality

none

Extensibility

none

Application Management

Interface: hk2 @Configured framework
Stability: evolving
Exporting Project: Name, Specification or other Link.
Comments:

4.5.3 Other interfaces (Optional)

General deployment functionality

There is no change from v3 prelude.

Change from v2: The internal applications repository layout: the applications repository for standalone module has moved from $DOMAIN_DIR/applications/j2ee-modules to $DOMAIN_DIR/applications. The internal applications repository layout: the applications repository for enterprise application has moved from $DOMAIN_DIR/applications/j2ee-applications to $DOMAIN_DIR/applications. This change was made to simplify the implementation, avoid unnecessary code branching. Also users will have one uniform place to look for all types of application regardless of the module type.
Stability: evolving
The domain.xml: we use a generic "application" element to represent any JavaEE module type.
Stability: evovling

4.6. Doc Impact:

General deployment functionality

Deployment guide, Admin reference, CLI man page

Extensibility

The referenced v3 prelude doc already describes many aspects of extensibility. We need to review it (again) for completeness and accuracy especially if the Java interfaces change further.

Application Management

The add-on development guide should be enhanced to describe the process for supporting config customization.

The admin content should be enhanced to describe the ability to use the GUI or the CLI commands to manage application customization.

4.7. Admin/Config Impact:

General deployment functionality

New "application" element in the domain.xml subsumes the role of the “web-module”, "ejb-module", "connector-module", "appclient-module", "j2ee-application" elements.

Application Management

See discussion of web customization GUI and commands.

4.8. HA Impact:

None

4.9. I18N/L10N Impact:

Application Management

Web customization GUI will be subject to localization.

4.10. Packaging & Delivery:

No impact.

4.11. Security Impact:

None

4.12. Compatibility Impact

General deployment functionality

There are no incompatible changes from v3 prelude.

Changes from v2: The applications repository layout change might impact upgrade depending on the upgrade mechanism we choose.
User scripts that currently leverage the dynamic reload functionality will need to be corrected to reflect the new repository layout.
User scripts that depend on the default behavior of the v2 deploy subcommand may need to be corrected. For example, to adapt to the new default value of the "force" option.

Application Management

Upgrade from prelude to this release is not affected; upgrade beyond should be minimal because, even if the customizable items expands, the relevant elements in domain.xml are optional, and the corresponding changes to the @Configure interfaces will be backward compatible.