Class Loading in Integration Server

How Class Loading Works in Integration Server

Integration Server runs in the Java Virtual Machine (JVM). When Integration Server, or any Java application, needs access to a class, the JVM locates the executable bytecode of the class and brings it into the JVM. This process is referred to as loading the class and is handled by class loaders. The class loaders in Integration Server and the JVM are designed to load classes from different locations.

During server initialization, at the point when Integration Server loads packages, Integration Server also loads all classes that contain Java services. A Java service contains statements that reference other Java classes. To execute these statements, the referenced classes must be loaded into the JVM.

If you are using your own classes developed by your company or classes from a third-party library, you can control the visibility and loading order of these classes. Class visibility refers to whether the classes and jar files will be or need to be visible to all the classes in Integration Server or to a particular package only.

Integration Server Class Loaders

Integration Server includes a server class loader and package class loaders. These class loaders load classes required for Integration Server to function.

The following diagram shows the different class loaders and their relationship in the class loader chain.

Integration Server Server Class Loader loads the classes that comprise the core of Integration Server. This loader loads from the Server Classpath, which you can see on the About page, and which is described below.
Integration Server Package Class Loaders load classes from Integration Server packages. These packages include those created by users through Designer and predefined packages that are provided as part of Integration Server. Each package has its own class loader.

Classpaths

The Integration Server classpath is the list of files and directories that Integration Server class loaders search when looking for classes. In Integration Server Administrator, the About page shows the files and directories that make up the classpaths used by the Integration Server’s class loaders. The following image shows a portion of that display.

Example of the Integration Server classpath displayed in Integration Server Administrator

How the Integration Server Classpath Is Set

When you start Integration Server, a script file named startup.bat (on Windows) or startup.sh (on UNIX) runs. Among other things, the startup.bat/sh file builds an Integration Server classpath variable which consists of many directories and variables.

The following table describes the directories and variables that Integration Server uses to construct the Integration Server classpath.

Directory or variable	Description
The `wrapper.java.additional.202= -Dwatt.server.prepend.classes` property of the `Integration Server_directory`\instances\`instance_name`\configuration\custom_wrapper.conf	Variable defined in custom_wrapper.conf that defines directories and files to prepend to the beginning of the classpath.
The `wrapper.java.additional.203= -Dwatt.server.append.classes` property of the `Integration Server_directory`\instances\`instance_name`\configuration\custom_wrapper.conf	Variable defined in custom_wrapper.conf that defines directories and files to append to the end of the classpath.
`Integration Server_directory`\instances\`instance_name`\bin\ini.cnf	The application.classpath property from `Integration Server_directory`\instances\ `instance_name`\bin\ini.cnf. This typically specifies classes in the following directories, in this order: `Integration Server_directory`\lib `Software AG_directory` \common\lib
`Integration Server_directory`\ instances\`instance_name`\lib\jars\custom	All custom or third party .jar and .zip files in this directory. Note: Use this directory to store your custom or third party .jar and .zip files that you want to make available to a server specific instance.
`Integration Server_directory`\ instances\`instance_name`\packages\`package_name`\code\jars\static	All .jar and .zip files from this directory in each package. The files are added to the classpath in the order returned by the File.list() method. Note: Jars contained in this directory will be loaded even if the associated package is disabled.
`Integration Server_directory`\instances\`instance_name`\packages\`package_name`\code\classes	If this directory exists, it is added to the classpath.
`Integration Server_directory`\instances\`instance_name`\packages\`package_name`\code\classes.zip	If this file exists, it is added to the classpath.
`Integration Server_directory`\instances\`instance_name`\updates	Valid, and non-voided updates and fixes.
`Integration Server_directory`\lib\jars	All .jar and .zip files in this directory.
`Integration Server_directory`\lib\jars\custom	Common custom and third party .jar and .zip files in this directory. Note: Use this directory to store your custom and third party .jar and .zip files that you want to make available to all server instances.
`Integration Server_directory`\updates	Common valid, and non-voided updates and fixes. Note: The updates and fixes in this directory are available to all server instances.

