Chapter 3. Class Loading and Modules

3.1. Introduction

3.1.1. Overview of Class Loading and Modules

JBoss EAP uses a modular class loading system for controlling the class paths of deployed applications. This system provides more flexibility and control than the traditional system of hierarchical class loaders. Developers have fine-grained control of the classes available to their applications, and can configure a deployment to ignore classes provided by the application server in favor of their own.

The modular class loader separates all Java classes into logical groups called modules. Each module can define dependencies on other modules in order to have the classes from that module added to its own class path. Because each deployed JAR and WAR file is treated as a module, developers can control the contents of their application’s class path by adding module configuration to their application.

3.1.2. Class Loading in Deployments

For the purposes of class loading, JBoss EAP treats all deployments as modules. These are called dynamic modules. Class loading behavior varies according to the deployment type.

WAR Deployment

A WAR deployment is considered to be a single module. Classes in the WEB-INF/lib directory are treated the same as classes in the WEB-INF/classes directory. All classes packaged in the WAR will be loaded with the same class loader.

EAR Deployment

EAR deployments are made up of more than one module, and are defined by the following rules:

The lib/ directory of the EAR is a single module called the parent module.
Each WAR deployment within the EAR is a single module.
Each EJB JAR deployment within the EAR is a single module.

Subdeployment modules, for example the WAR and JAR deployments within the EAR, have an automatic dependency on the parent module. However, they do not have automatic dependencies on each other. This is called subdeployment isolation and can be disabled per deployment or for the entire application server.

Explicit dependencies between subdeployment modules can be added by the same means as any other module.

3.1.3. Class Loading Precedence

The JBoss EAP modular class loader uses a precedence system to prevent class loading conflicts.

During deployment, a complete list of packages and classes is created for each deployment and each of its dependencies. The list is ordered according to the class loading precedence rules. When loading classes at runtime, the class loader searches this list, and loads the first match. This prevents multiple copies of the same classes and packages within the deployments class path from conflicting with each other.

The class loader loads classes in the following order, from highest to lowest:

Implicit dependencies: These dependencies are automatically added by JBoss EAP, such as the JAVA EE APIs. These dependencies have the highest class loader precedence because they contain common functionality and APIs that are supplied by JBoss EAP.
See Implicit Module Dependencies for complete details about each implicit dependency.
Explicit dependencies: These dependencies are manually added to the application configuration using the application’s MANIFEST.MF file or the new optional JBoss deployment descriptor jboss-deployment-structure.xml file.
See Add an Explicit Module Dependency to a Deployment to learn how to add explicit dependencies.
Local resources: These are class files packaged up inside the deployment itself, for example in the WEB-INF/classes or WEB-INF/lib directories of a WAR file.
Inter-deployment dependencies: These are dependencies on other deployments in a EAR deployment. This can include classes in the lib directory of the EAR or classes defined in other EJB jars.

3.1.4. jboss-deployment-structure.xml

The jboss-deployment-structure.xml file is an optional deployment descriptor for JBoss EAP. This deployment descriptor provides control over class loading in the deployment.

The XML schema for this deployment descriptor is located in the product install directory under EAP_HOME/docs/schema/jboss-deployment-structure-1_2.xsd.

The key tasks that can be performed using this deployment descriptor are:

Defining explicit module dependencies.
Preventing specific implicit dependencies from loading.
Defining additional modules from the resources of that deployment.
Changing the subdeployment isolation behavior in that EAR deployment.
Adding additional resource roots to a module in an EAR.

3.2. Add an Explicit Module Dependency to a Deployment

Explicit module dependencies can be added to applications to add the classes of those modules to the class path of the application at deployment.

Note

JBoss EAP automatically adds some dependencies to deployments. See Implicit Module Dependencies for details.

Prerequisites

A working software project that you want to add a module dependency to.
You must know the name of the module being added as a dependency. See Included Modules for the list of static modules included with JBoss EAP. If the module is another deployment, then see Dynamic Module Naming in the JBoss EAP Configuration Guide to determine the module name.

Dependencies can be configured using two methods:

Adding entries to the MANIFEST.MF file of the deployment.
Adding entries to the jboss-deployment-structure.xml deployment descriptor.

Add a Dependency Configuration to MANIFEST.MF

Maven projects can be configured to create the required dependency entries in the MANIFEST.MF file.

