Tips, Tricks and Code Tips, Tricks and Code

ESB and...

webMethods Integration Server Class-Loading

Created by Liferay Admin, last modified on Fri, 10 Oct 2014, 15:50

by Jonathan Heywood - Manager, Product Management Software AG


Product: Integration Server

Versions: 6.1, 6.5, 7.1.x, 8.0


When you want to use external Java classes or jar files from within Integration Server (IS) services, you need to decide precisely where to place or reference those classes so that they are accessible to the relevant IS services. This document first discusses where to place jar and class files, followed by a detailed description of how the IS class loaders work.

Where to place jar and class files#

It is usually preferable to place copies of required Java class or jar files within the IS package that is going to use them. This ensures that the files will automatically be included in within deployment of that package to another environment. Where you place them depends on the scope of services that needs to access them:
  • Files placed in packages/(package name)/code/jars or packages/(package name)/code/classes is only accessible to Java services inside the same package and packages that are configured to be dependent on this package. If additions or changes are made to these files, then a reload of the package is sufficient to cause the loaded classes to be refreshed from disk.

NOTE: Jar files take precedence over class files if a class is defined in both places.

  • Files placed in packages/(package name)/code/jars/static are accessible to all Java services across the entire IS. However, these files are loaded during IS startup, so a restart of IS is needed to activate any additions or changes to these.

NOTE: Jar files in this directory are always loaded, regardless of whether the containing package is enabled or disabled.

If you have good reason not to copy jar or class files to the IS directory, then you can refer to them using the PREPENDCLASSES and APPENDCLASSES settings in the file.

NOTE: Don’t forget to set these in other environments to which you deploy the packages that need these classes.

The Integration Server Class Loaders#

Classes loaded in Java are loaded by individual class loaders. There exist a number of different class loaders, each having a different purpose.

Every standard Java application begins with three class loaders:

  • java bootstrap class loader
  • java extension class loader
  • java system class loader

Integration Server extends this list adding two more class loaders:

  • IS server class loader
  • IS package class loader

An explanation of each of these class loaders follows.

Java Bootstrap Class Loader#

(Also known as the "Java Primordial Class Loader")

The java bootstrap class loader is the JVM's special built-in class loader. It loads the core java classes needed for the JVM to operate.

This class loader loads the following:

  • java.
  • javax.

Java Extension Class Loader#

The java extension class loader responsible for loading classes from JVM or JRE's extension directory

This class loader loads from the following:

  • JVM or JRE's lib/ext directory

Java System Class Loader#

(Also known as the "Java Application Class Loader")

This class loader corresponds to the "Java Classpath" section on the IS "About" page. The java system class loader is the class loader that is used to load classes when you start a java application from the command line. It's parent class loader is the Java Bootstrap class loader.

The classes that this class loader has access to defined by the "-classpath" parameter that is passed to the java executable. The classes, jars and zips are searched in the order that they appear in the parameter. The parent of this class loader is the Java extensions class loader which has access to classes in the jars and zips of the $JAVA_HOME/jre/lib/ext directory.

This class loader loads from the following:

    • This variable is defined in server.bat/.sh
  • JVM or JRE /lib directory
    • The java runtime jars (If JRE, then and i18n.jar. If JDK, then rt.jar and i18n.jar, ...)
  • IntegrationServer/lib/proxy.jar
    • The IS application launcher jar IntegrationServer/lib/proxy.jar
    • This variable is defined in server.bat/.sh

NOTE: Even in the case that a filename specified in PREPEND or APPEND SYSTEMCLASSPATH does not exist, it will still appear in the IS About page. This can bemisleading because the About Page will suggest that it is loaded, but if the filedoes not exist there is nothing to be loaded.

IS Server Class Loader#

This class loader corresponds to the "Server Classpath" section on the IS "About" page. The IS server class loader is only initialized at startup and does not change until the server restarted. This means that if you create a new package and add some jars to the code/jars/static dir, these jars will not be added to the IS server class loader until the server is restarted.

This class loader loads from the following (in order):

  • IntegrationServer/updates
    • Valid, and non-voided updates and fixes.
    • Variable defined in server.bat/sh.
  • IntegrationServer/lib/classes
    • Directory if it exists.
  • IntegrationServer/bin/ini.cnf
    • The application.classpath property from $IS_DIR/bin/ini.cnf
    • This typically specifies classes in the following directories (in order):
      - IntegrationServer/lib
      - webMethods/common/lib
      - IntegrationServer/lib/entrust
  • IntegrationServer/lib/jars
    • All .jar and .zip files in this directory
  • packages/(package name)/code/jars/static
    • All .jar and .zip from that directory in each package.
    • The files are added in whatever order the File.list() method returns them.
    • NOTE: Jars contained in this directory will be loaded even if the associated package is disabled!
  • packages/(package name)/code/libs
    • If this directory exists, then:
      - packages/(package name)/code/classes is included if it exists.
      - packages/(package name)/code/ is included if it exists.
    • variable defined in server.bat/sh.
    • environment variable if the USE_ENV_CLASSPATH variable in server.bat/sh is set to "true".
    • The default value for USE_ENV_CLASSPATH is true.

IS Package Class Loaders#

Separate package class loaders are created and associated with every Integration Server package that is loaded by the package manager. The parent of every package class loader is the IS server class loader.

NOTE: Dependent package class loaders are not children of other package class loaders - They are all direct children of the IS server class loader, with respect to the parent-child class loader relation.

These class loaders load from the following (in order):

  • (package_name)/code/
    • If this file exists
  • (package_name)/code/jars
    • All .jar and .zip from this directory of each package if it exists.
    • The files are added in whatever order the File.list() method returns them.
  • (package_name)/code/classes
    • Includes files in this directory if it exists
  • (package_name)/resources
    • Includes files in this directory if it exists
  • During runtime, the precedence when searching for a class is:
    • Resources (eg. .properties files)
    • jars
    • classes

NOTE: This means that if there exist two versions of a class with the same, but in two different places (one in a class, and one in a jar), the verion contained in the jar will take precedence.

The information in this document is provided as-is and with no warrantywhatsoever. Software AG cannot be held responsible for the results of anyinaccuracies.

0 Attachments
Average (4 Votes)

This is a good overview. I would be additionally interested in how class loader works for web applications coming as Integration Server package (packageName/web) and running on the build-in Tomcat.

The background is that we have an issue when the Integration Server class loader loads classes from WS-Stack and not from WEB-INF/lib of the web application. The class loader loads the axis-saaj.jar from WS-Stack (apache implementation version 1.4.1), instead of loading the saaj-impl-1.3.jar (Sun implementation version 1.3) from the WEB-INF/lib of our web application. This breaks Web Service clients created with the Apache CXF / JAX-WS framework producing the following error: "HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted." while running the web application on a standalone Tomcat is working without any errors.
Posted on 8/1/12 12:43 PM.
Hello Markus,

Could you please share the issue you have experienced to the Integration & ESB discussion forum available here: so that the community will be able to assist.

Best regards,
Your TECHcommunity Team
Posted on 8/22/12 11:55 AM in reply to Markus Lang.