Revision as of 04:09, 23 April 2010

Artifacts

Virgo supports the deployment of various types of artifacts. Standard artifact types are:

• bundle - an OSGi bundle.
• configuration - a properties file with name of the form <pid>.properties which when deployed produces a Configuration Admin dictionary with PID <pid>.
• plan - an XML file which refers to arbitrary other artifacts in the Virgo repository. Plans may be scoped or unscoped, as described below, and atomic or non-atomic in terms of whether the lifecycle of the plan is tied to the lifecycle of the plan's artifacts.
• PAR - a Plan ARchive which contains a collection of artifacts and is equivalent to a scoped, atomic plan referencing those artifacts (except the artifacts need not be present in the Virgo repository).

In addition, it is possible to add user defined artifact types.

Kernel

The Virgo kernel is the core runtime which may be used on its own or to deploy one or more server types and applications for those server types. The kernel houses the deployment pipeline, described below, as well as support for common artifact types (bundle, configuration, plan, and PAR), regions, scoping, and other core Virgo features.

Currently, for example, the Virgo web server packaging build uses the kernel to deploy a web server plan which includes the Gemini web container and the Virgo web bundle (which integrates Gemini web into Virgo).

The startup scripts launch the kernel which then installs, and optionally starts, each of a configurable collection of bundles to provide kernel function. The kernel bundles are located in lib/kernel and are referenced by the launcher.bundles property in the configuration file lib/org.eclipse.virgo.kernel.launch.properties. This property specifies a list of bundles, which is transitively closed with respect to dependencies, and specifies which of these bundles are started after all the bundles in the list are installed.

Regions

The kernel uses the nested framework support in Equinox to isolate the kernel from application artifacts, including artifacts which implement servers. The Equinox support is being standardised, with some changes, in OSGi. As shown in the figure below, the kernel starts in a normal OSGi framework, known as the kernel region, and then creates a nested framework known as the user region.

Region support was added to enable applications to run with a different version of Spring than that used by the kernel. A minimal set of Spring bundles is installed into the kernel region with very few optional dependencies which keeps the kernel footprint and startup time low. In principle, Spring could be entirely removed from the kernel region if the kernel was modified not to depend on Spring (most of these dependencies are because the kernel uses Spring DM to publish and find kernel services).

Certain packages and services are imported from the kernel region into the user region and certain services, but no packages, are exported from the user region to the kernel region. This isolates the kernel region from interference due to types and package wirings in the user region. The configuration file config/org.eclipse.virgo.kernel.userregion.properties controls the importing of packages and services into and the exporting of services out of the user region.

The content of the kernel region is controlled by the configuration file lib/org.eclipse.virgo.kernel.launch.properties.

So, apart from the basic principle that no packages are exported from the user region to the kernel region, there is a lot of flexibility for changing the contents of both kernel and user regions and for specifying which packages and services are shared between the regions.

In future, Virgo could be extended to support multiple user regions in order to isolate applications from each other.

Scoping

Virgo adds the concept of scoping to OSGi. The main use case for scoping is where a group of bundles form an application which needs to avoid clashing with other applications and which needs reliable behaviour when it calls third party bundles which use thread context class loading. Clashes can occur because of bundles, packages, or services conflicting in some way.

Metadata Rewriting

Virgo rewrites the metadata of bundles in a scope to prefix the bundle symbolic names with a scope-specific prefix and to add a mandatory matching attribute, with a scope-specific value, to packages exported by bundles in the scope.

Virgo also uses the standard OSGi service registry hooks to limit the visibility of services published by bundles in a scope.

However, a bundle in a scope may access bundles, packages, and services not provided in the scope but which are available outside the scope, that is from unscoped bundles. So a scope acts similarly to a programming language scope such as Java's curly braces:

int x;
// b is not visible here
{
    int b;
    // both b and x are visible here
}

Synthetic Context Generation

To ensure reliable thread context class loading when third party bundles are called from a scope, Virgo generates a synthetic context bundle in the scope. The class loader of the synthetic context bundle is used as the thread context class loader when bundles in the scope make calls outside the scope. The synthetic bundle imports each of the other bundles in the scope using the Virgo import-bundle header. This is semantically equivalent to importing all the exported packages of the other bundles in the scope. So to make a package of a scoped application available for thread context class loading, it is simply necessary to export the package.

Example of Scoping

The figure below shows a scoped plan referring to two bundles A and B being deployed. The result is a scope containing the bundles A and B as well as the synthetic context bundle. Note that bundles inside the scope can access bundles, such as X, outside the scope. Also, bundles outside the scope, such as Y, cannot access bundles inside the scope.

Pipeline

Artifacts are deployed into Virgo using a deployment pipeline consisting of several pipeline stages some of which have pipelines nested inside them as shown in the figure below.

The pipeline, and each pipeline stage, accepts a tree of install artifacts as input and outputs a possibly modified tree. Many of the interesting modifications to the tree are performed by the transform stage which uses the whiteboard pattern to drive all services of a Transformer type in order of service ranking. For example, a synthetic context bundle is added as a node of a scoped plan by xxx. A number of standard Transformer services are defined in the Spring context file deployer-context.xml in the kernel's deployer bundle.

There are two approaches to handling exceptions thrown by a pipeline stage. In general, unexpected exceptions are allowed to percolate upward and result in diagnostics and a failed deployment. However, certain expected exceptions, such as failure to resolve the dependencies of the install artifact tree, need to be handled more gracefully. In these cases, a compensating pipeline stage is defined which drives a compensation stage if an exception is thrown. failInstall and failResolve in the figure above are examples of compensation stages.

work in progress...

Repositories

work in progress