Note: In some cases, the Integration Server Administrator About page will display the names of files that do not exist. If filenames specified in the wrapper.java.additional.202=-Dwatt.server.prepend.classes and wrapper.java.additional.203=-Dwatt.server.append.classes properties for the Integration Server classpath do not exist, they will still be displayed on the Integration Server About page. If the ini.cnf file refers to jar files that do not exist, they will also be displayed on the About page and, if the watt.debug.warnOnClasspathError server configuration parameter is set to true, the following error will be written to the standard out for each non-existent jar file: Classpath entry in ini.cnf not found: <jar_file_name>. Standard out is directed to Integration Server_directory\instances\instance_name\logs\wrapper.log.

Additional Information about How the Microservices Runtime Classpath Is Set

The Microservices Runtime classpath is set in much the same way as the Integration Server classpath. However, there are two significant differences:

Microservices Runtime does not use instances. References to Software AG_directory\Integration Server_directory\instances\instance_name for Integration Server in the table in How the Integration Server Classpath Is Set correspond to just Integration Server_directory for Microservices Runtime.
Microservices Runtime uses information from Integration Server_directory/bin/setenv.bat(sh), specifically from the PREPENDCLASSES and APPENDCLASSES properties. Microservices Runtime does not use information from the custom_wrapper.conf file to build the classpath.

Note: In some cases, the Microservices Runtime About page will display the names of files that do not exist. Specifically, if filenames specified in the PREPENDCLASSES and APPENDCLASSES variables for the Microservices Runtime classpath do not exist, they will still be displayed on the Microservices Runtime About page.

Adding Classes to the Server Classpath

If you are using your own classes developed by your company or classes from a third-party library, you can control the visibility and loading order of these classes. Class visibility refers to whether the classes and jar files will be or need to be visible to all the classes in Integration Server or to a particular package only.

Classes and jar files that are added to the server classpath are visible to all classes in Integration Server including all Java services. In a sense, the classes and jar file are globally visible.

Note: The visibility of a class may also be restricted to members of the same Java package by omitting the "public" modifier from the class declaration. This is not directly related to class loading and is described in the Java documentation.

There are three ways to add classes and libraries (jar and zip files) to the classpath.

Option 1. Copy jar or zip files to a package's code\jars\static directory. Integration Server adds the files to the classpath when the package loads.
Note that if you change the contents of a jar file in a package's code\jars\static directory, you must restart Integration Server for the change to take effect. Simply reloading the package is not sufficient.
Option 2. Copy jar or zip files to the Integration Server_directory\instances\instanceName\lib\jars\custom directory. Integration Server adds the files to the classpath when Integration Server starts.
If you want to add your jar or zip files to the classpath for all Integration Server instances in an installation, copy the files to the Integration Server_directory\lib\jars\custom directory.

Note: For Option 2 for Microservices Runtime, add your jar or zip files to Integration Server_directory\lib\jars\custom

Option 3. Copy files to another location on the file system. Add the path to the jar or class files directory to the watt.server.prepend.classes or watt.server.append.classes properties set in the following file:

Integration Server_directory\instances\instanceName\configuration\custom_wrapper.conf:

If the custom_wrapper.conf file contains overrides to the classpath information, the server uses those settings during startup.

The following table identifies the variables you can use to add directories to the beginning and the end of the Integration Server classpath:

To add directories to the	Edit this variable
Beginning of the classpath	`wrapper.java.additional.202= -Dwatt.server.prepend.classes=`
End of the classpath	`wrapper.java.additional.203= -Dwatt.server.append.classes=`

For Microservices Runtime, add the path to the jar or class files to: Integration Server_directory/bin/setenv.bat(sh)

The following table identifies the Java system properties that you can set in setenv.bat(sh) to add directories the beginning or end of the classpath for Microservices Runtime.

To add directories to the	Edit this Java system property
Beginning of the classpath	PREPENDCLASSES in setenv.bat/sh.
End of the classpath	APPENDCLASSES in setenv.bat/sh.

For more detailed information about where and how these variables are added to the classpaths, see Classpaths. For more information about the custom_wrapper.conf and the properties you can set, see IBM webMethods Infrastructure Administrator's Guide.

Keep the following information in mind when choosing how to add classes and libraries to the classpath.

Options 1 and 2 described above will work only for jar and zip files. Option 3 will work for jar, zip, class, and other files.
Some third-party libraries look in the classpath for configuration or other types of files. Use option 3 to add these files to the classpath.
When option 1 is used, all jar and zip files in a package's code\jars\static directory are automatically included if the package is deployed to another Integration Server. With options 2 and 3, an additional step is required to deploy the jar, zip or class files.
Where the classes appear on the server classpath affect the loading order. For more information about loading order, see How Classes Are Found.

