Chapter 14. Jakarta Connectors Management
14.1. About Jakarta connectors
Jakarta Connectors defines a standard architecture for Jakarta EE systems to interact with external heterogeneous Enterprise Information Systems (EIS). Examples of EISs include Enterprise Resource Planning (ERP) systems, mainframe transaction processing (TP), databases, and messaging systems. A resource adapter is a component that implements the Jakarta Connectors architecture.
Jakarta Connectors 1.7 provides features for managing:
- Connections
- Transactions
- Security
- Life-cycle
- Work instances
- Transaction inflow
- Message inflow
Additional resources
14.2. About resource adapters
A resource adapter is a deployable Jakarta EE component that provides communication between a Jakarta EE application and an Enterprise Information System (EIS) using the Jakarta Connectors specification. A resource adapter is often provided by EIS vendors to allow easy integration of their products with Jakarta EE applications.
An Enterprise Information System can be any other software system within an organization. Examples include Enterprise Resource Planning (ERP) systems, database systems, email servers, and proprietary messaging systems.
A resource adapter is packaged in a Resource Adapter Archive (RAR) file, which can be deployed to JBoss EAP. A RAR file may also be included in an Enterprise Archive (EAR) deployment.
The resource adapter itself is defined within the resource-adapters
subsystem, which is provided by the IronJacamar project.
14.3. Configuring the jca
Subsystem
The jca
subsystem controls the general settings for the Jakarta Connectors container and resource adapter deployments. You can configure the jca
subsystem using the management console or the management CLI.
The main jca
subsystem elements to configure are:
14.3.1. jca
subsystem settings in the management console
You can configure the jca
subsystem from the management console by navigating to Configuration
Configuration
Contains settings for the cached connection manager, archive validation, and bean validation. Modify these settings by opening the appropriate tab and clicking the Edit link.
Bootstrap Context
Contains the list of configured bootstrap contexts. New bootstrap context objects can be added, removed, and configured. Each bootstrap context must be assigned a work manager.
Workmanager
Contains the list of configured work managers. New work managers can be added, removed, and their thread pools configured here. Each work manager can have one short-running thread pool and an optional long-running thread pool.
The thread pool attributes can be configured by clicking Thread Pools on the selected work manager.
14.3.2. jca
subsystem settings in the management CLI
You can configure the jca
subsystem using the management CLI by following the steps in this procedure.
Procedure
-
Configure the
jca
subsystem using the management CLI:
/subsystem=jca
In a managed domain, you must precede the command with:
/profile=PROFILE_NAME
Attribute names in the tables in the following sections are listed as they appear in the management model, for example, when using the management CLI. See the schema definition file located at EAP_HOME/docs/schema/wildfly-jca_5_0.xsd
to view the elements as they appear in the XML, as there may be differences from the management model.
14.3.3. Archive validation
This determines whether archive validation will be performed on the deployment units. The following table describes the attributes you can set for archive validation.
Attribute | Default Value | Description |
---|---|---|
|
| Specifies whether archive validation is enabled. |
|
| Specifies whether an archive validation error report fails the deployment. |
|
| Specifies whether an archive validation warning report fails the deployment. |
If archive validation is not specified, it is considered present, and the enabled
attribute defaults to true
.
Example error messages during deployment
Severity: ERROR Section: 19.4.2 Description: A ResourceAdapter must implement a "public int hashCode()" method. Code: com.mycompany.myproject.ResourceAdapterImpl Severity: ERROR Section: 19.4.2 Description: A ResourceAdapter must implement a "public boolean equals(Object)" method. Code: com.mycompany.myproject.ResourceAdapterImpl
14.3.4. Bean validation
Bean validation determines whether bean validation is performed. For information about the specification, see the Jakarta Bean Validation specification.
Attribute | Default Value | Description |
---|---|---|
|
| Specifies whether bean validation is enabled. |
If bean validation is not specified, it is considered present, and the enabled
attribute defaults to true
.
14.3.5. Work managers
Work managers manage work instances within the Jakarta Connectors subsystem. There are two types of work managers:
Default work manager
The default work manager and its thread pools.
Custom work manager
A custom work manager definition and its thread pools.
Attribute | Description |
---|---|
| Specifies the name of the work manager. |
| Enables Elytron security for the work manager. |
A work manager also has the following child elements:
Child Element | Description |
---|---|
short-running-threads | Thread pool for standard Work instances. Each work manager has one short-running thread pool. |
long-running-threads |
Thread pool for Jakarta Connectors 1.7 Work instances that set the |
The following table describes the attributes you can set for work manager thread pools.
Attribute | Description |
---|---|
allow-core-timeout |
Boolean setting that determines whether core threads may time out. The default value is |
core-threads | The core thread pool size. This must be equal to or smaller than the maximum thread pool size. |
handoff-executor | An executor to delegate tasks to in the event that a task cannot be accepted. If not specified, tasks that cannot be accepted will be silently discarded. |
keepalive-time | Specifies the amount of time that pool threads should be kept after doing work. |
max-threads | The maximum thread pool size. |
name | Specifies the name of the thread pool. |
queue-length | The maximum queue length. |
thread-factory | Reference to the thread factory. |
14.3.6. Distributed work managers
A distributed work manager is a work manager instance that is able to reschedule work execution on another work manager instance.
The following example management CLI commands configure a distributed work manager. Note that you must use a configuration that provides high availability capabilities, such as the standalone-ha.xml
or standalone-full-ha.xml
configuration file for a standalone server.
Example: Configure a distributed work manager
batch /subsystem=jca/distributed-workmanager=myDistWorkMgr:add(name=myDistWorkMgr) /subsystem=jca/distributed-workmanager=myDistWorkMgr/short-running-threads=myDistWorkMgr:add(queue-length=10,max-threads=10) /subsystem=jca/bootstrap-context=myCustomContext:add(name=myCustomContext,workmanager=myDistWorkMgr) run-batch
The name of the short-running-threads
element must be the same as the name of the distributed-workmanager
element.
The following table describes the attributes you can configure for distributed work managers.
Attribute | Description |
---|---|
elytron-enabled | Enables Elytron security for the work manager. |
name | The name of the distributed work manager. |
policy | The policy decides when to redistribute a work instance. Allowed values are:
|
policy-options |
List of the policy’s key/value pair options. If you use the /subsystem=jca/distributed-workmanager=myDistWorkMgr:write-attribute(name=policy-options,value={watermark=3}) |
selector | The selector decides to which nodes in the network to redistribute the work instance. Allowed values are:
|
selector-options | List of the selector’s key/value pair options. |
A distributed work manager also has the following child elements.
Child Element | Description |
---|---|
long-running-threads |
The thread pool for work instances that set the |
short-running-threads | The thread pool for standard work instances. Each distributed work manager must have a short-running thread pool. |
14.3.7. Bootstrap Contexts
This is used to define custom bootstrap contexts. The following table describes the attributes you can set for bootstrap contexts.
Attribute | Description |
---|---|
name | Specifies the name of the bootstrap context. |
workmanager | Specifies the name of the work manager to use for this context. |
14.3.8. Cached connection manager
A cached connection manager is used for debugging connections and supporting lazy enlistment of a connection in a transaction, tracking whether they are used and released properly by the application. The following table describes the attributes you can set for the cached connection manager.
Attribute | Default Value | Description |
---|---|---|
debug | false | Outputs warning on failure to explicitly close connections. |
error | false | Throws exception on failure to explicitly close connections. |
ignore-unknown-connections | false | Specifies that unknown connections will not be cached. |
install | false | Enable or disable the cached connection manager valve and interceptor. |
14.3.9. Deploying a resource adapter using the management CLI
Use the management CLI to deploy a resource adapter.
Prerequisites
- Access to the management CLI.
Procedure
Deploy the resource adapter to a standalone server:
---- deploy /path/to/resource-adapter.rar ----
Deploy the resource adapter to all server groups in a managed domain:
---- deploy /path/to/resource-adapter.rar --all-server-groups ----
14.3.10. Deploying a resource adapter using the management console
Use the management console to deploy a resource adapter.
Prerequisites
- Access to the management console.
Procedure
- Log in to the management console.
- Navigate to the Deployments tab.
Click the Add (+) button.
- In a managed domain, you will first need to select Content Repository.
- Choose the Upload Deployment option.
- Browse to the resource adapter archive and click Next.
- Verify the upload, then click Finish.
- In a managed domain, deploy the deployment to the appropriate server groups and enable the deployment
14.3.11. Deploying a resource adapter using the deployment scanner
Deploy a resource adapter using the deployment scanner in a standalone server.
Prerequisites
- Access to the file system of the server.
Procedure
-
To deploy a resource adapter manually to a standalone server, copy the resource adapter archive to the server deployments directory, for example,
EAP_HOME/standalone/deployments/
. This will be picked up and deployed by the deployment scanner.
This option is not available for managed domains. You must use either the management console or the management CLI to deploy the resource adapter to server groups.
14.4. Configuring a resource adapter
You can configure resource adapters using the management interfaces. The below example shows how to configure a resource adapter using the management CLI. See your resource adapter vendor’s documentation for supported properties and other important information.
14.4.1. Adding the resource adapter configuration
Add the resource adapter configuration using the management CLI.
Prerequisites
- Access to the management CLI.
Procedure
Add the resource adapter configuration:
/subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)
14.4.2. Configuring the resource adapter settings
Resource adapter settings manage connections between the application server and external systems; configure them to optimize integration and performance.
Prerequisites
- The resource adapter configuration has been added.
- You have access to the management CLI.
Procedure
Configure
config-properties
:Add the
server
configuration property:---- /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=server:add(value=localhost) ----
Add the
port
configuration property:---- /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=port:add(value=9000) ----
Configure
admin-objects
:Add an admin object:
---- /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName:add(class-name=com.acme.eis.ra.EISAdminObjectImpl, jndi-name=java:/eis/AcmeAdminObject) ----
Configure an admin object configuration property:
---- /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName/config-properties=threshold:add(value=10) ----
Configure
connection-definitions
:Add a connection definition for a managed connection factory:
---- /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:add(class-name=com.acme.eis.ra.EISManagedConnectionFactory, jndi-name=java:/eis/AcmeConnectionFactory) ----
Configure a managed connection factory configuration property:
---- /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName/config-properties=name:add(value=Acme Inc) ----
Configure whether to record the enlistment trace:
Enable the recording of enlistment traces by setting the
enlistment-trace
attribute totrue
:---- /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:write-attribute(name=enlistment-trace,value=true) ----
WarningEnabling enlistment tracing makes tracking down errors during transaction enlistment easier, but comes with a performance impact.
Additional resources
- Resource Adapter Attributes for all available configuration options for resource adapters.
14.4.3. Activating the resource adapter
Activate the resource adapter after it has been configured.
Prerequisites
- The resource adapter has been configured.
- Access to the management CLI.
Procedure
Activate the resource adapter:
---- /subsystem=resource-adapters/resource-adapter=eis.rar:activate ----
You can also define capacity policies for resource adapters. For more details, see the Capacity Policies section.
14.5. Configuring resource adapters to use the Elytron subsystem
Resource adapters in IronJacamar involve two types of communications between the server and the resource adapter:
- One of the types is when the server opens a resource adapter connection. This can be secured by container-managed sign-on, which requires propagation of a JAAS subject with principal and credentials to the resource adapter when opening the connection. This sign-on can be delegated to Elytron.
- When a resource adapter establishes security information when submitting work to the work manager or delivering messages to endpoints within the same JBoss EAP instance. This mechanism is known as security inflow.
14.5.1. Container-managed sign-On with Elytron
In order to achieve container-managed sign-on with Elytron, the elytron-enabled
attribute needs to be set to true
. This will result in all connections to the resource adapter to be secured by Elytron.
/subsystem=resource-adapters/resource-adapter=<RAR_NAME>/connection-definitions=<FACTORY_NAME>:write-attribute(name=elytron-enabled,value=true)
The elytron-enabled
attribute can be configured using the management CLI by setting the elytron-enabled
attribute, in the resource-adapters
subsystems, to true
. By default this attribute is set to false
.
The authentication-context
attribute defines the name of the Elytron authentication context that will be used for performing sign-on.
An Elytron authentication-context
attribute can contain one or more authentication-configuration
elements, which in turn contains the credentials you want to use.
If the authentication-context
attribute is not set, JBoss EAP will use the current authentication-context
, which is the authentication-context
used by the caller code that is opening the connection.
Example: Creating an authentication-configuration
/subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
Example: Creating the authentication-context
Using the above Configuration
/subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
14.5.2. Security Inflow with Elytron
Security inflow enables a resource adapter to establish security information when submitting work to the work manager or delivering messages to endpoints within the same JBoss EAP instance. This allows the work to authenticate itself before execution using Elytron. If authentication succeeds, the submitted work will be executed under the resulting authentication context. If it fails, the work execution will be rejected.
To enable Elytron security inflow, set the wm-elytron-security-domain
attribute when configuring the resource adapter’s work manager.
-
When the resource adapter work manager is configured to use the Elytron security domain,
wm-elytron-security-domain
, the referenced work manager should have theelytron-enabled
attribute set totrue
.
/subsystem=jca/workmanager=customWM:add(name=customWM, elytron-enabled=true)
-
If instead of
wm-elytron-security-domain
thewm-security-domain
attribute is used, the security inflow will be performed by the legacysecurity
subsystem.
In the example configuration of jca
subsystem below, we can see the configuration of a resource adapter called ra-with-elytron-security-domain
. This resource adapter configures work manager security to use the Elytron security domain’s wm-realm
.
<subsystem xmlns="urn:jboss:domain:jca:5.0"> <archive-validation enabled="true" fail-on-error="true" fail-on-warn="false"/> <bean-validation enabled="true"/> <default-workmanager> <short-running-threads> <core-threads count="50"/> <queue-length count="50"/> <max-threads count="50"/> <keepalive-time time="10" unit="seconds"/> </short-running-threads> <long-running-threads> <core-threads count="50"/> <queue-length count="50"/> <max-threads count="50"/> <keepalive-time time="10" unit="seconds"/> </long-running-threads> </default-workmanager> <workmanager name="customWM"> <elytron-enabled>true</elytron-enabled> <short-running-threads> <core-threads count="20"/> <queue-length count="20"/> <max-threads count="20"/> </short-running-threads> </workmanager> <bootstrap-contexts> <bootstrap-context name="customContext" workmanager="customWM"/> </bootstrap-contexts> <cached-connection-manager/> </subsystem>
The work manager is then referenced using the boostrap context from the resource-adapter
subsystem.
<subsystem xmlns="urn:jboss:domain:resource-adapters:5.0"> <resource-adapters> <resource-adapter id="ra-with-elytron-security-domain"> <archive> ra-with-elytron-security-domain.rar </archive> <bootstrap-context>customContext</bootstrap-context> <transaction-support>NoTransaction</transaction-support> <workmanager> <security> <elytron-security-domain>wm-realm</elytron-security-domain> <default-principal>wm-default-principal</default-principal> <default-groups> <group> wm-default-group </group> </default-groups> </security> </workmanager> </resource-adapter> </resource-adapters> </subsystem>
Example: Configuration of the Security Domain
/subsystem=elytron/properties-realm=wm-properties-realm:add(users-properties={path=/security-dir/users.properties, plain-text=true}, groups-properties={path=/security-dir/groups.properties}) /subsystem=elytron/simple-role-decoder=wm-role-decoder:add(attribute=groups) /subsystem=elytron/constant-permission-mapper=wm-permission-mapper:add(permissions=[{class-name="org.wildfly.security.auth.permission.LoginPermission"}]) /subsystem=elytron/security-domain=wm-realm:add(default-realm=wm-properties-realm, permission-mapper=wm-permission-mapper, realms=[{role-decoder=wm-role-decoder, realm=wm-properties-realm}])
The Work
class is responsible for providing the credentials for Elytron’s authentication under the specified domain. For that, it must implement jakarta.resource.spi.work.WorkContextProvider
.
public interface WorkContextProvider { /** * Gets an instance of <code>WorkContexts</code> that needs to be used * by the <code>WorkManager</code> to set up the execution context while * executing a <code>Work</code> instance. * * @return an <code>List</code> of <code>WorkContext</code> instances. */ List<WorkContext> getWorkContexts(); }
This interface allows the Work
class to use the WorkContext
to configure some aspects of the context in which the work will be executed. One of those aspects is the security inflow. For that, the List<WorkContext> getWorkContexts
method must provide a jakarta.resource.spi.work.SecurityContext
. This context will use jakarta.security.auth.callback.Callback
objects as defined by Jakarta Authentication.
Example: Creation of Callbacks Using Context
public class ExampleWork implements Work, WorkContextProvider { private final String username; private final String role; public MyWork(TestBean bean, String username, String role) { this.principals = null; this.roles = null; this.bean = bean; this.username = username; this.role = role; } public List<WorkContext> getWorkContexts() { List<WorkContext> l = new ArrayList<>(1); l.add(new MySecurityContext(username, role)); return l; } public void run() { ... } public void release() { ... } public class ExampleSecurityContext extends SecurityContext { public void setupSecurityContext(CallbackHandler handler, Subject executionSubject, Subject serviceSubject) { try { List<jakarta.security.auth.callback.Callback> cbs = new ArrayList<>(); cbs.add(new CallerPrincipalCallback(executionSubject, new SimplePrincipal(username))); cbs.add(new GroupPrincipalCallback(executionSubject, new String[]{role})); handler.handle(cbs.toArray(new jakarta.security.auth.callback.Callback[cbs.size()])); } catch (Throwable t) { throw new RuntimeException(t); } } }
In the above example, ExampleWork
implements the WorkContextProvider
interface to provide ExampleSecurityContext
. That context will create the callbacks necessary to provide the security information that will be authenticated by Elytron upon work execution.
Additional resources
14.6. Configuring Managed Connection Pools
JBoss EAP provides three implementations of the ManagedConnectionPool
interface:
-
org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreConcurrentLinkedQueueManagedConnectionPool
: This is the default connection pool in JBoss EAP 7 and provides the best out-of-the-box performance. -
org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool
: This was the default connection pool in previous JBoss EAP versions. -
org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool
: This connection pool is used for debugging purposes only and will report any leaks upon shutdown or when the pool is flushed.
Prerequisites
- Access to the management CLI.
Procedure
Set the managed connection pool implementation for a datasource:
---- /subsystem=datasources/data-source=DATA_SOURCE:write-attribute(name=mcp,value=MCP_CLASS) ----
Set the managed connection pool implementation for a resource adapter:
---- /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:write-attribute(name=mcp,value=MCP_CLASS) ----
Set the managed connection pool implementation for a messaging server:
---- /subsystem=messaging-activemq/server=SERVER/pooled-connection-factory=CONNECTION_FACTORY:write-attribute(name=managed-connection-pool,value=MCP_CLASS) ----
14.7. Viewing connection statistics
Read statistics for a defined connection from the /deployment=NAME.rar
subtree. This allows you to access statistics for any RAR, even if it is not defined in a standalone.xml
or domain.xml
configuration.
Prerequisites
- Access to the management CLI.
Procedure
Run the following command to read the connection statistics:
---- /deployment=NAME.rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true) ----
Be sure to specify the include-runtime=true
argument, as all statistics are runtime-only information.
14.8. Flushing resource adapter connections
You can flush resource adapter connections using the following management CLI commands.
In a managed domain, you must precede these commands with /host=HOST_NAME/server=SERVER_NAME/
.
Prerequisites
- Access to the management CLI.
Procedure
Flush all connections in the pool:
---- /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-all-connection-in-pool ----
Gracefully flush all connections in the pool:
---- /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-gracefully-connection-in-pool ----
The server will wait until connections become idle before flushing them.
Flush all idle connections in the pool:
---- /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-idle-connection-in-pool ----
Flush all invalid connections in the pool:
---- /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-invalid-connection-in-pool ----
The server will flush all connections that it determines to be invalid.
Theses procedures are not sequential.
14.9. Additional resources
-
For tips on monitoring and optimizing performance for the
datasources
subsystem, see the Datasource and Resource Adapter Tuning section of the Performance tuning for JBoss EAP.