|
eap-runtime-artifacts
Supported JBoss EAP runtime artifacts.
jboss-eap-jakartaee8
Supported JBoss EAP Jakarta EE 8 APIs plus additional JBoss EAP API JARs.
jboss-eap-jakartaee8-with-tools
jboss-eap-jakartaee8
plus development tools such as Arquillian.
These BOMs from JBoss EAP 6 have been consolidated into fewer BOMs to make usage simpler for most use cases. The Hibernate, logging, transactions, messaging, and other public API JARs are now included in the
jboss-eap-jakartaee8
BOM instead of a requiring a separate BOM for each case.
The following example uses the
7.4.0.GA
version of the
jboss-eap-jakartaee8
BOM.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.bom</groupId>
<artifactId>jboss-eap-jakartaee8</artifactId>
<version>7.4.0.GA</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
JBoss EAP Client BOMs
The client BOMs do not create a dependency management section or define dependencies. Instead, they are an aggregate of other BOMs and are used to package the set of dependencies necessary for a remote client use case.
The
wildfly-ejb-client-bom
,
wildfly-jms-client-bom
, and
wildfly-jaxws-client-bom
are managed by the
jboss-eap-jakartaee8
BOM, so you do not need to manage the versions in your project dependencies.
The following is an example of how to add the
wildfly-ejb-client-bom
,
wildfly-jms-client-bom
, and
wildfly-jaxws-client-bom
dependencies to your project.
<dependencyManagement>
<dependencies>
<!-- JBoss stack of the Jakarta EE APIs and related components. -->
<dependency>
<groupId>org.jboss.bom</groupId>
<artifactId>jboss-eap-jakartaee8</artifactId>
<version>7.4.0.GA</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.eap</groupId>
<artifactId>wildfly-ejb-client-bom</artifactId>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.jboss.eap</groupId>
<artifactId>wildfly-jms-client-bom</artifactId>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.jboss.eap</groupId>
<artifactId>wildfly-jaxws-client-bom</artifactId>
<type>pom</type>
</dependency>
</dependencies>
For more information about Maven Dependencies and BOM POM files, see
Apache Maven Project - Introduction to the Dependency Mechanism
.
Chapter 3. Class Loading and Modules
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 Jakarta Enterprise Beans 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 Jakarta 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 Jakarta Enterprise Beans 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.
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 a Jakarta Enterprise Beans 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 Jakarta Enterprise Beans interceptors. Without this, a Jakarta Enterprise Beans 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 a Jakarta Enterprise Beans 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.4, 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
-
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.
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.
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
Dependencies: test.module annotations, other.module
-
Option 2: If you are adding a module dependency using
jboss-deployment-structure.xml
add
annotations="true"
on the module dependency.
An annotation index is required when an application wants to use annotated Jakarta EE components defined in classes within the static module. In JBoss EAP 7.4, 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, Jakarta Enterprise Beans, 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, Jakarta Enterprise Beans, 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
The example here shows the WAR plug-in but it also works with the JAR and Jakarta Enterprise Beans 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 a Jakarta Enterprise Beans 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.
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.
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 Jakarta Enterprise Beans 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.
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 Jakarta 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.
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.
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:
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. For more information see
modules and dependencies
.
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
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>
-
--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
.
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. Display Modules by Deployment
:list-modules
/deployment=ejb-in-ear.ear/subdeployment=ejb-in-ear-web.war:list-modules
/host=master/server=server-one/deployment=ejb-in-ear.ear/subdeployment=ejb-in-ear-web.war:list-modules
This operation displays the list in a compact view.
3.10. Class Loading Reference
3.10.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.2. 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
Jakarta Bean Validation
org.hibernate.validator
javax.validation.api
Core Server
javax.api
sun.jdk
org.jboss.vfs
ibm.jdk
DriverDependenciesProcessor
javax.transaction.api
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
Jakarta Enterprise Beans 3
javax.ejb.api
javax.xml.rpc.api
org.jboss.ejb-client
org.jboss.iiop-client
org.jboss.as.ejb3
org.wildfly.iiop-openjdk
org.omg.api
javax.rmi.api
javax.orb.api
Jakarta RESTful Web Services (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
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 Jakarta RESTful Web Services annotations in the deployment.
Jakarta Connectors
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.
Jakarta Persistence (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.
Jakarta 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.logging.log4j.api
org.apache.log4j
org.slf4j
org.jboss.logging.jul-to-slf4j-stub
javax.mail.api
javax.activation.api
Messaging
javax.jms.api
org.wildfly.extension.messaging-activemq
PicketLink Federation
org.picketlink
org.jboss.as.pojo
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 (Jakarta Contexts and Dependency Injection)
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.
|
Logging is the practice of recording a series of messages from an application that provides a record, or log, of the application’s activities.
Log messages provide important information for developers when debugging an application and for system administrators maintaining applications in production.
Most modern Java logging frameworks also include details such as the exact time and the origin of the message.
4.1.1. Supported Application Logging Frameworks
JBoss LogManager supports the following logging frameworks:
JBoss Logging (included with JBoss EAP)
Apache Commons Logging
Simple Logging Facade for Java (SLF4J)
Apache log4j
Java SE Logging (java.util.logging)
JBoss LogManager supports the following APIs:
JBoss Logging
commons-logging
SLF4J
Log4j
Log4j2
java.util.logging
JBoss LogManager also supports the following SPIs:
java.util.logging Handler
Log4j Appender
If you are using the
Log4j API
and a
Log4J Appender
, then Objects will be converted to
string
before being passed.
4.2. Logging with the JBoss Logging Framework
4.2.1. About JBoss Logging
JBoss Logging is the application logging framework that is included in JBoss EAP. It provides an easy way to add logging to an application. You add code to your application that uses the framework to send log messages in a defined format. When the application is deployed to an application server, these messages can be captured by the server and displayed or written to file according to the server’s configuration.
JBoss Logging provides the following features:
An innovative, easy-to-use typed logger. A typed logger is a logger interface annotated with
org.jboss.logging.annotations.MessageLogger
. For examples, see
Creating Internationalized Loggers, Messages and Exceptions
.
Full support for internationalization and localization. Translators work with message bundles in properties files while developers work with interfaces and annotations. For details, see
Internationalization and Localization
.
Build-time tooling to generate typed loggers for production and runtime generation of typed loggers for development.
4.2.2. Add Logging to an Application with JBoss Logging
This procedure demonstrates how to add logging to an application using JBoss Logging.
If you use Maven to build your project, you must configure Maven to use the JBoss EAP Maven repository. For more information, see
Configure the JBoss EAP Maven Repository
.
The JBoss Logging JAR files must be in the build path for your application.
If you build using Red Hat CodeReady Studio, select
Properties
from the
Project
menu, then select
Targeted Runtimes
and ensure the runtime for JBoss EAP is checked.
If you set the
Target runtime
to
7.4
or a later runtime version in Red Hat CodeReady Studio, your project is compatible with the Jakarta EE 8 specification.
If you use Maven to build your project, make sure you add the
jboss-logging
dependency to your project’s
pom.xml
file for access to the JBoss Logging framework:
<dependency>
<groupId>org.jboss.logging</groupId>
<artifactId>jboss-logging</artifactId>
<version>3.3.0.Final-redhat-1</version>
<scope>provided</scope>
</dependency>
The jboss-eap-jakartaee8 BOM manages the version of
jboss-logging
. For more details, see
Manage Project Dependencies
. See the
logging
quickstart that ships with JBoss EAP for a working example of logging in an application.
You do not need to include the JARs in your built application because JBoss EAP provides them to deployed applications.
For each class to which you want to add logging:
Add the import statements for the JBoss Logging class namespaces that you will be using. At a minimum you will need the following import:
import org.jboss.logging.Logger;
Create an instance of
org.jboss.logging.Logger
and initialize it by calling the static method
Logger.getLogger(Class)
. It is recommended to create this as a single instance variable for each class.
private static final Logger LOGGER = Logger.getLogger(HelloWorld.class);
Call the
Logger
object methods in your code where you want to send log messages.
The
Logger
has many different methods with different parameters for different types of messages. Use the following methods to send a log message with the corresponding log level and the
message
parameter as a string:
LOGGER.debug("This is a debugging message.");
LOGGER.info("This is an informational message.");
LOGGER.error("Configuration file not found.");
LOGGER.trace("This is a trace message.");
LOGGER.fatal("A fatal error occurred.");
For the complete list of JBoss Logging methods, see the
Logging API
documentation.
The following example loads customized configuration for an application from a properties file. If the specified file is not found, an
ERROR
level log message is recorded.
4.2.3. Adding the Apache Log4j2 API to your application
You can use an Apache Log4j2 API instead of an Apache Log4j API to send application logging messages to your JBoss LogManager implementation.
The JBoss EAP 7.4 release supports the Log4J2 API, but not the Apache Log4j2 Core implementation,
org.apache.logging.log4j:log4j-core
, or its configuration files.
Procedure
-
Add the
org.apache.logging.log4j:log4j-api
as a dependency to your project
pom.xml
file.
4.2.4. Creating a Log4j2 LogManager implementation
You can use your Log4j2 LogManager in your application by including the Log4j2 API in your project’s
pom.xml
file. Additionally, you must include the corresponding Log4j2 LogManager version in your project’s
pom.xml
file.
Procedure
-
Disable the Log4j
logging
dependencies by excluding the
org.apache.logging.log4j.api
module dependency in the
jboss-deployment-structure.xml
file.
Add the
log4j-api
dependency and the
log4j2
dependency to your project
pom.xml
file.
4.3. Per-deployment Logging
Per-deployment logging allows a developer to configure the logging configuration for their application in advance. When the application is deployed, logging begins according to the defined configuration. The log files created through this configuration contain information only about the behavior of the application.
If the per-deployment logging configuration is not done, the configuration from
logging
subsystem is used for all the applications as well as the server.
This approach has advantages and disadvantages over using system-wide logging. An advantage is that the administrator of the JBoss EAP instance does not need to configure any other logging than the server logging. A disadvantage is that the per-deployment logging configuration is read only on server startup, and so cannot be changed at runtime.
4.3.1. Add Per-deployment Logging to an Application
To configure per-deployment logging for an application, add the
logging.properties
configuration file to your deployment. This configuration file is recommended because it can be used with any logging facade where JBoss Log Manager is the underlying log manager.
The directory into which the configuration file is added depends on the deployment method.
For EAR deployments, copy the logging configuration file to the
META-INF/
directory.
For WAR or JAR deployments, copy the logging configuration file to the
WEB-INF/classes/
directory.
If you are using
Simple Logging Facade for Java (SLF4J)
or
Apache log4j
, the
logging.properties
configuration file is suitable. If you are using Apache log4j appenders then the configuration file
log4j.properties
is required. The configuration file
jboss-logging.properties
is supported only for legacy deployments.
Configuring logging.properties
The
logging.properties
file is used when the server boots, until the
logging
subsystem is started. If the
logging
subsystem is not included in your configuration, then the server uses the configuration in this file as the logging configuration for the entire server.
JBoss Log Manager Configuration Options
Logger options
-
loggers=<category>[,<category>,…]
- Specify a comma-separated list of logger categories to be configured. Any categories not listed here will not be configured from the following properties.
logger.<category>.level=<level>
- Specify the level for a category. The level can be one of the valid levels. If unspecified, the level of the nearest parent will be inherited.
logger.<category>.handlers=<handler>[,<handler>,…]
- Specify a comma-separated list of the handler names to be attached to this logger. The handlers must be configured in the same properties file.
logger.<category>.filter=<filter>
- Specify a filter for a category.
logger.<category>.useParentHandlers=(true|false)
- Specify whether log messages should cascade up to parent handlers. The default value is
true
.
|
