Sun GlassFish Enterprise Server 2.1 Developer's Guide

Chapter 2 Class Loaders

Understanding Enterprise Server class loaders can help you determine where to place supporting JAR and resource files for your modules and applications. For general information about J2SE class loaders, see Understanding Network Class Loaders.

In a Java Virtual Machine (JVM), the class loaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the class loaders loads the relevant class into the environment. This section includes the following topics:

The Class Loader Hierarchy

Class loaders in the Enterprise Server runtime follow a delegation hierarchy that is illustrated in the following figure and fully described in Table 2–1.

Figure 2–1 Class Loader Runtime Hierarchy

Figure shows the class loader runtime hierarchy.

The following table describes the class loaders in the Enterprise Server.

Table 2–1 Sun GlassFish Enterprise Server Class Loaders


Class Loader	Description
Bootstrap	The Bootstrap class loader loads the basic runtime classes provided by the JVM, plus any classes from JAR files present in the system extensions directory. It is parent to the System class loader. To add JAR files to the system extensions, directory, see Using the Java Optional Package Mechanism.
System	The System class loader loads Enterprise Server launch classes. It is parent to the Shared Chain class loader. It is created based on the `system-classpath` attribute of the `java-config` element in the `domain.xml` file. In the developer profile, select the Enterprise Server component in the Admin Console and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Path Settings tab and edit the System Classpath field. See Using the System Class Loader and java-config in Sun GlassFish Enterprise Server 2.1 Administration Reference. Add the classes to the `system-classpath` attribute of the domain administration server (DAS) in addition to the `system-classpath` attribute on the server instances that use the classes. The default name for the DAS configuration is `server-config`.
Shared Chain	The Shared Chain class loader loads most of the core Enterprise Server classes. It is parent to the MBean class loader and the Common class loader. Classes specified by the `classpath-prefix` and `classpath-suffix` attributes of the `java-config` element in the `domain.xml` file are added to this class loader. In the developer profile, select the Enterprise Server component in the Admin Console and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Path Settings tab and edit the Classpath Prefix or Classpath Suffix field. The environment classpath is included if `env-classpath-ignored="false"` is set in the `java-config` element. Use `classpath-prefix` to place libraries ahead of Enterprise Server implementation classes in the shared chain. The `classpath-prefix` is ideal for placing development and diagnostic patches. To avoid overriding implementation classes, use `classpath-suffix` to place libraries after implementation classes in the shared chain. Add the classes to the `classpath-prefix` or `classpath-suffix` attribute of the DAS in addition to the corresponding attribute on the server instances that use the classes. The default name for the DAS configuration is `server-config`.
MBean	The MBean class loader loads the MBean implementation classes. See MBean Class Loading.
Common	The Common class loader loads classes in the `domain-dir/lib/classes` directory, followed by JAR files in the `domain-dir/lib` directory. It is parent to the Connector class loader. No special classpath settings are required. The existence of these directories is optional; if they do not exist, the Common class loader is not created. See Using the Common Class Loader.
Connector	The Connector class loader is a single class loader instance that loads individually deployed connector modules, which are shared across all applications. It is parent to the LifeCycleModule class loader and the Application class loader.
LifeCycleModule	The LifeCycleModule class loader is created once per lifecycle module. Each `lifecycle-module` element’s `classpath` attribute is used to construct its own class loader. For more information on lifecycle modules, see Chapter 13, Developing Lifecycle Listeners.
Application	The Application class loader loads the classes in a specific enabled individually deployed module or Java EE application. One instance of this class loader is present in each class loader universe; see Class Loader Universes. The Application class loader is created with a list of URLs that point to the locations of the classes it needs to load. It is parent to the Web class loader. The Application class loader loads classes in the following order: Classes specified by the `library-directory` element in the `application.xml` deployment descriptor or the `–-libraries` option during deployment; see Application-Specific Class Loading Classes specified by the application's or module's `location` attribute in the `domain.xml` file, determined during deployment Classes in the classpaths of the application's sub-modules Classes in the application's or module's stubs directory The `location` attribute points to `domain-dir/applications/j2ee-apps/app-name` or `domain-dir/applications/j2ee-modules/module-name`. The stubs directory is `domain-dir/generated/ejb/j2ee-apps/app-name` or `domain-dir/generated/ejb/j2ee-modules/module-name`.
Web	The Web class loader loads the servlets and other classes in a specific enabled web module or a Java EE application that contains a web module. This class loader is present in each class loader universe that contains a web module; see Class Loader Universes. One instance is created for each web module. The Web class loader is created with a list of URLs that point to the locations of the classes it needs to load. The classes it loads are in `WEB-INF/classes` or `WEB-INF/lib/*.jar`. It is parent to the JSP Engine class loader.
JSP Engine	The JSP Engine class loader loads compiled JSP classes of enabled JSP files. This class loader is present in each class loader universe that contains a JSP page; see Class Loader Universes. The JSP Engine class loader is created with a list of URLs that point to the locations of the classes it needs to load.

