docs/application-development-guide/src/main/asciidoc/class-loaders.adoc

type=page
status=published
title=Class Loaders
next=debugging-apps.html
prev=setting-up-dev-env.html
~~~~~~

= Class Loaders

[[GSDVG00003]][[beade]]


[[class-loaders]]
== 2 Class Loaders

Understanding {productName} 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:

* link:#beadf[The Class Loader Hierarchy]
* link:#gfqpi[Delegation]
* link:#beadk[Using the Java Optional Package Mechanism]
* link:#beadg[Class Loader Universes]
* link:#gatej[Application-Specific Class Loading]
* link:#beadh[Circumventing Class Loader Isolation]


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


For information about class loader debugging, see
link:debugging-apps.html#gkpdk[Class Loader Debugging].

[[beadf]][[GSDVG00094]][[the-class-loader-hierarchy]]

=== The Class Loader Hierarchy

Class loaders in the {productName} runtime follow a delegation
hierarchy that is illustrated in the following figure and fully
described in link:#fvxzq[Table 2-1].

The following table describes the class loaders in the {productName}.

[[GSDVG531]][[sthref4]][[fvxzq]]


Table 2-1 {productName} Class Loaders

[width="100%",cols="20%,80%",options="header",]
|===
|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 link:#beadk[Using the Java
Optional Package Mechanism].

|Public API |The Public API class loader makes available all classes
specifically exported by the {productName} runtime for use by
deployed applications. This includes, but is not limited to, Jakarta 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 link:#beadj[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
link:lifecycle-listeners.html#beamc[Developing Lifecycle Listeners].

|Applib a|
The Applib class loader loads the library classes, specified during
deployment, for a specific enabled module or Jakarta EE application; see
link:#gatej[Application-Specific Class Loading]. One instance of this
class loader is present in each class loader universe; see
link:#beadg[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 {productName}. This class loader also loads
any application-specific classes generated by the {productName}
runtime, such as stub classes or servlets generated by JSP pages.
|===


In previous {productName} 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 {productName} 6.0.

The `classpath-prefix` was typically used to substitute another package
for one of the {productName} packages, for example if a newer one was
available. This same result can be achieved on a per-application basis with the
`--libraries` option for the `deploy` subcommand. For more information,
see the link:reference-manual/deploy.html#GSRFM00114[`deploy`(1)] help page.
The Java Optional Package Mechanism does what `classpath-suffix` used to do. For more
information, see link:#beadk[Using the Java Optional Package Mechanism].

[[gfqpi]][[GSDVG00095]][[delegation]]

=== 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 "link:application-deployment-guide/dd-elements.html#GSDPG00110[class-loader]" in {productName} 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 link:application-deployment-guide.html#GSDPG[{productName} 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 Jakarta EE platform.

[[beadk]][[GSDVG00096]][[using-the-java-optional-package-mechanism]]

=== 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 {productName} Reference Manual.

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

[[gchif]][[GSDVG00097]][[using-the-endorsed-standards-override-mechanism]]

=== 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
http://docs.oracle.com/javase/8/docs/technotes/guides/standards/[Endorsed
Standards Override Mechanism]
(`http://docs.oracle.com/javase/8/docs/technotes/guides/standards/`).

[[beadg]][[GSDVG00098]][[class-loader-universes]]

=== 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 Jakarta 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:
+
[source]
----
module-name/WEB-INF/classes
module-name/WEB-INF/lib
----

[[gatej]][[GSDVG00099]][[application-specific-class-loading]]

=== 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
link:reference-manual.html#GSRFM[{productName} Reference Manual].
* Use the `asadmin add-library` command with the `--type app` option,
then restart the server. For details, see the link:reference-manual.html#GSRFM[{productName} Reference Manual].


[NOTE]
====
None of these alternatives apply to application clients. For more
information, see link:java-clients.html#gjpjt[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 {productName} 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 {productName} 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
link:#beadh[Circumventing Class Loader Isolation].

One library cannot reference classes from another library.

For general information about deployment, including dynamic reloading,
see the link:application-deployment-guide.html#GSDPG[{productName} 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
link:securing-apps.html#beabz[Changing Permissions for an Application].
====


[[beadh]][[GSDVG00100]][[circumventing-class-loader-isolation]]

=== 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:

* link:#beadj[Using the Common Class Loader]
* link:#gcrnt[Sharing Libraries Across a Cluster]
* link:#beadl[Packaging the Client JAR for One Application in Another
Application]

[[beadj]][[GSDVG00342]][[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 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 {productName} 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
link:java-clients.html#gjpjt[Using Libraries with Application Clients].

For example, using the Common class loader is the recommended way of
adding JDBC drivers to the {productName}. For a list of the JDBC
drivers currently supported by the {productName}, see the
link:release-notes.html#GSRLN[{productName} Release Notes]. For
configurations of supported and other drivers, see
"link:administration-guide/jdbc.html#GSADG00579[Configuration Specifics for JDBC Drivers]" in
{productName} Administration Guide.

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

[[gcrnt]][[GSDVG00343]][[sharing-libraries-across-a-cluster]]

==== 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.

[[beadl]][[GSDVG00344]][[packaging-the-client-jar-for-one-application-in-another-application]]

==== 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 link:#beadj[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.

[[fvyab]][[GSDVG00048]][[to-package-the-client-jar-for-one-application-in-another-application]]

==== 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:
+
[source]
----
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 Jakarta 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.