Adding Classes to a Package

If a class will be used only by services in a single Integration Server package, you can limit the visibility of the class to that package by placing the class in the package's code/classes directory. If the class is distributed in a jar or zip file, place it in the package's code/jars directory. Files in a package's code/classes or code/jars directories are not added to the Integration Server’s classpath.

Note: If you change the contents of a jar or class file in a package's code/jars or code/classes directory, reload the package to make the change take effect. You do not need to restart Integration Server for the changes to take effect.

If you have a package that needs access to a class in another package's code/classes or code/jars directory, you can provide access by creating a dependency relationship between the two packages. For example, consider the following scenario:

PackageA has a class in its code/classes directory.
PackageB needs to use the class in PackageA's code/classes directory.

You can use Designer to establish a dependency on PackageA from PackageB.

Alternatively, you can modify PackageB's manifest.v3 to require PackageA.

<record name="requires" javaclass="com.wm.util.Values">

<value name="PackageA">1.0</value>

</record>

After editing the manifest, if Integration Server is running, reload PackageB.

PackageB is now able to access classes in PackageA's code/classes and code/jars directories. Because PackageB requires PackageA, PackageB cannot be enabled unless PackageA is enabled. PackageA cannot be disabled unless PackageB is disabled. Reloading PackageA will cause PackageB to be reloaded.

Class Searching Order

When a Java service refers to a class, Integration Server will, by default, look for the referenced class in this order:

On the server classpath.
Locally, within the package.
In all required packages.

When a class is found, Integration Server immediately loads and uses the class.

You can change the class loading order by modifying a package's manifest.v3 file to use the package class loader:

<value name='classloader'>package</value>

When a package's classloader property is "package", the class loading order is as follows:

Locally, within the package.
In all required packages.
On the server classpath.

The default value for the classloader property is "system". That is what Integration Server uses when no value is set for the classloader property:

<value name='classloader'/>

For detailed information about configuring a package to use the package class loader, see Using a Package Class Loader.

How Classes Are Found

When you are choosing where to put your classes on the server classpath, as described in Adding Classes to the Server Classpath, consider the effect of the possible locations on the loading order. Here is the order in which Integration Server searches the various locations relative to one another:

watt.server.prepend.classes
Software AG_directory\Integration Server_directory\instances\instanceName\bin\ini.cnf
Specifically, the application.classpath property in the ini.cnf file. The application.classpath property typically specifies classes in the following directories, in this order:
- Integration Server_directory\lib
- Software AG_directory\common\lib
Software AG_directory\Integration Server_directory\instances\instanceName\lib\jars
Software AG_directory\Integration Server_directory\instances\instanceName\lib\jars\custom
Software AG_directory\Integration Server_directory\lib\jars
Software AG_directory\Integration Server_directory\lib\jars\custom
Software AG_directory\Integration Server_directory\instances\instanceName\packages\packageName\code\jars\static
watt.server.append.classes

Note: For information about the directories Microservices Runtime searches for class and jar files, see How Classes Are Found in Microservices Runtime.

If you have two or more copies of a class, whether it is a single class file or is a class in a jar file, and multiple locations for the class appear in the server classpath, Integration Server always loads the instance of the class that appears first in the server classpath. Integration Server never uses other instances of the same class that appear later in the server classpath. A scenario where this is significant is when different versions of a third-party jar file are on the server classpath. Integration Server always uses the version that comes first in the server classpath.

If more than one package has jar files in its code\jars\static directory, the jar files will be added to the server classpath in alphabetical order, by package name. For example, jar files in PackageA\code\jars\static will be loaded before jar files in PackageB\code\jars\static.

You can view the Integration Server classpath on the About page in Integration Server Administrator.

How Classes Are Found in Microservices Runtime

The locations that Microservices Runtime searches relative to one another is different than Integration Server because Microservices Runtime does not have the directory \instances\instanceName.

Below is the order in which Microservices Runtime searches the various locations relative to one another:

