docs/application-development-guide/src/main/jbake/content/class-loaders.adoc - glassfish - Git at Google


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


            * link:#beadf[The Class Loader Hierarchy]

            
            * link:#gfqpi[Delegation]

            
            * link:#beadk[Using the Java Optional Package Mechanism]

            
            * link:#gchif[Using the Endorsed Standards Override Mechanism]

            
            * link:#beadg[Class Loader Universes]

            
            * link:#gatej[Application-Specific Class Loading]

            
            * link:#beadh[Circumventing Class Loader Isolation]


            [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

            
            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 GlassFish Server 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 GlassFish Server.


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


            Table 2-1 Oracle GlassFish Server 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 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 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 Java 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 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 link:#gchif[Using the Endorsed Standards Override Mechanism] and the

            
            link:../reference-manual/deploy.html#GSRFM00114[`deploy`(1)] help page, respectively. 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 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 link:../application-deployment-guide/toc.html#GSDPG[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.


            [[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 GlassFish

            
            Server Open Source Edition 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 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: +

            
            [source,oac_no_warn]

            
            ----

            
            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/toc.html#GSRFM[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 link:../reference-manual/toc.html#GSRFM[GlassFish

            
            Server Open Source Edition 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 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

            
            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/toc.html#GSDPG[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

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

            
            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 GlassFish Server. For a list of the JDBC

            
            drivers currently supported by the GlassFish Server, see the

            
            link:../release-notes/toc.html#GSRLN[GlassFish Server Open Source Edition Release Notes]. For

            
            configurations of supported and other drivers, see

            
            "link:../administration-guide/jdbc.html#GSADG00579[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.


            [[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,oac_no_warn]

            
            ----

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

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


	[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
	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 GlassFish Server 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 GlassFish Server.

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


	Table 2-1 Oracle GlassFish Server 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 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 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 Java 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 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 link:#gchif[Using the Endorsed Standards Override Mechanism] and the
	link:../reference-manual/deploy.html#GSRFM00114[`deploy`(1)] help page, respectively. 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 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 link:../application-deployment-guide/toc.html#GSDPG[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.

	[[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 GlassFish
	Server Open Source Edition 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 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: +
	[source,oac_no_warn]
	----
	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/toc.html#GSRFM[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 link:../reference-manual/toc.html#GSRFM[GlassFish
	Server Open Source Edition 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 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
	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/toc.html#GSDPG[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
	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 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
	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 GlassFish Server. For a list of the JDBC
	drivers currently supported by the GlassFish Server, see the
	link:../release-notes/toc.html#GSRLN[GlassFish Server Open Source Edition Release Notes]. For
	configurations of supported and other drivers, see
	"link:../administration-guide/jdbc.html#GSADG00579[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.

	[[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,oac_no_warn]
	----
	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.