If the project does not have one, create a file called MANIFEST.MF. For a web application (WAR), add this file to the META-INF/ directory. For an EJB archive (JAR), add it to the META-INF/ directory.
Add a dependencies entry to the MANIFEST.MF file with a comma-separated list of dependency module names:
```
Dependencies: org.javassist, org.apache.velocity, org.antlr
```
- To make a dependency optional, append optional to the module name in the dependency entry:
```
Dependencies: org.javassist optional, org.apache.velocity
```
- A dependency can be exported by appending export to the module name in the dependency entry:
```
Dependencies: org.javassist, org.apache.velocity export
```
- The annotations flag is needed when the module dependency contains annotations that need to be processed during annotation scanning, such as when declaring EJB interceptors. Without this, an EJB interceptor declared in a module cannot be used in a deployment. There are other situations involving annotation scanning when this is needed too.
```
Dependencies: org.javassist, test.module annotations
```
- By default items in the META-INF of a dependency are not accessible. The services dependency makes items from META-INF/services accessible so that services in the modules can be loaded.
```
Dependencies: org.javassist, org.hibernate services
```
- To scan a beans.xml file and make its resulting beans available to the application, the meta-inf dependency can be used.
```
Dependencies: org.javassist, test.module meta-inf
```

Add a Dependency Configuration to the jboss-deployment-structure.xml