PREPENDCLASSES in Integration Server_directory\bin\server.bat(sh)
Software AG_directory\Integration Server_directory\bin\ini.cnf
Specifically, the application.classpath property in the ini.cnf file. The application.classpath property typically specifies classes in the following directories, in this order:
- Integration Server_directory\lib
- Software AG_directory\common\lib
Software AG_directory\Integration Server_directory\lib\jars
Software AG_directory\Integration Server_directory\lib\jars\custom
Software AG_directory\Integration Server_directory\packages\packageName\code\jars\static
APPENDCLASSES in Integration Server_directory\bin\server.bat(sh)

Note: Microservices Runtime handles two or more copies of a class or multiple packages with jar files in its code\jars\static directory the same way in which Integration Server does. For more information, see How Classes Are Found.

Searching Order within a Package

When Integration Server searches within a package for a class, it uses this order:

packageName\resources
packageName\lib
packageName\code\jars
packageName\code\classes

Note: When a package requires another package, Integration Server will first look for a referenced class in the above order within the package that refers to the class. Then Integration Server will look in the above order in the required packages.

Where to Put Your Classes and Jar Files

If you are using your own classes developed by your company or classes from a third-party library, you can control the visibility and loading order of these classes. Class visibility refers to whether the classes and jar files will be or need to be visible to all the classes in Integration Server or to a particular package only.

Use the following guidelines to help you decide where to put your class files and jar files.

If a class or jar file is needed only by services in one Integration Server package, put it in the package's code/classes or code/jars directory.
If a class or jar file is needed by a second Integration Server package, keep the class or jar in the package that it already resides in and establish a package dependency on the first package. You can accomplish this by using Designer to establish a dependency on the first package from the second package or by modifying the second package's manifest.v3 file to require the first package.
If additional Integration Server packages need the class or jar file, and the package dependencies are becoming difficult to manage, do one of the following:
- If it is a jar or zip file, move it to the package's code/jars/static directory. This will add the jar or zip to the server's classpath and make it available to all packages.
- If it is a class or a set of classes and you are using Integration Server, add the full path to the parent directory in one of these lines in the following file: Integration Server_directory\instances\instanceName\configuration\custom_wrapper.conf
  wrapper.java.additional.202=-Dwatt.server.prepend.classes=
  
  wrapper.java.additional.203=-Dwatt.server.append.classes=
If it is a class or a set of classes and you are using Microservices Runtime, add the full path to the parent directory in one of the Java system properties in the following file: Software AG_directory\Integration Server_directory\bin\setenv.bat(sh)
APPENDCLASSES

PREPENDCLASSES
If your package needs a different version of a class or jar file than one that resides in another package, copy the version you need to your package's code/classes or code/jars directory.
If your package needs a different version of a class or jar file than one that is on the server classpath, do the following:
1. Copy the version you need to your package's code/classes or code/jars directory.
2. Change your package's classloader property to "package".
When a Java security provider is registered with the JVM, the provider is available to all Integration Server packages. Java security is implemented in such a way that the JVM retains the implementation of the provider along with its class loader and makes this implementation available to every process running within the JVM. This affects other Integration Server packages as well as any other installed products that run in the JVM. For this reason, registering additional security providers or overriding existing ones should be done with caution.
By default, Integration Server classloaders load multi-release JAR files. The jdk.util.jar.enableMultiRelease system property in the custom_wrapper.conf file located in the Integration Server_directory\instances\instanceName\configuration directory controls the functionality. By default, the value of the property is true, which enables the functionality. Set the value to false to disable the functionality. For more information, see the JarFile class documentation on Oracle Help Center.

Accelerating Class Loading

Class loading can be a time consuming process when many directories and classes are involved. Depending on your application and how it is used, the following server configuration parameters might help classes load more quickly.

watt.server.coder.bincoder.trycontextloaderfirst

When this property is set to true, when Integration Server encodes or decodes a pipeline, it uses the context loader before using the class loader for the currently executing thread. If a referenced class belongs to a particular package, it may be faster to use the context loader first.

watt.server.classloader.pkgpriority=packageName, packageName

Some Integration Server facilities do not operate within the context of a package. When a class is referenced from these facilities, all packages are searched in a non-deterministic order. This configuration parameter specifies a comma-delimited list of the packages that Integration Server is to search first. Specifying a package search order may offer a performance improvement. Refer to Server Configuration Parameters for more information about this property.