Classloaders

There are several classloaders involved in ServiceMix:

• the container class loader
• shared library class loader: the parent is the container class loader
• component class loader: parents are container class loader + any referenced SL class loader
• service unit class loader: parent is the component class loader

The container class loader contains: JRE + /conf + /lib/*.jar + /lib/optional/*.jar. ServiceMix 3.1, uses Classworlds to configure a classloader finding path. You can add your own path into the conf/servicemix.conf file.

The components class loaders are defined in the JBI spec and contain the jars referenced in the JBI descriptor (META-INF/jbi.xml). These class loaders can use a parent-first (default) or self-first delegation. When a class is loaded, the class loader will first ask its parent(s) and work back down the classloader hierarchy, or will first load the class from its referenced jars.

The service unit class loader is not specified in the JBI spec, because the SU content is specific to each component. In ServiceMix, all XBean based SUs may define their own classloader using the <classpath /> location (though since ServiceMix 3.1 this is no longer necessary, see the last section below).

Let's say you deploy a POJO to the servicemix-lwcontainer. When building the configuration, for XBean to find the class, it will ask the SU classloader to do so. So the component may be inside this classloader, or one of its parent (servicemix-lwcontainer, servicemix-shared and the container classloader). However, the component and SL classloaders are not easily modified (you need to repackage the artifact and redeploy it), so you can put this class in the SU or the container.

If you put this class in the container, you will need to restart the container after having added the jar in the classpath, which is not what we want. So usually, we put it in the SU.

The other benefit of using classloaders is that you can have isolated components. You could deploy two components (or SU) which use different version of the same library without any problems. This is not possible if you put all the dependencies in the container classpath.

Self-first delegation

The common delegation mechanism for classloaders is to delegate to the parent first when loading a class. Thus, all classes defined in the container classloader are shared. But when a class references another class (using an import statement in the Java code for example), the referenced classes will be loaded by the same classloader. To avoid such problems, you can use a self-first delegation where classes are loaded from the classloader, and if not found, it will ask its parent.

Shared libraries and SMX components

To enable self-first delegation for shared libraries and components change the service's POM.XML to include

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.servicemix.tooling</groupId>
      <artifactId>jbi-maven-plugin</artifactId>
      <configuration>
        <classLoaderDelegation>self-first</classLoaderDelegation>
      </configuration>
    </plugin>
  </plugins>
</build>

SU Classloaders

XBean based service units can define their own classloader. This can be done by adding the following tag in the main XBean configuration file for the SU (xbean.xml or servicemix.xml for the servicemix-lwcontainer component):

<classpath [inverse="true"]>
  [<nonOverridable>xxx</nonOverridable>]*
  [<hidden>xxx</hidden>]*
  [<location>xxx</location>]*
</classpath>

The inverse attribute can be set to true to use self-first delegation mode.

The nonOverridable tag can be used to specify that classes with a name starting with the specified string can not be overridden by this classloader (the classloader will always use the parent classes).

The hidden tag is used to hide specific classes (whose name start with the specified string) defined by the parent classloader.

The location tag can be used to add jars or directories relative to the SU root to the classloader.

New in ServiceMix 3.1

Starting with ServiceMix 3.1, if no classpath is defined, or if no locations are specified, the default ones will be automatically added in the SU classloader:

• /
• lib/*.jar
• lib/*.zip

For ServiceMix 3.0.x versions, you need to define the classpath manually, as the default does not include any locations.

New in ServiceMix 3.2

You can now reference Shared Libraries and Components classloaders using the following syntax:

<classpath [inverse="true"]>
  [<nonOverridable>xxx</nonOverridable>]*
  [<hidden>xxx</hidden>]*
  [<location>xxx</location>]*
  [<library>xxx</library>]*
  [<component>xxx</component>]*
</classpath>

For example to reference the "cxf" shared library and the "servicemix-wsn2005" component in addition to the jars inside the SU, you could write:

<classpath>
  <library>cxf</library>
  <component>servicemix-wsn2005</component>
</classpath>

New In ServiceMix 3.3.1

You can now reference external archives using system properties. For example:

<classpath>
  <location>${servicemix.home}/lib/ext/my.jar</location>
</classpath>

You can explore and use regex inside externale archives (zip, jar, war, ear). For example:

<classpath>
  <location>jar:file:/path/to/my.ear!/my.jar</location>
  <location>jar:file:/path/to/my.ear!/other*.jar</location>
</classpath>

New in ServiceMix 4.2.0

To allow you to access classes from other OSGi bundles in your SU code as well, the library element has now been enhanced to allow referencing bundles when running in ServiceMix 4.2.0 or above. The URI syntax is osgi:<bundle symbolic name> or osgi:<bundle symbolic name>/<version> to reference a specific bundle version.

Example: the following snippet explicitly adds the org.springframework.bean bundle to the SU classloader.

<classpath>
  <library>osgi:org.springframework.bean</library>
</classpath>