If the application does not have one, create a new file called jboss-deployment-structure.xml and add it to the project. This file is an XML file with the root element of <jboss-deployment-structure>.
```
<jboss-deployment-structure>

</jboss-deployment-structure>
```
For a web application (WAR), add this file to the WEB-INF/ directory. For an EJB archive (JAR), add it to the META-INF/ directory.
Create a <deployment> element within the document root and a <dependencies> element within that.
Within the <dependencies> node, add a module element for each module dependency. Set the name attribute to the name of the module.
```
<module name="org.javassist" />
```
- A dependency can be made optional by adding the optional attribute to the module entry with the value of true. The default value for this attribute is false.
```
<module name="org.javassist" optional="true" />
```
- A dependency can be exported by adding the export attribute to the module entry with the value of true. The default value for this attribute is false.
```
<module name="org.javassist" export="true" />
```
- When the module dependency contains annotations that need to be processed during annotation scanning, the annotations flag is used.
```
<module name="test.module" annotations="true" />
```
- The services dependency specifies whether and how services found in this dependency are used. The default is none. Specifying a value of import for this attribute is equivalent to adding a filter at the end of the import filter list which includes the META-INF/services path from the dependency module. Setting a value of export for this attribute is equivalent to the same action on the export filter list.
```
<module name="org.hibernate" services="import" />
```
- The META-INF dependency specifies whether and how META-INF entries in this dependency are used. The default is none. Specifying a value of import for this attribute is equivalent to adding a filter at the end of the import filter list which includes the META-INF/** path from the dependency module. Setting a value of export for this attribute is equivalent to the same action on the export filter list.
```
<module name="test.module" meta-inf="import" />
```

Example: jboss-deployment-structure.xml File with Two Dependencies

<jboss-deployment-structure>
   <deployment>
      <dependencies>
         <module name="org.javassist" />
         <module name="org.apache.velocity" export="true" />
      </dependencies>
   </deployment>
</jboss-deployment-structure>

JBoss EAP adds the classes from the specified modules to the class path of the application when it is deployed.

Creating a Jandex Index

The annotations flag requires that the module contain a Jandex index. In JBoss EAP 7.1, this is generated automatically. However, adding the index manually is still recommended for performance reasons because automatic scanning can be a long process that consumes the CPU and increases the deployment time.

To add the index manually, create a new "index JAR" to add to the module. Use the Jandex JAR to build the index, and then insert it into a new JAR file. In the current implementation, when an index is added to a JAR file inside a module, no scanning at all is executed.

Creating a Jandex index::

Create the index:

java -jar modules/system/layers/base/org/jboss/jandex/main/jandex-jandex-2.0.0.Final-redhat-1.jar $JAR_FILE

Create a temporary working space:
```
mkdir /tmp/META-INF
```
Move the index file to the working directory
```
mv $JAR_FILE.ifx /tmp/META-INF/jandex.idx
```
1. Option 1: Include the index in a new JAR file
```
jar cf index.jar -C /tmp META-INF/jandex.idx
```
  Then place the JAR in the module directory and edit module.xml to add it to the resource roots.
2. Option 2: Add the index to an existing JAR
```
java -jar /modules/org/jboss/jandex/main/jandex-1.0.3.Final-redhat-1.jar -m $JAR_FILE
```
Tell the module import to utilize the annotation index, so that annotation scanning can find the annotations.
1. Option 1: If you are adding a module dependency using MANIFEST.MF, add annotations after the module name. For example change:
```
Dependencies: test.module, other.module
```
  to
```
Dependencies: test.module annotations, other.module
```
2. Option 2: If you are adding a module dependency using jboss-deployment-structure.xml add annotations="true" on the module dependency.
  Note
  An annotation index is required when an application wants to use annotated Java EE components defined in classes within the static module. In JBoss EAP 7.1, annotation indexes for static modules are automatically generated, so you do not need to create them. However, you must tell the module import to use the annotations by adding the dependencies to either the MANIFEST.MF or the jboss-deployment-structure.xml file.

3.3. Generate MANIFEST.MF entries using Maven

Maven projects using the Maven JAR, EJB, or WAR packaging plug-ins can generate a MANIFEST.MF file with a Dependencies entry. This does not automatically generate the list of dependencies, but only creates the MANIFEST.MF file with the details specified in the pom.xml.

Before generating the MANIFEST.MF entries using Maven, you will require:

A working Maven project, which is using one of the JAR, EJB, or WAR plug-ins (maven-jar-plugin, maven-ejb-plugin, or maven-war-plugin).
You must know the name of the project’s module dependencies. Refer to Included Modules for the list of static modules included with JBoss EAP. If the module is another deployment, then refer to Dynamic Module Naming in the JBoss EAP Configuration Guide to determine the module name.

Generate a MANIFEST.MF File Containing Module Dependencies

Add the following configuration to the packaging plug-in configuration in the project’s pom.xml file.

<configuration>
   <archive>
      <manifestEntries>
         <Dependencies></Dependencies>
      </manifestEntries>
   </archive>
</configuration>

Add the list of module dependencies to the <Dependencies> element. Use the same format that is used when adding the dependencies to the MANIFEST.MF file:
```
<Dependencies>org.javassist, org.apache.velocity</Dependencies>
```
The optional and export attributes can also be used here:
```
<Dependencies>org.javassist optional, org.apache.velocity export</Dependencies>
```

Build the project using the Maven assembly goal:

[Localhost ]$ mvn assembly:single

When the project is built using the assembly goal, the final archive contains a MANIFEST.MF file with the specified module dependencies.

Example: Configured Module Dependencies in pom.xml

Note

The example here shows the WAR plug-in but it also works with the JAR and EJB plug-ins (maven-jar-plugin and maven-ejb-plugin).

<plugins>
   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
         <archive>
            <manifestEntries>
               <Dependencies>org.javassist, org.apache.velocity</Dependencies>
            </manifestEntries>
         </archive>
      </configuration>
   </plugin>
</plugins>

3.4. Prevent a Module Being Implicitly Loaded

You can configure a deployable application to prevent implicit dependencies from being loaded. This can be useful when an application includes a different version of a library or framework than the one that will be provided by the application server as an implicit dependency.

Prerequisites

A working software project that you want to exclude an implicit dependency from.
You must know the name of the module to exclude. Refer to Implicit Module Dependencies for a list of implicit dependencies and their conditions.

Add dependency exclusion configuration to jboss-deployment-structure.xml

If the application does not have one, create a new file called jboss-deployment-structure.xml and add it to the project. This is an XML file with the root element of <jboss-deployment-structure>.
```
<jboss-deployment-structure>

</jboss-deployment-structure>
```
For a web application (WAR), add this file to the WEB-INF/ directory. For an EJB archive (JAR), add it to the META-INF/ directory.
Create a <deployment> element within the document root and an <exclusions> element within that.
```
<deployment>
   <exclusions>

   </exclusions>
</deployment>
```

Within the exclusions element, add a <module> element for each module to be excluded. Set the name attribute to the name of the module.

<module name="org.javassist" />

Example: Excluding Two Modules

<jboss-deployment-structure>
   <deployment>
      <exclusions>
         <module name="org.javassist" />
         <module name="org.dom4j" />
      </exclusions>
   </deployment>
</jboss-deployment-structure>

3.5. Exclude a Subsystem from a Deployment

Excluding a subsystem provides the same effect as removing the subsystem, but it applies only to a single deployment. You can exclude a subsystem from a deployment by editing the jboss-deployment-structure.xml configuration file.

Exclude a Subsystem

Edit the jboss-deployment-structure.xml file.

Add the following XML inside the <deployment> tags:

<exclude-subsystems>
  <subsystem name="SUBSYSTEM_NAME" />
</exclude-subsystems>

Save the jboss-deployment-structure.xml file.

The subsystem’s deployment unit processors will no longer run on the deployment.

Example: jboss-deployment-structure.xml File

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <ear-subdeployments-isolated>true</ear-subdeployments-isolated>
  <deployment>
    <exclude-subsystems>
      <subsystem name="jaxrs" />
    </exclude-subsystems>
    <exclusions>
      <module name="org.javassist" />
    </exclusions>
    <dependencies>
      <module name="deployment.javassist.proxy" />
      <module name="deployment.myjavassist" />
      <module name="myservicemodule" services="import"/>
    </dependencies>
    <resources>
      <resource-root path="my-library.jar" />
    </resources>
  </deployment>
  <sub-deployment name="myapp.war">
    <dependencies>
      <module name="deployment.myear.ear.myejbjar.jar" />
    </dependencies>
    <local-last value="true" />
  </sub-deployment>
  <module name="deployment.myjavassist" >
    <resources>
     <resource-root path="javassist.jar" >
       <filter>
         <exclude path="javassist/util/proxy" />
       </filter>
     </resource-root>
    </resources>
  </module>
  <module name="deployment.javassist.proxy" >
    <dependencies>
      <module name="org.javassist" >
        <imports>
          <include path="javassist/util/proxy" />
          <exclude path="/**" />
        </imports>
      </module>
    </dependencies>
  </module>
</jboss-deployment-structure>

3.6. Use the Class Loader Programmatically in a Deployment

3.6.1. Programmatically Load Classes and Resources in a Deployment

You can programmatically find or load classes and resources in your application code. The method you choose depends on a number of factors. This section describes the methods available and provides guidelines for when to use them.

Load a Class Using the Class.forName() Method

You can use the Class.forName() method to programmatically load and initialize classes. This method has two signatures:

Class.forName(String className):
This signature takes only one parameter, the name of the class you need to load. With this method signature, the class is loaded by the class loader of the current class and initializes the newly loaded class by default.
Class.forName(String className, boolean initialize, ClassLoader loader):
This signature expects three parameters: the class name, a boolean value that specifies whether to initialize the class, and the ClassLoader that should load the class.

The three argument signature is the recommended way to programmatically load a class. This signature allows you to control whether you want the target class to be initialized upon load. It is also more efficient to obtain and provide the class loader because the JVM does not need to examine the call stack to determine which class loader to use. Assuming the class containing the code is named CurrentClass, you can obtain the class’s class loader using CurrentClass.class.getClassLoader() method.

The following example provides the class loader to load and initialize the TargetClass class:

Class<?> targetClass = Class.forName("com.myorg.util.TargetClass", true, CurrentClass.class.getClassLoader());

Find All Resources with a Given Name

If you know the name and path of a resource, the best way to load it directly is to use the standard Java Development Kit (JDK) Class or ClassLoader API.

Load a single resource.
To load a single resource located in the same directory as your class or another class in your deployment, you can use the Class.getResourceAsStream() method.
```
InputStream inputStream = CurrentClass.class.getResourceAsStream("targetResourceName");
```
Load all instances of a single resource.
To load all instances of a single resource that are visible to your deployment’s class loader, use the Class.getClassLoader().getResources(String resourceName) method, where resourceName is the fully qualified path of the resource. This method returns an Enumeration of all URL objects for resources accessible by the class loader with the given name. You can then iterate through the array of URLs to open each stream using the openStream() method.
The following example loads all instances of a resource and iterates through the results.
```
Enumeration<URL> urls = CurrentClass.class.getClassLoader().getResources("full/path/to/resource");
while (urls.hasMoreElements()) {
    URL url = urls.nextElement();
    InputStream inputStream = null;
    try {
        inputStream = url.openStream();
        // Process the inputStream
        ...
    } catch(IOException ioException) {
        // Handle the error
    } finally {
        if (inputStream != null) {
            try {
                inputStream.close();
            } catch (Exception e) {
                // ignore
            }
        }
    }
}
```
Note
Because the URL instances are loaded from local storage, it is not necessary to use the openConnection() or other related methods. Streams are much simpler to use and minimize the complexity of the code.

Load a class file from the class loader.

If a class has already been loaded, you can load the class file that corresponds to that class using the following syntax:

InputStream inputStream = CurrentClass.class.getResourceAsStream(TargetClass.class.getSimpleName() + ".class");

If the class is not yet loaded, you must use the class loader and translate the path:

String className = "com.myorg.util.TargetClass"
InputStream inputStream = CurrentClass.class.getClassLoader().getResourceAsStream(className.replace('.', '/') + ".class");

3.6.2. Programmatically Iterate Resources in a Deployment

The JBoss Modules library provides several APIs for iterating all deployment resources. The JavaDoc for the JBoss Modules API is located here: http://docs.jboss.org/jbossmodules/1.3.0.Final/api/. To use these APIs, you must add the following dependency to the MANIFEST.MF:

Dependencies: org.jboss.modules

It is important to note that while these APIs provide increased flexibility, they also run much more slowly than a direct path lookup.

This section describes some of the ways you can programmatically iterate through resources in your application code.

List resources within a deployment and within all imports.
There are times when it is not possible to look up resources by the exact path. For example, the exact path might not be known or you might need to examine more than one file in a given path. In this case, the JBoss Modules library provides several APIs for iterating all deployment resources. You can iterate through resources in a deployment by utilizing one of two methods.
- Iterate all resources found in a single module.
  The ModuleClassLoader.iterateResources() method iterates all the resources within this module class loader. This method takes two arguments: the starting directory name to search and a boolean that specifies whether it should recurse into subdirectories.
  The following example demonstrates how to obtain the ModuleClassLoader and obtain the iterator for resources in the bin/ directory, recursing into subdirectories.
```
ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Iterator<Resource> mclResources = moduleClassLoader.iterateResources("bin",true);
```
  The resultant iterator can be used to examine each matching resource and query its name and size (if available), open a readable stream, or acquire a URL for the resource.
- Iterate all resources found in a single module and imported resources.
  The Module.iterateResources() method iterates all the resources within this module class loader, including the resources that are imported into the module. This method returns a much larger set than the previous method. This method requires an argument, which is a filter that narrows the result to a specific pattern. Alternatively, PathFilters.acceptAll() can be supplied to return the entire set.
  The following example demonstrates how to find the entire set of resources in this module, including imports.
```
ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Module module = moduleClassLoader.getModule();
Iterator<Resource> moduleResources = module.iterateResources(PathFilters.acceptAll());
```
Find all resources that match a pattern.
If you need to find only specific resources within your deployment or within your deployment’s full import set, you need to filter the resource iteration. The JBoss Modules filtering APIs give you several tools to accomplish this.
- Examine the full set of dependencies.
  If you need to examine the full set of dependencies, you can use the Module.iterateResources() method’s PathFilter parameter to check the name of each resource for a match.
- Examine deployment dependencies.
  If you need to look only within the deployment, use the ModuleClassLoader.iterateResources() method. However, you must use additional methods to filter the resultant iterator. The PathFilters.filtered() method can provide a filtered view of a resource iterator this case. The PathFilters class includes many static methods to create and compose filters that perform various functions, including finding child paths or exact matches, or matching an Ant-style "glob" pattern.

Additional code examples for filtering resources.

The following examples demonstrate how to filter resources based on different criteria.

Example: Find All Files Named messages.properties in Your Deployment

ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Iterator<Resource> mclResources = PathFilters.filtered(PathFilters.match("**/messages.properties"), moduleClassLoader.iterateResources("", true));

