Chapter 28 Configuring Custom Java Class Lists

About this feature

In Java, a class loader is a Java class that 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.

EAServer uses custom Java class loaders to allow refreshing the Web application classes and Java components, and to load classes from directories and JAR files that are not specified in the CLASSPATH environment variable. This feature allows you to add or modify classes without restarting the host server.

You can configure custom class loading at these levels:

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.
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. Classes and JAR files in the Web application's WEB-INF/lib or WEB-INF/classes directory are always custom loaded.
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.
Package Allows you to define a custom class list shared by all Java components that are installed in the package.
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.

The package, application, and server custom class lists are useful when many components and Web applications share common utility classes. By custom loading these classes at a higher level, you avoid the overhead incurred by custom-loading many copies of the same class.

The EAServer class loader hierarchy

Each component, Web application, application, and package running in EAServer has a custom class loader associated with it. The EAServer class loaders are organized hierarchically, so that every class loader except the server class loader has a parent. This relationship is shown in the following figure:

Figure 28-1: EAServer class loader hierarchy

When you specify the same class at multiple levels, it is always loaded at the highest possible level. For example, if you specify Java package X in a component's class list and the server's class list, classes in package X are loaded by the server class loader.

Class loader caveats and troubleshooting

While EAServer's custom class loaders allow installation and refresh of application classes, there are issues to be aware of:

Class cast exceptions In Java, classes loaded by different class loaders are considered different types. You cannot assign a class loaded by one class loader to a reference loaded by another class loader. This restriction must be accounted for when specifying the custom class list, or when deciding at what level a class should be loaded at. If EJB local interfaces are used to call an EJB component, both the caller and the called component must be loaded by the same custom class loader.
Refreshing classes Classes must be refreshed at the level they were loaded at. For example, if your component uses classes loaded by the server class loader, you must refresh the server in order to load new implementations of those classes.

Class loader errors will be recorded in the server log file, and include the following Java exceptions:

java.lang.ClassCastException
java.lang.LinkageError
java.lang.NoClassDefFoundError
java.lang.IncompatibleClassChangeError

To troubleshoot class loader problems, you can enable custom class loader tracing by setting the server property com.sybase.jaguar.server.classloader.debug to true using the All Properties tab in the Server Properties dialog box.