Chapter 16. Jakarta Connectors Management 16.1. About Jakarta Connectors Jakarta Connectors define a standard architecture for Jakarta EE systems to 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 16.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, e-mail 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. 16.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: Archive validation Bean validation Work managers Distributed work managers Bootstrap contexts Cached connection manager Configure jca subsystem settings from the management console The jca subsystem can be configured from the management console by navigating to Configuration Subsystems JCA and clicking View . Then, select the appropriate tab: Configuration - Contains settings for the cached connection manager, archive validation, and bean validation. Each of these is contained in their own tab as well. 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. Configure jca subsystem settings from the management CLI The jca subsystem can be configured from the management CLI from the /subsystem=jca address. In a managed domain, you must precede the command with /profile= PROFILE_NAME . Note 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. 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. Table 16.1. Archive Validation Attributes Attribute Default Value Description enabled true Specifies whether archive validation is enabled. fail-on-error true Specifies whether an archive validation error report fails the deployment. fail-on-warn false Specifies whether an archive validation warning report fails the deployment. If an archive does not implement the Jakarta Connectors specification correctly and archive validation is enabled, an error message will display during deployment describing the problem. For example: If archive validation is not specified, it is considered present and the enabled attribute defaults to true . Bean Validation This setting determines whether bean validation is performed. For information about the specification, see in Jakarta Bean Validation specification . The following table describes the attributes you can set for bean validation. Table 16.2. Bean Validation Attributes Attribute Default Value Description enabled true Specifies whether bean validation is enabled. If bean validation is not specified, it is considered present and the enabled attribute defaults to true . Work Managers 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. The following table describes the attributes you can set for work managers. Table 16.3. Work Manager Attributes Attribute Description name Specifies the name of the work manager. elytron-enabled This attribute enables Elytron security for the workmanager . A work manager also has the following child elements. Table 16.4. Work Manager 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 LONG_RUNNING hint. Each work manager can have one optional long-running thread pool. The following table describes the attributes you can set for work manager thread pools. Table 16.5. Thread Pool Attributes Attribute Description allow-core-timeout Boolean setting that determines whether core threads may time out. The default value is false . 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. 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 Note 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. Table 16.6. Distributed Work Manager Attributes 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: NEVER - Never distribute the work instance to another node. ALWAYS - Always distribute the work instance to another node. WATERMARK - Distribute the work instance to another node based on how many free worker threads the current node has available. policy-options List of the policy's key/value pair options. If you use the WATERMARK policy, then you can use the watermark policy option to specify at what number of free threads that work should be distributed. For example: selector The selector decides to which nodes in the network to redistribute the work instance. Allowed values are: FIRST_AVAILABLE - Select the first available node in the list. PING_TIME - Select the node with the lowest ping time. MAX_FREE_THREADS - Select the node with highest number of free worker threads. selector-options List of the selector's key/value pair options. A distributed work manager also has the following child elements. Table 16.7. Distributed Work Manager Child Elements Child Element Description long-running-threads The thread pool for work instances that set the LONG_RUNNING hint. Each distributed work manager can optionally have a long-running thread pool. short-running-threads The thread pool for standard work instances. Each distributed work manager must have a short-running thread pool. Bootstrap Contexts This is used to define custom bootstrap contexts. The following table describes the attributes you can set for bootstrap contexts. Table 16.8. Bootstrap Context Attributes Attribute Description name Specifies the name of the bootstrap context. workmanager Specifies the name of the work manager to use for this context. Cached Connection Manager This 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. Table 16.9. Cached Connection Manager Attributes 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. 16.4. Configuring Resource Adapters 16.4.1. Deploy a Resource Adapter Resource adapters can be deployed just like other deployments using the management CLI or the management console. When running a standalone server, you can also copy the archive to the deployments directory to be picked up by the deployment scanner. Deploy a Resource Adapter using the Management CLI To deploy the resource adapter to a standalone server, enter the following management CLI command. To deploy the resource adapter to all server groups in a managed domain, enter the following management CLI command. Deploy a Resource Adapter using the Management Console Log in to the management console and click on 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 . Verify the upload, then click Finish . In a managed domain, deploy the deployment to the appropriate server groups and enable the deployment. Deploy a Resource Adapter Using the Deployment Scanner 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. Note 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. 16.4.2. Configure 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. Add the Resource Adapter Configuration Add the resource adapter configuration. Configure the Resource Adapter Settings Configure any of the following settings as necessary. Configure config-properties . Add the server configuration property. Add the port configuration property. Configure admin-objects . Add an admin object. Configure an admin object configuration property. Configure connection-definitions . Add a connection definition for a managed connection factory. Configure a managed connection factory configuration property. Configure whether to record the enlistment trace. You can enable the recording of enlistment traces by setting the enlistment-trace attribute to true . Warning Enabling enlistment tracing makes tracking down errors during transaction enlistment easier, but comes with a performance impact. See Resource Adapter Attributes for all available configuration options for resource adapters. Activate the Resource Adapter Activate the resource adapter. Note You can also define capacity policies for resource adapters. For more details, see the Capacity Policies section. 16.4.3. Configure Resource Adapters to Use the Elytron Subsystem Two types of communications occur between the server and the resource adapter in IronJacamar. One of them is when the server opens a resource adapter connection. As defined by the specifications, 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. IronJacamar supports security inflow. This mechanism enables a resource adapter to establish security information when submitting a work to the work manager, and when delivering messages to endpoints residing in the same JBoss EAP instance. Container-managed Sign-On 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. 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 Example: Creating the authentication-context Using the above Configuration Security Inflow It is also possible for the resource manager to inflow security credentials when submitting the work which is to be executed by the work manager. Security inflow allows the work to authenticate itself before execution. 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 work manager. Elytron will perform the authentication based on the specified domain. Note When the resource adapter work manager is configured to use the Elytron security domain, wm-elytron-security-domain , the referenced work manager should have the elytron-enabled attribute set to true . Note If instead of wm-elytron-security-domain the wm-security-domain attribute is used, the security inflow will be performed by the legacy security 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 The Work class is responsible for providing the credentials for Elytron's authentication under the specified domain. For that, it must implement javax.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 javax.resource.spi.work.SecurityContext . This context will use javax.security.auth.callback.Callback objects as defined by Jakarta Authentication. For more information about the specification, see Jakarta Authentication specification . 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<javax.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 javax.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. 16.4.4. Deploy and Configure the IBM MQ Resource Adapter You can find the instructions for deploying the IBM MQ resource adapter in Configuring Messaging for JBoss EAP. 16.4.5. Deploy and Configure the Generic Jakarta Messaging Resource Adapter You can find the instructions for configuring the generic Jakarta Messaging resource adapter in Configuring Messaging for JBoss EAP. 16.5. Configure 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 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. You can set the managed connection pool implementation for a datasource using the following management CLI command. You can set the managed connection pool implementation for a resource adapter using the following management CLI command. You can set the managed connection pool implementation for a messaging server using the following management CLI command. 16.6. View Connection Statistics You can read statistics for a defined connection from the /deployment= NAME .rar subtree. This is so that you can access statistics for any RAR, even if it not defined in a standalone.xml or domain.xml configuration. Note Be sure to specify the include-runtime=true argument, as all statistics are runtime-only information. See Resource Adapter Statistics for information on the available statistics. 16.7. Flushing Resource Adapter Connections You can flush resource adapter connections using the following management CLI commands. Note In a managed domain, you must precede these commands with /host= HOST_NAME /server= SERVER_NAME . Flush all connections in the pool. Gracefully flush all connections in the pool. The server will wait until connections become idle before flushing them. Flush all idle connections in the pool. Flush all invalid connections in the pool. The server will flush all connections that it determines to be invalid. 16.8. Tuning the Resource Adapters Subsystem For tips on monitoring and optimizing performance for the resource-adapters subsystem, see the Datasource and Resource Adapter Tuning section of the Performance Tuning Guide .

