Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 16. Java Connector Architecture (JCA) Management

16.1. About the Java Connector Architecture (JCA)

The Java EE Connector Architecture (JCA) defines a standard architecture for Java 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 Java EE Connector API architecture.

JCA 1.7 provides features for managing:

  • connections
  • transactions
  • security
  • life-cycle
  • work instances
  • transaction inflow
  • message inflow

JCA 1.7 was developed under the Java Community Process as JSR-322.

16.2. About Resource Adapters

A resource adapter is a deployable Java EE component that provides communication between a Java EE application and an Enterprise Information System (EIS) using the Java Connector Architecture (JCA) specification. A resource adapter is often provided by EIS vendors to allow easy integration of their products with Java 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.

16.3. Configuring the JCA Subsystem

The jca subsystem controls the general settings for the JCA container and resource adapter deployments. You can configure the jca subsystem using the management console or the management CLI.

The main JCA elements to configure are:

Configure JCA settings from the management console

The jca subsystem can be configured from the management console by navigating to Configuration → Subsystems → JCA. Then, select the appropriate tab:

  • Common Config - 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 button.
  • Bootstrap Contexts - 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.

  • Work Manager - 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 View on the selected work manager.

Configure JCA 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.

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

AttributeDefault ValueDescription

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 JCA specification correctly and archive validation is enabled, an error message will display during deployment describing the problem. For example: 

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

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 (JSR-303) will be performed on the deployment units. The following table describes the attributes you can set for bean validation.

Table 16.2. Bean Validation Attributes

AttributeDefault ValueDescription

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

AttributeDescription

name

Specifies the name of the work manager.

short-running-threads

Thread pool for standard Work instances. Each work manager has one short-running thread pool.

long-running-threads

Thread pool for JCA 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.4. Thread Pool Attributes

AttributeDefault ValueDescription

name

default

Specifies the name of the thread pool.

keepalive-time

10 seconds

Specifies the amount of time that pool threads should be kept after doing work.

allow-core-timeout

false

Boolean setting that determines whether core threads may time out. The default value is false.

thread-factory

 

Reference to the thread factory.

max-thread

50

The maximum thread pool size.

core-threads

50

The core thread pool size. This must be equal to or smaller than the maximum thread pool size.

queue-length

50

The maximum queue length.

Bootstrap Contexts

This is used to define custom bootstrap contexts. The following table describes the attributes you can set for bootstrap contexts.

Table 16.5. Bootstrap Context Attributes

AttributeDescription

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.6. Cached Connection Manager Attributes

AttributeDefault ValueDescription

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.

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. 

deploy /path/to/resource-adapter.rar

To deploy the resource adapter to all server groups in a managed domain, enter the following management CLI command. 

deploy /path/to/resource-adapter.rar --all-server-groups
Deploy a Resource Adapter using the Management Console
  1. Log in to the management console and click on the Deployments tab.
  2. Click Add. In a managed domain, you will first need to select Content Repository.
  3. Choose the Upload a new deployment option and click Next.
  4. Browse to the resource adapter archive and click Next.
  5. Verify the upload, then click Finish.
  6. In a managed domain, assign 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. 

/subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)
Configure the Resource Adapter Settings

Configure any of the following settings as necessary.

  • 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. You can disable the recording of enlistment traces by setting the enlistment-trace attribute to false. 

    /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:write-attribute(name=enlistment-trace,value=false)
    Warning

    Disabling the enlistment trace will make tracking down errors during transaction enlistment more difficult.

See Resource Adapter Attributes for all available configuration options for resource adapters.

Activate the Resource Adapter

Activate the resource adapter. 

/subsystem=resource-adapters/resource-adapter=eis.rar:activate
Note

You can also define capacity policies for resource adapters. For more details, see the Capacity Policies section.

16.4.3. Deploy and Configure the Websphere MQ Resource Adapter

You can find the instructions for deploying the Websphere MQ resource adapter in Configuring Messaging for JBoss EAP.

16.4.4. Deploy and Configure the Generic JMS Resource Adapter

You can find the instructions for configuring the generic JMS 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 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.

You can set the managed connection pool implementation for a datasource using the following management CLI command. 

/subsystem=datasources/data-source=DATA_SOURCE:write-attribute(name=mcp,value=MCP_CLASS)

You can set the managed connection pool implementation for a resource adapter using the following management CLI command. 

/subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:write-attribute(name=mcp,value=MCP_CLASS)

You can set the managed connection pool implementation for a messaging server using the following management CLI command. 

/subsystem=messaging-activemq/server=SERVER/pooled-connection-factory=CONNECTION_FACTORY:write-attribute(name=managed-connection-pool,value=MCP_CLASS)

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. 

/deployment=NAME.rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true)
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.