XML Repositories

Overview

The provisioning component in the FUSE ESB Kernel provides simple, yet flexible, ways to provision libraries or applications. They can be downloaded locally, installed, and started, using Maven artifacts, URLs, and local file paths. Different URL handlers are provided for installing and deploying features.

A feature consists of one or more OSGi bundles grouped to collectively provide a specific feature or functionality. Provisioning allows you to install complex applications by installing multiple related OSGi bundles in the FUSE ESB container. Each feature is made up of a collection of bundles that work together to provide some functionality. When a feature is loaded, the container loads any required bundles that are not already present into the container and activates them.

Features allow you to load a collection of bundles using a single name. Using an XML deployment descriptor, you can collectively deploy/undeploy a set of bundles and recursively a set of features.

The provisioning system uses XML repositories that define a set of features. An XML repository uses a XML features descriptor. Each descriptor defines one or more feature elements, each one representing an application that can be installed.

A feature is identified by its name, which must be unique among all the repositories used and consists of a set of bundles that must be installed, along with optional dependencies on other features and optional configurations for the Configuration Admin OSGi service. (See Configuration Admin OSGi compendium service.)

XML repository schema

The XML repository schema uses Relax NG, a schema language for XML, based on RELAX and TREX. The XML repositories use the following Relax NG Compact syntax in the repository schema:

element features {
  element repository { text }*
  element feature {
     attribute name { text },
     attribute version { text },
     element feature { 
        attribute version { text },
        text 
     }*,
     element config {
        attribute name { text },
        text
     }*,
     element bundle { text }*
  }*
}

Examples of XML repositories

The following example has one feature:

<features>
  <feature name="nmr" version="1.0.0>
      <bundle>
         mvn:org.apache.servicemix.document/org.apache.servicemix.document/1.0.0
      </bundle>
      <bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0</bundle>
      <bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.core/1.0.0</bundle>
      <bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.osgi/1.0.0</bundle>
      <bundle>
         mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.spring/1.0.0
      </bundle>
      <bundle>
         mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.commands/1.0.0
      </bundle>
      <bundle>
         mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.management/1.0.0
      </bundle>
   </feature>
</features>

The following example has two features:

<?xml version="1.0" encoding="UTF-8"?>
<features>
  <feature name="management">
     <bundle>
         mvn:org.apache.servicemix.management/org.apache.servicemix.management.core/4.0.0-fuse-SNAPSHOT
    </bundle>
  </feature>
  <feature name="transaction">
     <bundle>mvn:org.apache.geronimo.specs/geronimo-jta_1.1_spec/1.1.1</bundle>
     <bundle>mvn:org.apache.geronimo.specs/geronimo-jms_1.1_spec/1.1.1</bundle>
     <bundle>
        mvn:org.apache.geronimo.specs/geronimo-j2ee-connector_1.5_spec/2.0.0
     </bundle>
     <bundle>
        mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.howl/1.0.1-1_1
     </bundle>
     <bundle>mvn:org.apache.geronimo.components/geronimo-transaction/2.2-r634076</bundle>
     <bundle>mvn:org.apache.geronimo.components/geronimo-connector/2.2-r634076</bundle>
     <bundle>mvn:org.springframework/spring-tx/2.5.5</bundle>
     <bundle>
        mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.jencks/2.1_1
     </bundle>
     <bundle>
        mvn:org.apache.servicemix.transaction/org.apache.servicemix.transaction/4.0.0-fuse-SNAPSHOT
     </bundle>
  </feature>
<features>

Specifying bundles

The most important information provided by a feature is the set of OSGi bundles that defines an application. You specify URLs that point to the actual bundle JARs. For example, if you specify the following, this bundle will be installed when installing the feature:

<bundle>
  http://repo1.maven.org/maven2/org/apache/servicemix/nmr/org.apache.servicemix.nmr.api/1.0.0-m2/org.apache.servicemix.nmr.api-1.0.0-m2.jar
</bundle>

Maven URL handlers

FUSE ESB Kernel provides several URL handlers in addition to the usual ones like file and HTTP. One of these is the Maven URL handler, which allows you to reuse Maven repositories to point to the bundles.

The Maven equivalent of the previous bundle is:

<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2</bundle>

In addition to being less verbose, Maven URL handlers can resolve snapshots and use a local copy of the JAR if one is available in your local Maven repository.

The org.ops4j.pax.url.mvn bundle resolves Maven URLs. You can configure this flexible tool using the configuration service.

For example, to find the current repositories:

smx@root:/> config/list
...
----------------------------------------------------------------
Pid: org.ops4j.pax.url.mvn
BundleLocation: mvn:org.ops4j.pax.url/pax-url-mvn/0.3.3
Properties:
   service.pid = org.ops4j.pax.url.mvn
   org.ops4j.pax.url.mvn.defaultRepositories = 
      file:/opt/development/karaf/assembly/target/apache-felix-karaf-1.2.0-SNAPSHOT/system@snapshots
   org.ops4j.pax.url.mvn.repositories = 
      http://repo1.maven.org/maven2, 
      http://people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases, 
      http://repository.ops4j.org/maven2, 
      http://svn.apache.org/repos/asf/servicemix/m2-repo 
  below = list of repositories and even before the local repository

