Mastering JOnAS ClassLoaders

A ClassLoader knows how to load resources (class, images, ...).

Where the ClassLoader locates the resources is an implementation detail: it could search on a network drive, a local file, in a jar or in a directory, ...

Additionaly, for Java classes, a ClassLoader supports the class definition process: turning a byte[] into a Class<T> instance.

	Warning
	Beware of ClassLoaders, behind the interface, how they works can differ a lot from an implementation to another. Ex: an OSGi™ Classloader has no automatic delegation to parent loader, unlike an URLClassLoader. Understanding the execution chain requires a knowledge of the ClassLoader's internals

ClassLoaders delegate loading of resources to other ClassLoaders, under certains circumstances and conditions.

	Note
	a Class using java.lang.String must use the same Class<String> definition to be interoperable with other Class (potentially loaded by different loaders ). Delegation is essential !

In order to delegate resource loading to other loaders, a ClassLoader defines some relationships. At least, a ClassLoader have a parent loader (Only system loader do not have a parent : it is the root loader). It may (or may not) also have other links to other loaders. Theses links may (or may not) be used to delegate loading of a resource (or a class) to another loader.

	Warning
	The way the ClassLoader uses theses links to other loaders, including link to the parent loader are depending on the ClassLoader implementation.

The <bootstrap> loader is the primordial VM ClassLoader. It is responsible to load the core Java libraries (rt.jar, ...) located in JAVA_HOME/lib/*.jar.

The loader has no parent and is implemented with native code.

The <extensions> loader is the only child of <bootstrap>, it is responsible to load Java extensions (security, ...) from JAVA_HOME/lib/ext/*.jar. The content of this loader can be adapted using the java.ext.dirs system property. This property accepts a comma separated list of paths, all .jar files in theses directories will be added in the <extension> loader.

This loader is implemented (at least when using Hotspot VM) with sun.misc.Launcher$ExtClassLoader.

The <system> loader is the only child of the <extensions> loader, it contains the content of the CLASSPATH environment variable. It is implemented using sun.misc.Launcher$AppClassLoader (at least when using Hotsport VM).

JOnAS is a modular application server, it relies on OSGi™ to provide the module layer.

As a consequence, JOnAS is simply an aggregation of Bundles (more or less): a right sized (no more, no less) JOnAS assembly is possible by just choosing the right set of bundles needed by the application.

Figure 2.1. JOnAS modular architecture

Existing Bundles have to be deployed using the usual JOnAS deployment mechanisms:

Jar files (do not have OSGi™ metadata in their manifest) cannot be deployed by Just dropping a jar in ${jonas.base}/deploy/. They have to be turned into bundle first.

JOnAS offers a fast, easy and efficient mechanism to perform that operation: Extension Loader.

This mechanism look for jar files in the lib/ext/ directories of ${jonas.root} and ${jonas.base}. Every jar file (extension: *.jar) in these directorier will be transformed into a Bundle (using aQute Bnd).

# Symbolic Name is computed from source jar filename
# A maven-like artifact name is expected <artifactId>-<version>.jar (-version is optional)
# <artifactId> maps to Symbolic Name
# <version> maps to bundle version (if missing 0.0.0 is used)
Bundle-SymbolicName <artifactId>
Bundle-Version      <version>

# Imports all discovered required packages
# Have them marked as optional to avoid startup resolution errors
Import-Package *;resolution:=optional

# Export all the packages contained in the original jar
Export-Package *

# Can load any non-imported package at runtime
DynamicImport-Package *

	Note
	The lib/ext/ directories are only traversed once: when JOnAS starts. Any update or jar file removal will be ignored until next restart.

	Note
	Generated Bundles can be found in ${jonas.base}/work/ext-bundles/ Once they have been generated they could be used as standard Bundles (placed in deploy/).

Java EE modules can be represented in two groups: standalone modules and embed modules. The classloading hierarchies are different from one case to another.

Figure 2.6. Java EE Modules Classloading Hierarchy

	Note
	Visibility is from bottom to the top in this schema.

By default, a classloader follow the Java 2 delegation model: asking it's parent first. So any embed WebApp can see the content of the embeds EjbJars, embeds libraries, embed Resource Adapters of its containing Ear. And transitively, it can also access resources provided by standalone Resource adapters. But it will not be able to see resources coming from sibling WebApps and ApplicationClient, niether from standalone EjbJars and WebApps.

2.4.1.1. Standalone modules

Standalone modules means modules primarily deployed on JOnAS (artefact in deploy/ for example).

• Ears (Java EE Applications) are de facto standalone modules because they cannot be embed in another Java EE module.

• EjbJars and Web Applications are standalone module if deployed outside of an Ear.

• Rars (Resource Adapters) are standalone module if deployed outside of an Ear.

Standalone Rars are specials because they don't have an isolated ClassLoader for each, this unique loader is also the parent of all other standalone modules.

It is necessary for them to share the same loader because Rars contains jars/resources that have to be available to all Java EE deployed modules (thus be accessible in an ancestor of the Java EE loaders).

	Note
	As Standalone Resource Adapters (not in .ear) are sharing the same ClassLoader, if 2 resources overlaps, the one coming from the earliest deployed Rar is preferred.

Standalone Ears, EjbJars and WebApps are direct childs of this common ancestor: they can load resources/classes from the standalone Rars.

The Java2 delegation model is a delegation strategy where the parent loader is asked first, then local sources are probed if resource was not found by parent. This ensure a maximum class space consistence, ensuring a preference for shared sources over local sources.

This model is the default delegation model applied on all JVM provided ClassLoaders (System, URLClassLoader, ...).

The Servlet specification states that web applications must run within an “inverted delegation model”. In other words : local resources (WEB-INF/classes/ + WEB-INF/lib/) are preferred over server's resources. Standalone Jetty/Tomcat runs apps with this model by default.

On the contrary, the Java EE specification states that the default model must be the normal delegation model.

A WebApp loader can access resource from 3 main locations:

The ClassLoaders for non Web Applications are behaving like traditional ClassLoaders: they use the standard Java2 delegation strategy (parent first).

ClassLoaders of Java EE modules can be filtered with JOnAS. Filtering acts as a runtime package mask hiding a specified set of patterns.

When a resource/class is trying to be loaded by a ClassLoader, this one first checks if the fully qualified resource name (ie: includes the package name) matches a provided pattern. If so, it cut the execution flow and throw a ClassnotFoundException or return null when a class (respectively a resource) matches one of the patterns.

ClassLoader Filtering is a fine grained approach to filtering, based on pattern matching (ex: org.springframework.* excludes all resources from the org.springframework packages). It is implemented as an intermediate (pass through) ClassLoader seating between 2 other ClassLoaders (ex: Web -> (filtering) -> EjbJars).

Two levels of filters are available: system-wide (shared by all Java EE modules in the system) and per-module (only impacts a given module).

	Important
	JOnAS 5.1 only offers system wide configuration

It is globally deactivatable using the System property jonas-disable-filtering-class-loader=true

	Important
	Acts as a barrier between Java EE modules and the application server: isolate modules from resources also available in JOnAS.

Figure 3.1. Filter's position

<?xml version="1.0" encoding="UTF-8"?>
<class-loader-filtering xmlns="http://org.ow2.jonas.lib.loader.mapping">

  <!--
    List of filters used to exclude packages/resources that are used
    internally by the Application Server but that will not be available
    to applications.
    An empty list will not hide any packages to the applications
    This list is used both to hide resources and classes to applications.
  -->
  <default-filters>
    <!--
      Filters are using regexp as specified at
      http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html#matches(java.lang.String)
    -->
    <filter-name>org.apache.commons.digester.*</filter-name>
    <filter-name>org.springframework.*</filter-name>
  </default-filters>
</class-loader-filtering>

<?xml version="1.0" encoding="UTF-8"?>
<class-loader-filtering xmlns="http://org.ow2.jonas.lib.loader.mapping">
  <filters>
    <filter-name>org.apache.xml.*</filter-name>
  </filters>
</class-loader-filtering>

ClassLoader filtering should be used when JOnAS provides libraries are conflicting with application's embed libraries. That will make sure that application libraries are used instead of application server's ones.

	Warning
	Make sure that all needed packages are filtered: some libraries aggregates multiple packages. Ex : Apache Xalan includes org.apache.xalan + org.apache.xml + org.apache.xpath in Xalan.jar

The list of System Bundle exported package is expressed using 2 properties : org.osgi.framework.system.packages and org.osgi.framework.system.packages.extra.

The format of theses properties is a comma separated list of package names (ex : org.osgi.framework;version=1.5.0), just like a standard Export-Package OSGi™ header.

	Note
	Wildcards are not accepted in this list, all packages (even sub-packages) have to be declared individually.

Theses packages will then be importable from other Bundles installed on the OSGi™ gateway.

Tweaking the list of system packages may be used to hide or change some attributes of packages, that let a possibility for other bundles to provide a different version of the exported packages, and leave the choice to the bundle consummer.

That configuration freedom has to be used with care: org.osgi.framework.system.packages property has to be used only when it's needed to remove/modify a package in the system default exported list.

	Note
	javax.transaction + javax.transaction.xa are not exported by the System Bundle in JOnAS because the JVM misses some of the classes in theses packages

The System extra packages list has to be used when bundles/applications need an additional package from a library placed in endorsed directories (or in any of the place seached for System ClassLoader: extensions + CLASSPATH).

	Note
	Resolve package constraint resolution error with the addition of a new exported packages declaration to the system.

Boot delegation packages is one of the OSGi joker for known non-modular JVM packages. They have priority over all other way of classloading.

It is configurable through the org.osgi.framework.bootdelegation property. The value is a comma separated list of packages patterns: wildcard ('*') is only accepted at the end of the pattern.

	Note
	com.sun.image* : accept classes from com.sun.image and sub-packages

	Important
	Theses packages do NOT appear in system's exported packages (may lead to unexpected resolution error)

Touching this property should be avoided as much as possible, because it breaks modularity. As per the osgi delegation strategy, bootdelegation have the top most priority in loading, so no overridde is possible: a Bundle cannot use a different version (even if it import it and the import was resolved) !

In clear, it should be used as last resort: when adding packages to System Bundle did not worked or when a class in a bundle performs some dynamic class loading and makes the assumption that its own ClassLoader can load the wanted Class. There are multiple condition for this to happen:

The web console offers a search feature that helps to know from which Bundle a class/package/resource comes from.It displays the wired consumer Bundle(s).

It helps to see if a Bundle is wired to the right package provider.

Figure 4.1. OSGi Diagnosis

<title>Search for a given class in all the OSGi bundles</title>

The web console also offers a Java EE ClassLoading hierarchy view. It is dedicated to a selected Java EE module and show the ancestry of Classloader.

Filtering patterns associated to ClassLoaders are also displayed.

This view permits to test resource loading from the selected ClassLoader. That helps to see if the class comes from the expected source.

In an eye blink, suspect all static Factory.newInstance() methods. Period.

The AbstractFactory pattern is a well known and quite used pattern. There is an abstract Factory class with an implemented static method (newInstance()). This method is in charge of finding a suitable implementation that will be returned to the consumer. JAXP API are using this pattern.

Usually this method performs the following operations:

	Important
	This kind of code make the assumption that they can load any class. This is not true (even completely wrong) in a modular world

The environment has to be adapted to what is expected by the code:

Conflicting libraries are found in JOnAS and in an application.

Delegation mechanism, and the logic used to find an implementation, produces an instance from a Class incompatible with expected type.

For example, the loaded type comes from the System ClassLoader but the expected type comes from the webapp ClassLoader.

Use the stacktrace to extract faulty classnames: that's the main suspects.

Use the console to find from where theses classes/packages are loaded.

Display Right/Left ClassLoader of the assignation to discover the ClassLoader sources. -

Filter the package(s) to force resolution in your application codebase.

Usually go back to first bullet until no more Exceptions .