GlassFish V3 Extensibility One Pager

[

|(TableOfContentstitle='')]

1. Introduction

1.1. Project/Component Working Name:

Pluggability and Extensibility.

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

Sreenivas Munnangi, sreenivas.munnangi@sun.com
Nandini Ektare (ne110415@dev.java.net)

1.3. Date of This Document:

12/11/08: first version
02/05/09: modified based on Jerome's feedabck

2. Project Summary

2.1. Project Description:

Provide for extending the application server functionality by enabling the integration of OSGi modules, JARs, and v2 like add-ons. Enable distribution of add-ons to given targets similar to Java EE application. Integration with Update Center 2.0 for managing IPS repository contents.

2.2. Risks and Assumptions:

The add-on dependencies are assumed to be resolved by IPS infrastructure.

Depends on deployment and synchronization infrastructure for deployment of add-on and synchronization to remote instances respectively.

Usability issues for which we have to discuss with individual providers and determine the ease of use requirements.

Rollback will be confined to what the deployment infrastructure provides.

While extensibility remains at the top of the teams priorities, its implementation is determined the availability of resources and changing priorities. The complete implementaion may be delivered in phases depending on priority of each release.

3. Problem Summary

3.1. Problem Area:

The extensibility infrastructure provides the ability to extend application server functionality through add-ons. The add-on could be a combination of OSGi module, v2 like add-on, Java EE application or a simple jar.

One of the severe limitations of add-ons in previous version is that the add-ons were confined to DAS and could not be distributed to clusters/stand-alone instances. We would like to enhance the utility of add-ons in this release by allowing for deployment to clusters and instances in addition to DAS. At the same time provide for operations similar to java ee applications, like deployment to a given target, along with scalability and high availability.

3.2. Justification:

Limited v2 functionality of add-on is enhanced by enabling the deployment of add-ons to clusters/instances along with scalability and availability.

4. Technical Description:

Continuing on the prelude infrastructure, provide for extending the application server functionality by enabling the integration of OSGi modules, and v2 like add-ons.

Provide infrastructure for MDS (Module Distribution System) which enables downloading the add-ons from a given Update Center 2.0 repository and distribute it to specified targets like clusters and stand-alone instances. Also allows for life-cycle operations like install/uninstall, and enable/disable of the add-ons on specified targets.

Subsequently, add-on means any of the type mentioned above including OSGi modules, v2 like add-ons, Java EE Application, and JAR archive. Any of these types could be distributed through Update Center repository as an add-on.

4.1. Details:

One can create add-on using the pluggability API (Configuration, CLI, Monitoring, Deployment, GUI) and proposed extensibility API.