Example: Find All Files Named messages.properties in Your Deployment and Imports

ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Module module = moduleClassLoader.getModule();
Iterator<Resource> moduleResources = module.iterateResources(PathFilters.match("**/message.properties"));

Example: Find All Files Inside Any Directory Named my-resources in Your Deployment

ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Iterator<Resource> mclResources = PathFilters.filtered(PathFilters.match("**/my-resources/**"), moduleClassLoader.iterateResources("", true));

Example: Find All Files Named messages or errors in Your Deployment and Imports

ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Module module = moduleClassLoader.getModule();
Iterator<Resource> moduleResources = module.iterateResources(PathFilters.any(PathFilters.match("**/messages"), PathFilters.match("**/errors"));

Example: Find All Files in a Specific Package in Your Deployment

ModuleClassLoader moduleClassLoader = (ModuleClassLoader) TargetClass.class.getClassLoader();
Iterator<Resource> mclResources = moduleClassLoader.iterateResources("path/form/of/packagename", false);

3.7. Class Loading and Subdeployments

3.7.1. Modules and Class Loading in Enterprise Archives

Enterprise Archives (EAR) are not loaded as a single module like JAR or WAR deployments. They are loaded as multiple unique modules.

The following rules determine what modules exist in an EAR:

The contents of the lib/ directory in the root of the EAR archive is a module. This is called the parent module.
Each WAR and EJB JAR subdeployment is a module. These modules have the same behavior as any other module as well as implicit dependencies on the parent module.
Subdeployments have implicit dependencies on the parent module and any other non-WAR subdeployments.

The implicit dependencies on non-WAR subdeployments occur because JBoss EAP has subdeployment class loader isolation disabled by default. Dependencies on the parent module persist, regardless of subdeployment class loader isolation.

Important

No subdeployment ever gains an implicit dependency on a WAR subdeployment. Any subdeployment can be configured with explicit dependencies on another subdeployment as would be done for any other module.

Subdeployment class loader isolation can be enabled if strict compatibility is required. This can be enabled for a single EAR deployment or for all EAR deployments. The Java EE specification recommends that portable applications should not rely on subdeployments being able to access each other unless dependencies are explicitly declared as Class-Path entries in the MANIFEST.MF file of each subdeployment.

3.7.2. Subdeployment Class Loader Isolation

Each subdeployment in an Enterprise Archive (EAR) is a dynamic module with its own class loader. By default, a subdeployment can access the resources of other subdeployments.

If a subdeployment is not to be allowed to access the resources of other subdeployments, strict subdeployment isolation can be enabled.

3.7.3. Enable Subdeployment Class Loader Isolation Within a EAR

This task shows you how to enable subdeployment class loader isolation in an EAR deployment by using a special deployment descriptor in the EAR. This does not require any changes to be made to the application server and does not affect any other deployments.

Important

Even when subdeployment class loader isolation is disabled, it is not possible to add a WAR deployment as a dependency.

Add the deployment descriptor file.
Add the jboss-deployment-structure.xml deployment descriptor file to the META-INF directory of the EAR if it doesn’t already exist and add the following content:
```
<jboss-deployment-structure>

</jboss-deployment-structure>
```
Add the <ear-subdeployments-isolated> element.
Add the <ear-subdeployments-isolated> element to the jboss-deployment-structure.xml file if it doesn’t already exist with the content of true.
```
<ear-subdeployments-isolated>true</ear-subdeployments-isolated>
```

Subdeployment class loader isolation is now enabled for this EAR deployment. This means that the subdeployments of the EAR will not have automatic dependencies on each of the non-WAR subdeployments.

3.7.4. Configuring Session Sharing between Subdeployments in Enterprise Archives

JBoss EAP provides the ability to configure enterprise archives (EARs) to share sessions between WAR module subdeployments contained in the EAR. This functionality is disabled by default and must be explicitly enabled in the META-INF/jboss-all.xml file in the EAR.

Important

Since this feature is not a standard servlet feature, your applications might not be portable if this functionality is enabled.

To enable session sharing between WARs within an EAR, you need to declare a shared-session-config element in the META-INF/jboss-all.xml of the EAR:

Example: META-INF/jboss-all.xml

<jboss xmlns="urn:jboss:1.0">
  ...
  <shared-session-config xmlns="urn:jboss:shared-session-config:1.0">
  </shared-session-config>
  ...
</jboss>

The shared-session-config element is used to configure the shared session manager for all WARs within the EAR. If the shared-session-config element is present, all WARs within the EAR will share the same session manager. Changes made here will affect all the WARs contained within the EAR.

3.7.4.1. Reference of Shared Session Configuration Options

Example: META-INF/jboss-all.xml

<jboss xmlns="urn:jboss:1.0">
    <shared-session-config xmlns="urn:jboss:shared-session-config:1.0">
        <max-active-sessions>10</max-active-sessions>
        <session-config>
            <session-timeout>0</session-timeout>
            <cookie-config>
                <name>JSESSIONID</name>
                <domain>domainName</domain>
                <path>/cookiePath</path>
                <comment>cookie comment</comment>
                <http-only>true</http-only>
                <secure>true</secure>
                <max-age>-1</max-age>
            </cookie-config>
            <tracking-mode>COOKIE</tracking-mode>
        </session-config>
        <replication-config>
            <cache-name>web</cache-name>
            <replication-granularity>SESSION</replication-granularity>
        </replication-config>
    </shared-session-config>
</jboss>

Element	Description
shared-session-config	Root element for the shared session configuration. If this is present in the `META-INF/jboss-all.xml`, then all deployed WARs contained in the EAR will share a single session manager.
max-active-sessions	Number of maximum sessions allowed.
session-config	Contains the session configuration parameters for all deployed WARs contained in the EAR.
session-timeout	Defines the default session timeout interval for all sessions created in the deployed WARs contained in the EAR. The specified timeout must be expressed in a whole number of minutes. If the timeout is 0 or less, the container ensures the default behavior of sessions is to never time out. If this element is not specified, the container must set its default timeout period.
cookie-config	Contains the configuration of the session tracking cookies created by the deployed WARs contained in the EAR.
name	The name that will be assigned to any session tracking cookies created by the deployed WARs contained in the EAR. The default is `JSESSIONID`.
domain	The domain name that will be assigned to any session tracking cookies created by the deployed WARs contained in the EAR.
path	The path that will be assigned to any session tracking cookies created by the deployed WARs contained in the EAR.
comment	The comment that will be assigned to any session tracking cookies created by the deployed WARs contained in the EAR.
http-only	Specifies whether any session tracking cookies created by the deployed WARs contained in the EAR will be marked as `HttpOnly`.
secure	Specifies whether any session tracking cookies created by the deployed WARs contained in the EAR will be marked as secure even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS.
max-age	The lifetime (in seconds) that will be assigned to any session tracking cookies created by the deployed WARs contained in the EAR. Default is `-1`.
tracking-mode	Defines the tracking modes for sessions created by the deployed WARs contained in the EAR.
replication-config	Contains the HTTP session clustering configuration.
cache-name	This option is for use in clustering only. It specifies the name of the Infinispan container and cache in which to store session data. The default value, if not explicitly set, is determined by the application server. To use a specific cache within a cache container, use the form `container.cache`, for example `web.dist`. If name is unqualified, the default cache of the specified container is used.
replication-granularity	This option is for use in clustering only. It determines the session replication granularity level. The possible values are `SESSION` and `ATTRIBUTE` with `SESSION` being the default. If `SESSION` granularity is used, all session attributes are replicated if any were modified within the scope of a request. This policy is required if an object reference is shared by multiple session attributes. However, this can be inefficient if session attributes are sufficiently large and/or are modified infrequently, since all attributes must be replicated regardless of whether they were modified or not. If `ATTRIBUTE` granularity is used, only those attributes that were modified within the scope of a request are replicated. This policy is not appropriate if an object reference is shared by multiple session attributes. This can be more efficient than `SESSION` granularity if the session attributes are sufficiently large and/or are modified infrequently.

3.8. Deploy Tag Library Descriptors (TLDs) in a Custom Module

If you have multiple applications that use common Tag Library Descriptors (TLDs), it might be useful to separate the TLDs from the applications so that they are located in one central and unique location. This enables easier additions and updates to TLDs without necessarily having to update each individual application that uses them.

This can be done by creating a custom JBoss EAP module that contains the TLD JARs, and declaring a dependency on that module in the applications.

Note

Ensure that at least one JAR contains TLDs and that the TLDs are packed in META-INF.

Deploy TLDs in a Custom Module

Using the management CLI, connect to your JBoss EAP instance and execute the following command to create the custom module containing the TLD JAR:
```
module add --name=MyTagLibs --resources=/path/to/TLDarchive.jar
```
Important
Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment. For more information, see the Create a Custom Module Manually and Remove a Custom Module Manually sections of the JBoss EAP Configuration Guide.
Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
If the TLDs are packaged with classes that require dependencies, use the --dependencies option to ensure that you specify those dependencies when creating the custom module.
When creating the module, you can specify multiple JAR resources by separating each one with the file system-specific separator for your system.
- For linux - :. Example, --resources=<path-to-jar>:<path-to-another-jar>
- For Windows - ;. Example, --resources=<path-to-jar>;<path-to-another-jar>
  Note
  --resources
  It is required unless --module-xml is used. It lists file system paths, usually JAR files, separated by a file system-specific path separator, for example java.io.File.pathSeparatorChar. The files specified will be copied to the created module’s directory.
  --resource-delimiter
  It is an optional user-defined path separator for the resources argument. If this argument is present, the command parser will use the value here instead of the file system-specific path separator. This allows the modules command to be used in cross-platform scripts.
In your applications, declare a dependency on the new MyTagLibs custom module using one of the methods described in Add an Explicit Module Dependency to a Deployment.

Important

Ensure that you also import META-INF when declaring the dependency. For example, for MANIFEST.MF:

Dependencies: com.MyTagLibs meta-inf

Or, for jboss-deployment-structure.xml, use the meta-inf attribute.

3.9. Class Loading Reference

3.9.1. Implicit Module Dependencies

The following table lists the modules that are automatically added to deployments as dependencies and the conditions that trigger the dependency.

Table 3.1. Implicit Module Dependencies
Subsystem Responsible for Adding the Dependency	Package Dependencies That Are Always Added	Package Dependencies That Are Conditionally Added	Conditions That Trigger the Addition of the Dependency
Application Client	org.omg.api org.jboss.xnio
Batch	javax.batch.api org.jberet.jberet-core org.wildfly.jberet
Bean Validation	org.hibernate.validator javax.validation.api
Core Server	javax.api sun.jdk org.jboss.vfs ibm.jdk
DriverDependenciesProcessor		javax.transaction.api
EE	org.jboss.invocation (except org.jboss.invocation.proxy.classloading) org.jboss.as.ee (except org.jboss.as.ee.component.serialization, org.jboss.as.ee.concurrent, org.jboss.as.ee.concurrent.handle) org.wildfly.naming javax.annotation.api javax.enterprise.concurrent.api javax.interceptor.api javax.json.api javax.resource.api javax.rmi.api javax.xml.bind.api javax.api org.glassfish.javax.el org.glassfish.javax.enterprise.concurrent
EJB 3	javax.ejb.api javax.xml.rpc.api org.jboss.ejb-client org.jboss.iiop-client org.jboss.as.ejb3	org.wildfly.iiop-openjdk
IIOP	org.omg.api javax.rmi.api javax.orb.api
JAX-RS (RESTEasy)	javax.xml.bind.api javax.ws.rs.api javax.json.api org.jboss.resteasy.resteasy-atom-provider org.jboss.resteasy.resteasy-crypto org.jboss.resteasy.resteasy-validator-provider-11 org.jboss.resteasy.resteasy-jaxrs org.jboss.resteasy.resteasy-jaxb-provider org.jboss.resteasy.resteasy-jackson2-provider org.jboss.resteasy.resteasy-jsapi org.jboss.resteasy.resteasy-json-p-provider org.jboss.resteasy.resteasy-multipart-provider org.jboss.resteasy.resteasy-yaml-provider org.codehaus.jackson.jackson-core-asl	org.jboss.resteasy.resteasy-cdi	The presence of JAX-RS annotations in the deployment.
JCA	javax.resource.api	javax.jms.api javax.validation.api org.jboss.ironjacamar.api org.jboss.ironjacamar.impl org.hibernate.validator	The deployment of a resource adapter (RAR) archive.
JPA (Hibernate)	javax.persistence.api	org.jboss.as.jpa org.jboss.as.jpa.spi org.javassist	The presence of an `@PersistenceUnit` or `@PersistenceContext` annotation, or a `<persistence-unit-ref>` or `<persistence-context-ref>` element in a deployment descriptor. JBoss EAP maps persistence provider names to module names. If you name a specific provider in the `persistence.xml` file, a dependency is added for the appropriate module. If this not the desired behavior, you can exclude it using a `jboss-deployment-structure.xml` file.
JSF (Java Server Faces)		javax.faces.api com.sun.jsf-impl org.jboss.as.jsf org.jboss.as.jsf-injection	Added to EAR applications. Added to WAR applications only if the `web.xml` file does NOT specify a `context-param` of `org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL` with a value of `true`.
JSR-77	javax.management.j2ee.api
Logging	org.jboss.logging org.apache.commons.logging org.apache.log4j org.slf4j org.jboss.logging.jul-to-slf4j-stub
Mail	javax.mail.api javax.activation.api
Messaging	javax.jms.api	org.wildfly.extension.messaging-activemq
PicketLink Federation		org.picketlink
Pojo	org.jboss.as.pojo
SAR		org.jboss.modules org.jboss.as.system-jmx org.jboss.common-beans	The deployment of a SAR archive that has a `jboss-service.xml`.
Seam2		org.jboss.vfs	.
Security	org.picketbox org.jboss.as.security javax.security.jacc.api javax.security.auth.message.api
ServiceActivator		org.jboss.msc
Transactions	javax.transaction.api	org.jboss.xts org.jboss.jts org.jboss.narayana.compensations
Undertow	javax.servlet.jstl.api javax.servlet.api javax.servlet.jsp.api javax.websocket.api	io.undertow.core io.undertow.servlet io.undertow.jsp io.undertow.websocket io.undertow.js org.wildfly.clustering.web.api
Web Services	javax.jws.api javax.xml.soap.api javax.xml.ws.api	org.jboss.ws.api org.jboss.ws.spi	If it is not application client type, then it will add the conditional dependencies.
Weld (CDI)	javax.enterprise.api javax.inject.api	javax.persistence.api org.javassist org.jboss.as.weld org.jboss.weld.core org.jboss.weld.probe org.jboss.weld.api org.jboss.weld.spi org.hibernate.validator.cdi	The presence of a `beans.xml` file in the deployment.

3.9.2. Included Modules

For the complete listing of the included modules and whether they are supported, see Red Hat JBoss Enterprise Application Platform 7 Included Modules on the Red Hat Customer Portal.

3.1. Introduction

3.1.1. Overview of Class Loading and Modules

3.1.2. Class Loading in Deployments

3.1.3. Class Loading Precedence

3.1.4. jboss-deployment-structure.xml

3.2. Add an Explicit Module Dependency to a Deployment

Prerequisites

Add a Dependency Configuration to MANIFEST.MF

Add a Dependency Configuration to the jboss-deployment-structure.xml

Creating a Jandex Index

3.3. Generate MANIFEST.MF entries using Maven

Generate a MANIFEST.MF File Containing Module Dependencies

3.4. Prevent a Module Being Implicitly Loaded

3.5. Exclude a Subsystem from a Deployment

3.6. Use the Class Loader Programmatically in a Deployment

3.6.1. Programmatically Load Classes and Resources in a Deployment

3.6.2. Programmatically Iterate Resources in a Deployment

3.7. Class Loading and Subdeployments

3.7.1. Modules and Class Loading in Enterprise Archives

3.7.2. Subdeployment Class Loader Isolation

3.7.3. Enable Subdeployment Class Loader Isolation Within a EAR

3.7.4. Configuring Session Sharing between Subdeployments in Enterprise Archives

3.7.4.1. Reference of Shared Session Configuration Options

3.8. Deploy Tag Library Descriptors (TLDs) in a Custom Module

Deploy TLDs in a Custom Module

3.9. Class Loading Reference

3.9.1. Implicit Module Dependencies

3.9.2. Included Modules

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links