Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current Restore this Version View Page History

« Previous Version 6 Next »

In SCA, applications are packaged in one or more contributions. Contributions can be a variety of formats. Fabric3 supports the following formats and can be extended to support others:

  • JAR archives
  • OSGi bundles
  • WAR archives
  • ZIP archives
  • XML documents 

JAR contributions

Most SCA applications will be packaged as one or more JARs. In addition to including application classes and artifacts, a JAR-based contribution may contain an sca-contribution.xml manifest file in the META-INF directory. This manifest file contains contribution metadata, including a list of deployable composites. Deployable composites are those composites that are contained in the contribution which may be deployed to a domain. A contribution may contain other composites but if they are not marked as deployable, they may not be directly included in the domain (i.e. they may only be used by a deployable composite). An example sca-contribution.xml file is shown below:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" xmlns:sample="urn:tempuri.org">
   <deployable composite="sample:TheComposite"/>
</contribution>

Applications often require third-party libraries. Fabric3 supports two ways of packaging and deploying these libraries: by embedding them in the JAR; and importing them from another contribution. Similar to WARs, Fabric3 allows contribution JARs to bundle third-party libraries by placing their JARs in the META-INF/lib directory of the contribution. Any JAR placed in the META-INF/lib directory will be made available on the contribution classpath.

The Fabric3 Contribution Plugin

For Maven users, Fabric3 includes a contribution plugin that automates the process of embedding third-party libraries in a contribution. This plugin allows projects to specify a set of Maven modules which will be included in the META-INF/lib directory. The plugin automatically calculates and includes transitive dependencies as well. To use the contribution plugin, set the POM packaging element to sca-contribution-jar and add the plugin to the POM plugins section:

<build>
   <plugins>
      <plugin>
         <groupId>org.codehaus.fabric3</groupId>
         <artifactId>fabric3-contribution-plugin</artifactId>
         <extensions>true</extensions>
      </plugin>
   </plugins>
</build>

Contribution Imports and Exports

Embedding artifacts and libraries in the META-INF/lib directory of a contribution is simple but lacks the flexibility required by many applications. For example, several applications may need to share the same WSDL document or library. Fabric3 supports two forms of sharing:

  • XML resource sharing
  • Java package sharing

In both cases, a resource (or set of resources) are exported by one contribution and *imported*by another. Imports and exports are specified in the contribution manifest file.

XML Resource Sharing

XML resources are shared by exporting and importing their qualified name (qname). For example, assume a set of portTypes in a WSDL document need to be shared among several contributions. The contribution manifest file contining the WSDL document will export the document's qname using the <export> element:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <export name={"urn:somenamespace:1.0"/>
</contribution>

Contributions that require access to the portTypes defined in the urn:somenamespace:1.0 namespace may import it using the <import> element in their manifest:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <import name="urn:somenamespace:1.0"/>
</contribution>

When the qname is imported, Fabric3 will ensure the portTypes may be referenced by artifacts such as composite files contained in the importing contribution.

Java Package Sharing

Java resources (i.e. classes) are shared by exporting and importing their packages. Java package sharing in Fabric3 is based on OSGi, so if you are familiar with that technology, you already understand Fabric3's approach and capabilities. Classes contained in Java packages are made available to other contributions using the <export.java> element in the contribution manifest:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <export.java package="com.foo.bar"/>
</contribution>

Exported packages may then be imported using the <import.java> element in the manifest of another contribution:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <import.java package="com.foo.bar"/>
</contribution>

The previous examples make classes in the com.foo.bar package available to the importing contribution.

Fabric3 and OSGi Classloading

Fabric3 loads contributions in separate classloaders using OSGi. This provides contribution isolation (Java classes and artifacts are not visibile to other contributions unless they are exported, thereby reducing the potential for conflicts) and allows versioning. Further, each contribution is associated a classloader space. When a package is imported, a "wire" is created between the importing and exporting contribution. This wire is used by the importing contribution's classloader to load classes belonging to the package using the exporting conribution's classloader. A classloader space therefore consists of the contribution classloader and the classloaders it is wired to via a set of import/export pairs.

Since package imports and exports can specify versions, it is possible to control contribution isolation is a very precise manner. For example, by specifying a version, is is possible for two contributions to use different versions of the same package. For example, versions 1.0 and 2.0 of package com.bar.foo can be provided by using the @version attribute of the <export.java> element:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <export.java package="com.foo.bar" version="2.0"/>
</contribution>

An importing contribution can control which version it receives by specifying the @version attribute of the <import.java> element:

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
   <export.java package="com.foo.bar" version="2.0"/>
</contribution>

Often, it is useful to specify a version range instead of an exact version. This can be done using the @min, @minInclusive, @max, and @maxInclusive attributes of the <import.java> element:

<import.java package="org.foo.bar" min=1.0.0" minInclusive="false" max="2.0.0" maxInclusive="true"/>

By default, @minInclusive and @maxInclusive are true.
It is also possible to specify a '*' wildcard when exporting and importing packages. For example, the following will export packages com.foo.bar and com.foo.baz:

<export.java package="org.foo.*"/>

OSGi Bundles

Fabric3 also supports packaging contributions as OSGi bundles. In this case, OSGi bundle manifests may be used to export and import packages from other contributions.

Note in Fabric3 1.5, only Export-Package and Import-Package OSGi manifest headers are supported in a limited fashion. Specifically, only versions and version ranges are supported. The "uses", "required", and attribute directives are not supported.

WAR Archives

Fabric3 supports packaging contributions as WAR files. This is useful for deploying web applications that are wired to services in a domain.

Excluding Contribution Contents

Sometimes it is necessary to exclude contents of a contribution from being scanned. For example, generated XML files that contain invalid markup. Exclude patters can be specified using the <scan> element from the Fabric3 namespace in an sca-contribution.xml manifest with a REGEX pattern:

<contribution ....>
   <f3:scan exclude=".*\.ds\.xml"/>
</contribution>