Deployment

Container Deployment

Deployment is part of the Provisioning system. It is the process of adding a single Resource to a given target container. The Provisioner supports installing shared/unshared resources.

Deployment is not aware of the container's runtime state (i.e. the set of resources that are already available) nor does it add any dependency meta data to the Resource. It is the client's responsibility to make sure that

• The deployed resource is unique in the target container
• The target container already provides the needed dependencies
• Container specific dependency meta data is provided together with the resource
• Interdependent resources are provided in the correct order

Because of these limitations, deployment by itself would not be very useful. It is a low level API that is used by the Provisioning system to install shared/unshared resources in a container agnostic way.

Shared Resources

The notion of shared resources, comes from target containers that provide a common resource location that can be seen by multiple unshared resource. Most obvious, this is the case for Tomcat where resources that contain shared API packages need to go to ${catalina.home}/lib whereas the unshared web applications are isolated from each other. WildFly also has the notion of shared resources. In Karaf every resource is shared.

The Gravia wiki contains a little more background information about class loading in a modular environment and the specifics of shared/unshared resources in Tomcat, WildFly, Karaf.

Here is an example that installs a shared resource from a given inputStream

ResourceIdentity identity = ResourceIdentity.fromString(RESOURCE_A);
ResourceBuilder builder = provisioner.getContentResourceBuilder(identityA, inputStream); 
Resource resource = builder.getResource();

ResourceHandle handle = provisioner.installSharedResource(resource);
try {
    // do stuff
} finally {
    handle.uninstall();
}

For this to work in Tomcat, the dependencies of that resource must already be present in the common ${catalina.home}/lib folder. To work in WildFly, the dependencies must already be present in the modules hierarchy and WildFly proprietary wiring information must be part of the given input stream (e.g. a Dependencies: header in the resource's manifest). To work in Karaf, resource must contain valid OSGi metadata in the manifest.

Here is an example that installs a shared resource from maven coordinates. We assume that this is a 3rd party artefact that does not contain WildFly specific wiring information.

ResourceIdentity identity = ResourceIdentity.fromString("camel.core.shared");
MavenCoordinates mavenid = MavenCoordinates.parse("org.apache.camel:camel-core:jar:2.11.0");
ResourceBuilder builder = provisioner.getMavenResourceBuilder(identity, mavenid);
builder.addIdentityRequirement("javax.api");
builder.addIdentityRequirement("org.slf4j");
Resource resource = builder.getResource();

ResourceHandle handle = provisioner.installSharedResource(resource);
try {
    // do stuff
} finally {
    handle.uninstall();
}

This will work in every container, because the needed dependencies are available and the artefact is an OSGi bundle.

Unshared Resources

An unshared resource is a normal container deployment in a format that the target container supports. For Tomcat this would be a WAR file. For WildFly this would be any JavaEE deployment or any other deployment type for which there is a WildFly subsystem installed. For Karaf this would be a valid OSGi bundle deployment. Again, container specific dependency constraints apply - ordering matters.

Here is an example that installs an unshared resource from a given inputStream

ResourceIdentity identity = ResourceIdentity.fromString(RESOURCE_A);
ResourceBuilder builder = provisioner.getContentResourceBuilder(identityA, inputStream); 
Resource resource = builder.getResource();

ResourceHandle handle = provisioner.installResource(resource);
try {
    // do stuff
} finally {
    handle.uninstall();
}

Similarly this can be done from maven coordinates.

Resource Portability

Shared resources would typically be jars that contain public API. For a shared resource to be portable across all supported target containers, it would need to be an OSGi bundle that also contains WildFly specific dependency definitions.

A portable unshared resource, would be an WAR that contains valid OSGi metadata and WildFly specific dependency definitions.

Any deployable Resource supports multiple ContentCapabilities. The capability attributes can be used to filter the target containers. It is therefore possible to use the same ResourceIdentity with different bytes depending on the target container the resource applies to.