Sun GlassFish Enterprise Server v3 Prelude 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 JVM implementation, 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:

Note –

For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. Web services are not supported unless the optional Metro (JSR 109) add-on component is downloaded from the Update Tool. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

The Class Loader Hierarchy

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

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 software.
Extension	The Extension class loader loads classes from JAR files present in the system extensions directory, `domain-dir/lib/ext`. It is parent to the Public API class loader. See Using the Java Optional Package Mechanism.
Public API	The Public API class loader makes available all classes specifically exported by the Enterprise Server runtime for use by deployed applications. This includes, but is not limited to, Java EE APIs and other Sun GlassFish APIs. It is parent to the Common class loader.
Common	The Common class loader loads JAR files in the `as-install/lib` directory, then classes in the `domain-dir/lib/classes` directory, followed by JAR files in the `domain-dir/lib` directory. Using `domain-dir/lib/classes` or `domain-dir/lib` is recommended whenever possible, and required for custom login modules and realms. It is parent to the Connector class loader. 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 Applib class loader.
Applib	The Applib class loader loads the library classes, specified during deployment, for a specific enabled module; see Application-Specific Class Loading. One instance of this class loader is present in each class loader universe; see Class Loader Universes. It is parent to the Archive class loader. When multiple deployed applications use the same library, they share the same instance of the library. One library cannot reference classes from another library.
Archive	The Archive class loader loads classes from the WAR and JAR files or directories (for directory deployment) of modules deployed to the Enterprise Server. This class loader also loads any application-specific classes generated by the Enterprise Server runtime, such as stub classes or servlets generated by JSP pages.

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 class loading to its parent before attempting to load a class itself. 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.

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 modules installed on the server occurs within the context of isolated class loader universes, each of which has its own Applib and Archive class loaders.

Individually Deployed Module Universe – Each individually deployed EJB JAR or web WAR 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 module’s classpath; for example, a web module’s classpath includes these directories:
```
module-name/WEB-INF/classes
module-name/WEB-INF/lib
```

Application-Specific Class Loading

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

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

Application libraries are included in the Applib 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).

If multiple 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, modules using application-specific libraries are not portable. Other ways to make libraries available are described in Circumventing Class Loader Isolation.

One library cannot reference classes from another library.

For general information about deployment, see the Sun GlassFish Enterprise Server v3 Prelude 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 module class loader universe is isolated, a module cannot load classes from another module. This prevents two similarly named classes in different modules from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules, you can include the relevant path to the required classes. See Using the Common Class Loader.

Using the Common Class Loader

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

Using the Common class loader makes a module accessible to all 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 v3 Prelude Release Notes. For configurations of supported and other drivers, see Configuration Specifics for JDBC Drivers in Sun GlassFish Enterprise Server v3 Prelude Administration Guide.

To activate custom login modules and realms, place the JAR files in the domain-dir/lib directory or the class files in the domain-dir/lib/classes directory, then restart the server.