Commands:
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
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
/subsystem=jca/distributed-workmanager=myDistWorkMgr:write-attribute(name=policy-options,value={watermark=3})
deploy /path/to /resource-adapter.rar
deploy /path/to /resource-adapter.rar --all-server-groups
/subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)
/subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=server:add(value=localhost)
/subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=port:add(value=9000)
/subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName:add(class-name=com.acme.eis.ra.EISAdminObjectImpl, jndi-name=java:/eis/AcmeAdminObject)
/subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName/config-properties=threshold:add(value=10)
/subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:add(class-name=com.acme.eis.ra.EISManagedConnectionFactory, jndi-name=java:/eis/AcmeConnectionFactory)
/subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName/config-properties=name:add(value=Acme Inc)
/subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:write-attribute(name=enlistment-trace,value=true)
/subsystem=resource-adapters/resource-adapter=eis.rar:activate
/subsystem=resource-adapters/resource-adapter= RAR_NAME /connection-definitions= FACTORY_NAME :write-attribute(name=elytron-enabled,value=true)
/subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
/subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
/subsystem=jca/workmanager=customWM:add(name=customWM, elytron-enabled=true)
<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>
<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>
/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}])
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(); }
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<javax.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 javax.security.auth.callback.Callback[cbs.size()])); } catch (Throwable t) { throw new RuntimeException(t); } } }
/subsystem=datasources/data-source= DATA_SOURCE :write-attribute(name=mcp,value= MCP_CLASS )
/subsystem=resource-adapters/resource-adapter= RESOURCE_ADAPTER /connection-definitions= CONNECTION_DEFINITION :write-attribute(name=mcp,value= MCP_CLASS )
/subsystem=messaging-activemq/server= SERVER /pooled-connection-factory= CONNECTION_FACTORY :write-attribute(name=managed-connection-pool,value= MCP_CLASS )
/deployment= NAME .rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true)
/subsystem=resource-adapters/resource-adapter= RESOURCE_ADAPTER /connection-definitions= CONNECTION_DEFINITION :flush-all-connection-in-pool
/subsystem=resource-adapters/resource-adapter= RESOURCE_ADAPTER /connection-definitions= CONNECTION_DEFINITION :flush-gracefully-connection-in-pool
/subsystem=resource-adapters/resource-adapter= RESOURCE_ADAPTER /connection-definitions= CONNECTION_DEFINITION :flush-idle-connection-in-pool
/subsystem=resource-adapters/resource-adapter= RESOURCE_ADAPTER /connection-definitions= CONNECTION_DEFINITION :flush-invalid-connection-in-pool