Delegation

Note that the class loader hierarchy is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a class loader delegates classloading to its parent before attempting to load a class itself. A class loader parent can be either the System class loader or another custom class loader. If the parent class loader cannot load a class, the class loader attempts to load the class itself. In effect, a class loader is responsible for loading only the classes not available to the parent. Classes loaded by a class loader higher in the hierarchy cannot refer to classes available lower in the hierarchy.

The Java Servlet specification recommends that the Web class loader look in the local class loader before delegating to its parent. You can make the Web class loader follow the delegation inversion model in the Servlet specification by setting delegate="false" in the class-loader element of the sun-web.xml file. It is safe to do this only for a web module that does not interact with any other modules. For details, see class-loader in Sun GlassFish Enterprise Server 2.1 Application Deployment Guide.

The default value is delegate="true", which causes the Web class loader to delegate in the same manner as the other class loaders. You must use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see Sun GlassFish Enterprise Server 2.1 Application Deployment Guide.

Using the Java Optional Package Mechanism

Optional packages are packages of Java classes and associated native code that application developers can use to extend the functionality of the core platform.

To use the Java optional package mechanism, copy the JAR files into the domain-dir/lib/ext directory, then restart the server.

For more information, see Optional Packages - An Overview and Understanding Extension Class Loading.

Using the Endorsed Standards Override Mechanism

Endorsed standards handle changes to classes and APIs that are bundled in the JDK but are subject to change by external bodies.

To use the endorsed standards override mechanism, copy the JAR files into the domain-dir/lib/endorsed directory, then restart the server.

For more information and the list of packages that can be overridden, see Endorsed Standards Override Mechanism.

Class Loader Universes

Access to components within applications and modules installed on the server occurs within the context of isolated class loader universes, each of which has its own Application, EJB, Web, and JSP Engine class loaders.

Application Universe – Each Java EE application has its own class loader universe, which loads the classes in all the modules in the application.
Individually Deployed Module Universe – Each individually deployed EJB JAR, web WAR, or lifecycle module has its own class loader universe, which loads the classes in the module.

A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in one of the following locations:

A directory pointed to by the Libraries field or --libraries option used during deployment
A directory pointed to by the library-directory element in the application.xml deployment descriptor
A directory pointed to by the class loader’s classpath; for example, the web class loader’s classpath includes these directories:
```
module-name/WEB-INF/classes
module-name/WEB-INF/lib
```

Application-Specific Class Loading

You can specify application-specific library classes during deployment in one of the following ways:

Use the Admin Console. Open the Applications component, then go to the page for the type of application or module. Select the Deploy button. Type the comma-separated paths in the Libraries field. For details, click the Help button in the Admin Console.
Use the asadmin deploy command with the --libraries option and specify comma-separated paths. For details, see the Sun GlassFish Enterprise Server 2.1 Reference Manual.