The repositories checked are controlled by these configuration properties.

For example, org.ops4j.pax.url.mvn.repositories is a comma separated list of repository URLs specifying the remote repositories to be checked.

To replace the defaults with a new repository at http://www.example.org/repo on the local system:

smx@root:/> config/edit org.ops4j.pax.url.mvn
smx@root:/> config/proplist                  
   service.pid = org.ops4j.pax.url.mvn
   org.ops4j.pax.url.mvn.defaultRepositories = 
      file:/opt/development/karaf/assembly/target/apache-felix-karaf-1.2.0-SNAPSHOT/system@snapshots
   org.ops4j.pax.url.mvn.repositories = 
      http://repo1.maven.org/maven2,
      http://people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases,
      http://repository.ops4j.org/maven2,
      http://svn.apache.org/repos/asf/servicemix/m2-repo
   below = list of repositories and even before the local repository
smx@root:/> config/propset org.ops4j.pax.url.mvn.repositories http://www.example.org/repo
smx@root:/> config/update

Snapshots are disabled by default. To enable a URL for snapshots, append @snapshots, for example:

http://www.example.org/repo@snapshots

Repositories on the local system are supported using file:/ URLs.

Dependent features

Dependent features are useful when a particular feature depends on another feature that must be installed. You specify the dependency in the feature definition:

<feature name="jbi">
   <feature>nmr</feature>
   ...
<feature>

Because of this dependency, the required nmr feature is automatically installed when the jbi feature is installed.

The following example shows how to specify dependencies between features. Installing the web feature requires that the web-core. feature is installed.

<feature name="web">
 <feature>web-core</feature>
   <bundle>mvn:org.ops4j.pax.web/pax-web-jsp/0.4.1</bundle>
   <bundle>mvn:org.ops4j.pax.web-extender/pax-web-ex-war/0.3.0</bundle>
   <bundle>mvn:org.ops4j.pax.web-extender/pax-web-ex-whiteboard/0.3.0</bundle>
   <bundle>mvn:org.ops4j.pax.url/pax-url-war/0.3.2</bundle>
   <bundle>
     mvn:org.apache.servicemix.war/org.apache.servicemix.war.deployer/4.0.0-fuse-SNAPSHOT
   </bundle>
 </feature>
</feature>

Configuration

The configuration section allows you to deploy configuration for the OSGi Configuration Admin service along with a set of bundles. The following is an example of such a configuration:

<config name="com.foo.bar">
   myProperty = myValue
</config>

The name attribute of the configuration element is used as the PID for the configuration set in the Configuration Admin service. When using a ManagedServiceFactory, the name attribute is servicePid-aliasId, where servicePid is the PID of the ManagedServiceFactory and aliasId is a label used to uniquely identify a particular service (an alias to the factory generated service PID)

Deploying this configuration has the same effect as dropping a file named com.foo.bar.cfg in the \etc directory of your installation.

The content of the configuration element is a set of properties parsed using the standard Java property mechanism.

This configuration is usually used with Spring-DM support for the Configuration Admin service, as in the following example:

<bean ...>
    <property name="propertyName" value="${myProperty}" />
 </bean>     
            
 <osgix:cm-properties id="cmProps" persistent-id="com.foo.bar">
    <prop key="myProperty">myValue</prop>
 </osgix:cm-properties>
 <ctx:property-placeholder properties-ref="cmProps" />

You can also use plain OSGi APIs.

For more information on using the Configuration Admin service in Spring-DM, see the Spring-DM documentation. (Also see OSGi Compendium services.)

Configuration file

There is a simple configuration file in your install directory, /etc/org.apache.servicemix.features.cfg, which contains:

...               
#
# Comma separated list of features repositories to register by default
#
featuresRepositories=mvn:org.apache.servicemix.kernel/apache-servicemix-kernel/1.1.0.0-fus
e/xml/features,mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0.0-fuse/xml/featur
es,mvn:org.apache.servicemix/apache-servicemix/4.1.0.0-fuse/xml/features,mvn:org.apache.se
rvicemix.camel/org.apache.servicemix.camel.features/4.1.0.0-fuse/xml/features
#
# Comma separated list of features to install at startup
#           
# Will put these back in when we decide to include these components
# servicemix-smpp,servicemix-snmp,servicemix-vfs,
featuresBoot=activemq,camel,jbi-cluster,web,servicemix-cxf-bc,servicemix-file,servicemix-f
tp,servicemix-http,servicemix-jms,servicemix-mail,servicemix-bean,servicemix-camel,service
mix-cxf-se,servicemix-drools,servicemix-eip,servicemix-osworkflow,servicemix-quartz,servic
emix-scripting,servicemix-validation,servicemix-saxon,servicemix-wsn2005

This configuration file has two properties:

featuresRepositories — Comma separated list of feature repositories to load at startup
featuresBoot — Comma separated list of features to install at startup

You can modify this file to customize the behavior when starting FUSE ESB Kernel for the first time. You can also modify this configuration file if you plan to distribute FUSE ESB Kernel with pre-installed features.