Understanding Application 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:
Class loaders in the Application 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 Application Server.Table 2–1 Sun Java System Application Server Class Loaders
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.
The System class loader loads Application 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 Admin Console, select the Application Server component, the JVM Settings tab, and the Path Settings tab, then edit the System Classpath field. See Using the System Class Loader and java-config in Sun Java System Application Server Platform Edition 9 Administration Reference.
The Shared Chain class loader loads most of the core Application 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 Admin Console, select the Application Server component, the JVM Settings tab, and the Path Settings tab, then 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 Application Server implementation classes in the shared chain. The classpath-prefix is ideal for placing development and diagnostic patches. Use classpath-suffix to place libraries after implementation classes in the shared chain.
The MBean class loader loads the MBean implementation classes. See MBean Class Loading.
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.
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.
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.
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:
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.
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.
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.
Note that this 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 Java System Application Server Platform Edition 9 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 The sun-web.xml File in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
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.
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.
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:
In iPlanetTM Application Server 6.x, individually deployed modules shared the same class loader. In subsequent Application Server versions, each individually deployed module has its own class loader universe.
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. Type the path in the Libraries field. For details, click the Help button in the Admin Console.
Use the asadmin deploy command with the --libraries option. For details, see the Sun Java System Application Server Platform Edition 9 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).
You can use application-specific class loading to specify a different XML parser than the default Application Server XML parser. For details, see http://blogs.sun.com/sivakumart/.
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 Java System Application Server Platform Edition 9 Application Deployment Guide.
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.
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 any other application or module across the domain.
To use the System class loader, do one of the following, then restart the server:
Use the Admin Console. Select the Application Server component, select the JVM Settings tab, 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 Java System Application Server Platform Edition 9 Administration Reference.
Using the System class loader makes an application or module accessible to any other application or module across the domain.
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 any other application or module across the domain.
For example, using the Common class loader is the recommended way of adding JDBC drivers to the Application Server. For a list of the JDBC drivers currently supported by the Application Server, see the Sun Java System Application Server Platform Edition 9 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers in Sun Java System Application Server Platform Edition 9 Administration Guide.
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 across the domain.
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.
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.