Chapter 30: Configuring Custom Java Class Lists

Understanding how the class loader works

In Java, a class loader loads the Java classes used by an application. Most applications use the Java system class loader, which loads classes from the directories and JAR files specified by the CLASSPATH environment variable. In the normal Java program configuration, you must restart a program or server to begin using updated Java classes. EAServer uses customized Java class loaders to allow hot refresh of Web application classes and Java components without restarting the server. EAServer provides custom class loaders for these entity types:

Component For CORBA/Java and EJB components, allows you to define the list of classes that must be custom loaded in addition to the component implementation class.
Package Allows you to define a custom class list shared by all Java components that are installed in the package.
Web application Allows you to specify classes and JAR files that are not in the Web application’s WEB-INF/lib or WEB-INF/classes directories, but must be custom loaded for the Web application.
Application Allows you to define a custom class list shared by all components and Web applications that are installed in the J2EE Application.
Server Allows you to define a custom class list shared by all components, servlets, and Web applications running on the server.
Servlet For servlets that are not installed in a Web application, but are installed directly in a server, allows you define the list of classes that must be custom loaded in addition to the servlet implementation class.

Class loader versions

EAServer supports two class loader versions. EAServer releases earlier than 5.1 use class loader version 1.0. Beginning in EAServer 5.1, you can configure two versions

Version 1, the default, guarantees compatibility with applications configured to run in earlier EAServer releases.
Version 2 offers improved diagnostics and allows you to configure the delegation order for parent-child class loader relationships.

You can configure the class loader version in the EAServer Manager Server Properties dialog box, on the Java VM tab; select Use Jaguar Class Loader Version 2 to begin using the version 2 class loader. If using jagtool or an EAServer configuration file, set the server property com.sybase.jaguar.server.jvm.classloader.

The class loader hierarchy and delegation policy

Each server, component, Web application, application, and package has a custom class loader associated with it. The EAServer class loaders have a a parent-child hierarchy. Every class loader except the server class loader has a parent. This relationship is shown in the following figure:

Figure 30-1: EAServer class loader hierarchy

When you specify the same class at multiple levels, the class loader delegation policy determines how version conflicts are resolved. The version 2 class loader supports these settings:

Parent First When loading classes at levels below the server, the entity class loader delegates to it’s parent before trying to load the class itself. For example, if you specify Java package X in a component’s class list, the class list of the package where X is installed, and the class list of the server where the package is installed, the server class loader loads classes in package X.

The Parent First policy is the default. This setting avoids the overhead incurred by custom-loading multiple copies of the same class among sibling entities. This policy allows sharing of common utility classes used by components and Web applications. It also allows sharing class instances that are passed as parameters to EJB local interface calls, which is a required to avoid ClassCastException errors.
Parent Last When loading classes at the levels below the server, the entity class loader tries to load classes itself before delegating to the parent. For example, if you specify Java package X in a component’s class list and the class list of the package where X is installed, the component class loader loads the class. If another component in the same package has the same settings, two copies of the class are loaded.

Use the Parent Last policy when you must load different versions of a class in different entities. For example, in a Web application you may require a different version of a JAR file than that used by the server.

If you use the version 1 class loader, the delegation policy is always Parent First, regardless of the entity configuration.

You can configure the delegation policy for each component, package, Web application, application. In EAServer Manager, use the Class Loader Policy control on the Java Classes tab in the properties dialog for the entity. If using jagtool or an EAServer configuration file, set the property listed in the Table 30-1.

**Table 30-1: Class loader delegation properties**
Entity	Property name
Component	com.sybase.jaguar.component.classloaderpolicy
Package	com.sybase.jaguar.package.classloaderpolicy
Web application	com.sybase.jaguar.webapplication.classloaderpolicy
Application	com.sybase.jaguar.application.classloaderpolicy

The system class loader

Classes not loaded by the custom class loader must be loaded by the system class loader, based on the search order specified by the server class path setting. These classes cannot be refreshed without restarting the server. It can be more efficient configure system class loaders for classes that are used server wide, as long as all components that use them require the same class versions, and you do not need to refresh the classes without restarting the server. (For classes used server-wide that may be updated, you can configure sharing of the classes at the server class loader level, as described in “Custom class lists for packages, applications, or servers”.)

By default, the server class path includes these entries:

Class files deployed in the class trees rooted in the EAServer java/classes and html/classes subdirectories.
All JAR files in the java/lib directory that exist when the server starts, exclusive of jagtool.jar, jdmkrt.jar, and jdkmktk.jar.

You can add classes or JAR files to the server’s class path using any of these techniques:

By placing a JAR file that contains the classes in the EAServer java/lib subdirectory. At startup, EAServer automatically configures the CLASSPATH and BOOTCLASSPATH environment variables to include JAR files that you have placed in this location.
By modifying the CLASSPATH and BOOTCLASSPATH environment variables in the shell where you start the server. You can do this by adding settings to the bin/user_setenv.bat (Windows) or bin/user_setenv.sh (UNIX) scripts. EAServer applies these settings automatically when you start the server. However, they are also applied in the environment for other tools, such as EAServer Manager and jagtool.
By modifying the following server properties, using the advanced tab in the EAServer Manager server properties dialog box:
- com.sybase.jaguar.server.jvm.classpath to configure the CLASSPATH setting.
- com.sybase.jaguar.server.jvm.classpath.jars to specify JAR files in the java/lib directory to add to the CLASSPATH setting.
- com.sybase.jaguar.server.jvm.bootclasspath to configure the BOOTCLASSPATH setting.
- com.sybase.jaguar.server.jvm.bootclasspath.jars to specify JAR files in the java/lib directory to add to the BOOTCLASSPATH setting.
For syntax information, see the reference pages in Appendix B, “Repository Properties Reference,” in the EAServer System Administration Guide.