Application libraries are included in the Application class loader. Paths to libraries can be relative or absolute. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS). The Enterprise Server automatically synchronizes these libraries to all remote cluster instances when the cluster is restarted. However, libraries specified by absolute paths are not guaranteed to be synchronized.

Tip –

You can use application-specific class loading to specify a different XML parser than the default Enterprise Server XML parser. For details, see http://blogs.sun.com/sivakumart/entry/classloaders_in_glassfish_an_attempt.

You can also use application-specific class loading to access different versions of a library from different applications.

If multiple applications or modules refer to the same libraries, classes in those libraries are automatically shared. This can reduce the memory footprint and allow sharing of static information. However, applications or modules using application-specific libraries are not portable. Other ways to make libraries available are described in Circumventing Class Loader Isolation.

For general information about deployment, see the Sun GlassFish Enterprise Server 2.1 Application Deployment Guide.

Note –

If you see an access control error message when you try to use a library, you may need to grant permission to the library in the server.policy file. For more information, see Changing Permissions for an Application.

Circumventing Class Loader Isolation

Since each application or individually deployed module class loader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:

Using the System class loader or Common class loader requires a server restart and makes a library accessible to all applications or modules deployed on servers that share the same configuration.

Using the System Class Loader

To use the System class loader, do one of the following, then restart the server:

Use the Admin Console. In the developer profile, select the Enterprise Server component and select the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Path Settings tab and edit the System Classpath field. For details, click the Help button in the Admin Console.
Edit the system-classpath attribute of the java-config element in the domain.xml file. For details about domain.xml, see the Sun GlassFish Enterprise Server 2.1 Administration Reference.

Using the System class loader makes an application or module accessible to all applications or modules deployed on servers that share the same configuration.

Add the classes to the system-classpath attribute of the DAS in addition to the system-classpath attribute on the server instances that use the classes. The default name for the DAS configuration is server-config.

Using the Common Class Loader

To use the Common class loader, copy the JAR files into the domain-dir/lib directory or copy the .class files into the domain-dir/lib/classes directory, then restart the server.

Using the Common class loader makes an application or module accessible to all applications or modules deployed on servers that share the same configuration.

For example, using the Common class loader is the recommended way of adding JDBC drivers to the Enterprise Server. For a list of the JDBC drivers currently supported by the Enterprise Server, see the Sun GlassFish Enterprise Server 2.1 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers in Sun GlassFish Enterprise Server 2.1 Administration Guide.

Sharing Libraries Across a Cluster

To share libraries across a specific cluster, copy the JAR files to the domain-dir/config/cluster-config-name/lib directory. Then add the path to the JAR files to the System class loader as explained in Using the System Class Loader or to the Shared Chain class loader as explained in Table 2–1.

Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide.

Packaging the Client JAR for One Application in Another Application

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

As an alternative for a production environment, you can have the Common class loader load the client JAR of the dependent application as described in Using the Common Class Loader. Restart the server to make the dependent application accessible to all applications or modules deployed on servers that share the same configuration.

To Package the Client JAR for One Application in Another Application

Deploy the dependent application.

Add the dependent application’s client JAR file to the calling application.
- For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:
```
Class-Path: filepath1.jar filepath2.jar ...
```
  Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the Java EE specification.
- For a calling web component, add the client JAR file under the WEB-INF/lib directory.

If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file.

This changes the Web class loader so that it follows the standard class loader delegation model and delegates to its parent before attempting to load a class itself.

For most applications, packaging the client JAR file with the calling EJB component is sufficient. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application.

Deploy the calling application.

The calling EJB or web component must specify in its sun-ejb-jar.xml or sun-web.xml file the JNDI name of the EJB component in the dependent application. Using an ejb-link mapping does not work when the EJB component being called resides in another application.

You do not need to restart the server.