Configuration pluggability will ensure that a new module's(contianer's) minimum/default configuration is picked up the first time the module(container) is loaded and this configuration is merged into the domain.xml (refer to the Administration Infrastructure One Pager requirement

The extensibility infrastructure essentially provides for handling a composite application called add-on similar to ear which can hold both Java EE and non Java EE modules. Java EE modules include war, ear, jar(acc), jar(ejb) and rar. Non Java EE types include OSGi bundle, and Java Archive (JAR). In addition, the extensibility infrastructure enables running of user defined functionality called AdminAction while deploying the add-on contents in defined sequence. The AdminAction interface defines the methods which need to be implemented by the add-on. V3 infrastructure can inject CommandRunner and other pertinent resources while invoking user defined AdminAction. User defined functions typically include various asadmin operations, modifying domain.xml, copying ant setup.xml, running ant script, updating classpath, etc. similar to v2. Refer to interfaces section for details.

AdminAction assumes familiarity with several exposed API and caters to complex situations. For users who want to develop simple add-ons who are usually familiar with asadmin commands, we may provide something similar to asadmin script with place holders for certain variables like target which will be token replaced by extensibility infrastructure at the time of deployment. This needs to be understood better and seek asarch recommendations.

It is proposed to use the existing deployment infrastructure for deployment and undeployment of add-ons. It makes lot of sense to use existing deployment infrastructure as it has support for persisting applications, running cli commands for applications, synchronization, scalaibility and availability. The deplyoment infrastructure needs to be enhanced for add-on container to invoke deployment API from within add-on container, for ex. sniffer support for embedded modules. Similar to other containers, add-on container will support the deployment of add-ons and invoke user defined AdminAction(s) as part of deployment.

Once the add-on is created using pluggability API and extensibility API, it can be made available through Update Center repository using IPS. The client application server image can then download the add-on package from UC repository. The downloaded package is just a payload whose contents need to be understood before acting on them. For example, the payload may contain any and/or a combination of the module types Java EE Application, OSGi bundle, JAR, v2 like add-on.

The add-on descriptor (similar to Java EE application.xml) describes the contents and the order in which they have to be deployed/installed. For ex. the module element contains the module id for osgi bundle, j2ee application, jar, and user defined AdminAction. Based on the order of definition, each of the modules is deployed using respective sniffer/container pair. There is no common classloader at the level of add-on. When it is osgi, the bundle is copied to glassfish/modules using OSGi sniffer, if it is jar then it is copied to glassfish/lib, j2ee app is deployed using corresponding sniffer, if defined, AdminAction is invoked. It is expected that the admin action is deployed mostly as osgi bundles before they are invoked. The developer can use the above combination to acheive a custom behavior.

While the deployment happens in the order the Modules and AdminActions are defined, the loading is performed by the respective sniffer/container.

The deployment to cluster depends on how clustering and synchronization evolve for v3. One thought is to transfer the bits and perform complete deployment (including generation) on each remote instance to avoid sync. issues. Another thought is similar to what is being done in v2. First the deployment is performed on DAS and the corresponding remote instances are notified of the config change. The remote instance then initiates synchronization with the DAS and receives the add-on artifacts and loaded. If non-das is true then the AdminAction is invoked on the non-das remote instance.

Picture below shows high level design of v3 Extensibility.

Cannot resolve external resource into attachment.

Following section discuss specific design details for each of the module types handled by add-on container.

4.1.1. Add-on module:

Based on the discussion so far, it would have been obvious that the add-on type is a combination of above module types with customizations. The add-on module will have descriptor which lists the contents of add-on and the order in which they have to be processed. The list can also include AdminAction(s). The add-on module is persisted in domain.xml as a composite-application.

Pl. see interfaces section for proposed add-on descriptor and composite-application details.

To check for any updates in the Update Center 2.0 Repository, it should be possible to determine the current versions based on the info in domain.xml. To store the add-on module info. and the corresponding IPS packgae (name, version, state), we plan to use composite-application element as described in interfaces scetion.

As stated earlier, the add-on may have a combination of OSGi bundle, Java EE Application, JAR, and AdminAction. Following sections describe each of these types in detail.

4.1.2. OSGi Bundle:

Let us assume that MDS (Module Distribution System which is a client of Extensibility API) detects a new IPS package whose payload is an OSGi bundle which does not exist in the application server. The IPS package is first downloaded by MDS to <applications>/my_osgi_bundle.jar. Then the OSGi bundle is deployed (on DAS) to the specified target using deployment API. The OSGi container will sniff the OSGi bundle and copies the OSGi bundle jar to the <glassfish>/modules directory. This is the default action for OSGI bundle.

If the target is a cluster the deployment is done similar to Java EE application as described above.

<!ELEMENT osgi-module (description?, property*)>

<!ATTLIST osgi-module 
    name CDATA #REQUIRED
    location CDATA #REQUIRED
    object-type %object-type; "user"
    enabled %boolean; "true">

It is possible to perform customization by implementing AdminAction interface provided by extensibility API. If the add-on descriptor contains the AdminAction then the add-on container invokes the AdminAction as specified in the descriptor.

When MDS is asked to remove the OSGi package, deplyment api (similar to asadmin undeploy --target) is invoked, the add-on container performs the steps in reverse order as defined in the add-on descriptor.

It is possible to enable or disable the module during lifecycle similar to Java EE application. Whenever asadmin enable/disable command is issued then the add-on container will invoke the corresponding implementaion provided by the module for enable/disable in its AdminAction. If it has multiple AdminActions then all of them will be accessed and whichever has corresponding method will be invoked.

4.1.3. Java Archive JAR:

Java Archive will be handled similar to OSGi bundle as described in 4.1.2 except that the jar is copied to <glassfish>/lib instead of <glassfish>/modules.

<!ELEMENT jar-module (description?, property*)>

<!ATTLIST jar-module 
    name CDATA #REQUIRED
    location CDATA #REQUIRED
    object-type %object-type; "user"
    enabled %boolean; "true">

4.1.4. Java EE Application (WAR, EAR, RAR, EJB Module, ACC Module):

If the module is one of the standard Java EE types then the module is deployed in the usual manner. If it is part of add-on then the add-on descriptor is consulted to verify the processing order and to invoke any AdminAction. Add-on container needs a way to access deployment API internally to facilitate this. The property element of the module is used to store the corresponding IPS package info otherwise we do not know whether it is a part of IPS package. This package info is critical for determining updates and for cleanup.

It is possible for the add-on to get into an inconsistent state either because of partial deployment or because some one manually undeployed the contents of add-on. Extensibility infrastructure needs some support from Java EE containers to handle this situation by not allowing undeployment based on the prersence of certain add-on property. This allows for a proper cleanup by the extensibility infrastructure.

For each of the Java EE applications, the corresponding sniffer/container pair are invoked.

4.1.5. v2 add-on:

Though v2 compatability is important, considering the lack of similar infrastructure in v3, we need to assess and determine how best to address this. For ex. in v3 we do not have support for lifecycle modules, add-on infrastructure similar to v2.

However, we can address some of the issues in v3 as given below.

• Lifecycle module in v2: We can implement a lifecycle container similar to v2 by exposing an interface and invoking the lifecycle implementation based on certain events like startup, shutdown.
• In v2 we allowed the modification of classpath which can be done in v3 by modifying classpath-suffix thru config API.
• Expose v2 interfaces for Installer and Configurator.

4.2. Bug/RFE Number(s):

List any Bug(s)/RFE(s) which will be addressed by this proposed change.

Provide links to the Issue tracker Bug(s)/RFE(s)where possible

4.3. In Scope:

Extensibility API and infrastructure for Module Distribution System (MDS).

4.4. Out of Scope:

Implementation details of MDS.
API to provide for high availability such as in-memory replication, HADB.

4.5. Interfaces:

Interfaces are a major part of Architectural review.
Commands, Files, Directory Layout, Ports, DTD/Schema, admin tools,
config files, APIs, CLIs, and almost anything that is externally
observable is an interface. In 1-Pager it is necessary to document
any interface that can be used by external projects and products.
Documented public interfaces must be assigned a stability level.
Some commonly used Stability levels in prior projects are:

<pre>
Stable : Widely used public interface. changed very rarely.
Standard : Defined by a standards body (e.g: JDBCv3). Rare but
incompatible clarifications and changes could occur
in a standard. Product will specify version of std
supported. J2SE, J2EE and WS* are classified
as Standard.
Evolving : Subject to carefully controlled but possibly
incompatible change at a major or minor release.
When a change is made all efforts will be made
to address incompatiblity and migration. All
incompatibilities will need to be reviewed
and approved by as-ccc@sun.com.
Unstable : Early access, subject to unrestricted degree of
change. A few App Server interfaces are classified
as Unstable. Docs must call out exported unstable
interfaces. Be wary of importing Unstable interfaces.
External : Defined external to GlassFish Application Server,
but not by a Standards body. Suitable for describing
other freeware, open source interfaces.
http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/ describes the permitted interface taxonomy.
</pre>

4.5.1 Exported Interfaces

Disclose all interfaces that this project exports.

• Interface: add-on container similar to jruby container
• Stability:
• Former Stability (if changing):
• Comments:

• Interface: add-on descriptor similar to ear descriptor
• Stability:
• Former Stability (if changing):
• Comments:

The add-on descriptor (similar to Java EE application.xml) describes the contents and the order in which they have to be deployed/installed. For ex. the module element contains the module id for osgi bundle, j2ee application, jar, and user defined AdminAction. Based on the order of definition, each of the modules is deployed using respective sniffer/container pair. There is no common classloader at the level of add-on. When it is osgi, the bundle is copied to glassfish/modules using OSGi sniffer, if it is jar then it is copied to glassfish/lib, j2ee app is deployed using corresponding sniffer, if defined, AdminAction is invoked. The developer can use a specific combination to acheive a custom behavior.

<!ENTITY % boolean "(true | false)">

<!ELEMENT add-on    (modules, property*)>
<!ATTLIST add-on    name CDATA #REQUIRED
                    version CDATA #REQUIRED
                    description CDATA #IMPLIED>

<!ELEMENT modules   ((module | admin-action)*)>

<!ELEMENT module    (#PCDATA)>
<!ATTLIST module    name CDATA #REQUIRED>

<!ELEMENT admin-action      (#PCDATA)>
<!ATTLIST admin-action      name CDATA #REQUIRED
                    non-das %boolean; "false">

<!ELEMENT property (description?)>

• Interface: AdminAction
• Stability:
• Former Stability (if changing):
• Comments:

<!ELEMENT admin-action      (#PCDATA)>
<!ATTLIST admin-action      name CDATA #REQUIRED
                            non-das %boolean; "false">

@Contract
public interface AdminAction { 

    // inject ServerContext sc, CommandRunner cr, 

    public void execute() throws AddonException;

    public void enable() throws AddonException;

    public void disable() throws AddonException;

    public void cleanup() throws AddonException;
}

• Interface: composite-application
• Stability:
• Former Stability (if changing):
• Comments:

Enhance applications element to include osgi-module and jar-module as described above.
Also, in addition to the regular attributes, each of the Java EE application/module will have an additinal attribute to store the composite-application name when they are part of composite-application or add-on. This helps distinguish the applications/modules which are deployed as part of add-on.

<!ELEMENT composite-application    
                    (property*, composite-application-config)>
<!ATTLIST composite-application    
                    name CDATA #REQUIRED
                    version CDATA #REQUIRED
                    description CDATA #IMPLIED
                    location CDATA #REQUIRED
                    object-type %object-type; "user"
                    enabled %boolean; "true"
                    availability-enabled %boolean; "false">
<!ELEMENT property (description?)>
<!ELEMENT composite-application-config (#PCDATA)>

/**
 * Tag interface for composite-application related configuration. 
 */
@Configured
public interface CompositeApplication extends ConfigBeanProxy, Named {
}

• Interface: lifecycle interface (similar to lifecycle module in v2)
• Stability:
• Former Stability (if changing):
• Comments:

Developing lifecycle listeners
Package com.sun.appserv.server API for lifecycle module
create-lifecycle-module

4.5.2 Imported interfaces

Disclose interfaces this project imports.

• Interface: GlassFish v2 add-on interfaces for install, configure and upgrade
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

AddonVersion: AddonVersion object represents the version in terms of major, minor and patch level.
Configurator: Name of an implementation of this interface will be configured in the META-INF/services/com.sun.appserv.addons.Configurator file.
Installer: Name of an implementation of this interface will be put in the META-INF/services/com.sun.appserv.addons.Installer file of the addon installer jar file.

• Interface: GlassFish v3 Pluggability API
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: Handling of new add-on type by deployment
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: IPS API
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: GlassFish v3 Container SPI
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: GlassFish v3 Deployment API
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: Update Center 2.0 API
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

• Interface: AMX API
• Stability:
• Exporting Project: Name, Specification or other Link.
• Comments:

4.5.3 Other interfaces (Optional)

Following are the private interfaces and mentioned here just for reference

• install location of downloaded IPS package
• install location of application server and relative paths for copying OSGi bundle, JAR

4.6. Doc Impact:

List any Documentation (man pages, manuals, service guides...) that will be impacted by this proposal.

4.7. Admin/Config Impact:

• add-on container may have its own config
• applications element need to be modified to add version, state

4.8. HA Impact:

What new requirements does this proposal place on the High Availability or Clustering aspects of the component?

4.9. I18N/L10N Impact:

Does this proposal impact internationalization or localization?

4.10. Packaging & Delivery:

IPS with manifest entries to determine the types of modules conatined in the package. Do we need any other information like order of deploying/loading modules ?

4.11. Security Impact:

How does this proposal interact with security-related APIs or interfaces? Does it rely on any Java policy or platform user/permissions implication? If the feature exposes any new ports, Or any similar communication points which may have security implications, note these here.

4.12. Compatibility Impact

Version v2 add-on may not be supported as is.

4.13. Dependencies:

• Deployment infrastructure
• Pluggability Infrastructure
• Imported interfaces 4.5.2
• Configuration pluggability Administration Infrastructure One Pager requirement

5. Reference Documents:

GlassFish v3 Contianer SPI
GlassFish v3 deployment one pager
GlassFish v3 pluggability one pager
OSGi related enhancements in GlassFish v3.0

6. Schedule:

6.1. Projected Availability:

Dates in appropriate precision (quarters, years)

extensibility_onepager_design.jpg (image/pjpeg)