Class Loaders

Previous Next Contents

2 Class Loaders

Understanding Oracle GlassFish Server class loaders can help you determine where to place supporting JAR and resource files for your modules and applications.

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.

The following topics are addressed here:

Note

The Web Profile of the GlassFish Server supports the EJB 3.1 Lite specification, which allows enterprise beans within web applications, among other features. The full GlassFish Server supports the entire EJB 3.1 specification. For details, see JSR 318 (http://jcp.org/en/jsr/detail?id=318).

For information about class loader debugging, see Class Loader Debugging.

The Class Loader Hierarchy

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

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

Table 2-1 Oracle GlassFish 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 GlassFish Server runtime for use by deployed applications. This includes, but is not limited to, Java EE APIs and other Oracle APIs. It is parent to the Common class loader.

Common

The Common class loader loads JAR files in the as-install`/lib` directory, followed by JAR files in the domain-dir`/lib` directory. Using 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 and the LifeCycleModule class loader.

LifeCycleModule

The LifeCycleModule class loader is created once per lifecycle module. Each lifecycle module’s classpath is used to construct its own class loader. For more information on lifecycle modules, see Developing Lifecycle Listeners.

Applib

The Applib class loader loads the library classes, specified during deployment, for a specific enabled module or Java EE application; 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, EAR, and JAR files or directories (for directory deployment) of applications or modules deployed to the GlassFish Server. This class loader also loads any application-specific classes generated by the GlassFish Server runtime, such as stub classes or servlets generated by JSP pages.

In previous GlassFish Server versions, the JVM options provided classpath-prefix and classpath-suffix attributes that made it possible to add JAR files or directories either in front of, or after the application server’s system classpath. These options are not present in GlassFish Server 5.0.

The classpath-prefix was typically used to substitute another package for one of the GlassFish Server packages, for example if a newer one was available. This same result can be achieved by using the Java Endorsed Standards Override Mechanism or on a per-application basis with the --libraries option for the deploy subcommand. For more information, see Using the Endorsed Standards Override Mechanism and the deploy(1) help page, respectively. The Java Optional Package Mechanism does what classpath-suffix used to do. For more information, see Using the Java Optional Package Mechanism.

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.

The Java Servlet specification recommends that a web module’s class loader look in the local class loader before delegating to its parent. You can make this class loader follow the delegation inversion model in the Servlet specification by setting delegate="false" in the class-loader element of the glassfish-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 GlassFish Server Open Source Edition Application Deployment Guide.

The default value is delegate="true", which causes a web module’s 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 glassfish-web.xml, see the GlassFish Server Open Source Edition Application Deployment Guide.

For a number of packages, including java.* and javax.*, symbol resolution is always delegated to the parent class loader regardless of the delegate setting. This prevents applications from overriding core Java runtime classes or changing the API versions of specifications that are part of the Java EE platform.

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, or use the asadmin add-library command with the --type ext option, then restart the server. For more information about the asadmin add-library command, see the GlassFish Server Open Source Edition Reference Manual.

For more information, see Optional Packages - An Overview (http://docs.oracle.com/javase/8/docs/technotes/guides/extensions/extensions.html) and Understanding Extension Class Loading (http://docs.oracle.com/javase/tutorial/ext/basics/load.html).

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 (http://docs.oracle.com/javase/8/docs/technotes/guides/standards/).

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 Applib and Archive 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 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 library-directory element in the application.xml deployment descriptor

  • A directory pointed to by the application or 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- or application-specific library classes in one of the following ways:

  • Use the Administration 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 Administration Console.

  • Use the asadmin deploy command with the --libraries option and specify comma-separated paths. For details, see the GlassFish Server Open Source Edition Reference Manual.

  • Use the asadmin add-library command with the --type app option, then restart the server. For details, see the GlassFish Server Open Source Edition Reference Manual.

Note

None of these alternatives apply to application clients. For more information, see Using Libraries with Application Clients.

You can update a library JAR file using dynamic reloading or by restarting (disabling and re-enabling) a module or application. To add or remove library JAR files, you can redeploy the module or application.

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). The GlassFish 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 GlassFish Server XML parser.

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.

One library cannot reference classes from another library.

For general information about deployment, including dynamic reloading, see the GlassFish Server Open Source Edition 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 or modules 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 Common Class Loader

To use the Common class loader, copy the JAR files into the domain-dir`/lib` or as-install`/lib` directory, or use the asadmin add-library command with the --type common option, then restart the server. For more information about the asadmin add-library command, see the GlassFish Server Open Source Edition Reference Manual.

Using the Common class loader makes an application or module accessible to all applications or modules deployed on servers that share the same configuration. However, this accessibility does not extend to application clients. For more information, see Using Libraries with Application Clients.

For example, using the Common class loader is the recommended way of adding JDBC drivers to the GlassFish Server. For a list of the JDBC drivers currently supported by the GlassFish Server, see the GlassFish Server Open Source Edition Release Notes. For configurations of supported and other drivers, see "Configuration Specifics for JDBC Drivers" in GlassFish Server Open Source Edition Administration Guide.

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

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.

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

  1. Deploy the dependent application.

  2. 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. 3. 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 glassfish-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. 4. Deploy the calling application.
The calling EJB or web component must specify in its glassfish-ejb-jar.xml or glassfish-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.


Previous Next Contents
Eclipse Foundation Logo  Copyright © 2019, Oracle and/or its affiliates. All rights reserved.