Resource Adapters and Contracts

We are working on a fresh, updated Jakarta EE Tutorial. This section hasn’t yet been updated.

This chapter examines resource adapters and explains how communications between Jakarta EE servers and EIS systems are mediated by them.

What Is a Resource Adapter?

A resource adapter is a Jakarta EE component that implements the Jakarta Connectors API for a specific EIS. Examples of EISs include enterprise resource planning, mainframe transaction processing, and database systems. In a Jakarta EE server, Jakarta Messaging and Jakarta Mail also act as EISs that you access using resource adapters. As illustrated in Figure 1, “Resource Adapters”, the resource adapter facilitates communication between a Jakarta EE application and an EIS.

Figure 1. Resource Adapters

Stored in a Resource Adapter Archive (RAR) file, a resource adapter can be deployed on any Jakarta EE server, much like a Jakarta EE application. A RAR file may be contained in an Enterprise Archive (EAR) file, or it may exist as a separate file.

A resource adapter is analogous to a JDBC driver. Both provide a standard API through which an application can access a resource that is outside the Jakarta EE server. For a resource adapter, the target system is an EIS; for a JDBC driver, it is a DBMS. Resource adapters and JDBC drivers are rarely created by application developers. In most cases, both types of software are built by vendors that sell tools, servers, or integration software.

The resource adapter mediates communication between the Jakarta EE server and the EIS by means of contracts. The application contract defines the API through which a Jakarta EE component, such as an enterprise bean, accesses the EIS. This API is the only view that the component has of the EIS. The system contracts link the resource adapter to important services that are managed by the Jakarta EE server. The resource adapter itself and its system contracts are transparent to the Jakarta EE component.

Management Contracts

Jakarta Connectors defines system contracts that enable resource adapter lifecycle and thread management.

Lifecycle Management

Jakarta Connectors specifies a lifecycle management contract that allows an application server to manage the lifecycle of a resource adapter. This contract provides a mechanism for the application server to bootstrap a resource adapter instance during the deployment or application server startup. This contract also provides a means for the application server to notify the resource adapter instance when it is undeployed or when an orderly shutdown of the application server takes place.

Work Management Contract

Jakarta Connectors work management contract ensures that resource adapters use threads in the proper, recommended manner. This contract also enables an application server to manage threads for resource adapters.

Resource adapters that improperly use threads can jeopardize the entire application server environment. For example, a resource adapter might create too many threads or might not properly release threads it has created. Poor thread handling inhibits application server shutdown and impacts the application server’s performance because creating and destroying threads are expensive operations.

The work management contract establishes a means for the application server to pool and reuse threads, similar to pooling and reusing connections. By adhering to this contract, the resource adapter does not have to manage threads itself. Instead, the resource adapter has the application server create and provide needed threads. When it is finished with a given thread, the resource adapter returns the thread to the application server. The application server manages the thread, either returning it to a pool for later reuse or destroying it. Handling threads in this manner results in increased application server performance and more efficient use of resources.

In addition to moving thread management to the application server, the Connector Architecture provides a flexible model for a resource adapter that uses threads.

The requesting thread can choose to block (stop its own execution) until the work thread completes.
The requesting thread can block while it waits to get the work thread. When the application server provides a work thread, the requesting thread and the work thread execute in parallel.
The resource adapter can opt to submit the work for the thread to a queue. The thread executes the work from the queue at some later point. The resource adapter continues its own execution from the point it submitted the work to the queue, no matter when the thread executes it.

With the latter two approaches, the submitting thread and the work thread may execute simultaneously or independently. For these approaches, the contract specifies a listener mechanism to notify the resource adapter that the thread has completed its operation. The resource adapter can also specify the execution context for the thread, and the work management contract controls the context in which the thread executes.

Generic Work Context Contract

The work management contract between the application server and a resource adapter enables a resource adapter to do a task, such as communicating with the EIS or delivering messages, by delivering Work instances for execution.

A generic work context contract enables a resource adapter to control the contexts in which the Work instances that it submits are executed by the application server’s WorkManager. A generic work context mechanism also enables an application server to support message inflow and delivery schemes. It also provides a richer contextual Work execution environment to the resource adapter while still maintaining control over concurrent behavior in a managed environment.

The generic work context contract standardizes the transaction context and the security context.

Outbound and Inbound Contracts

The Connector Architecture defines the following outbound contracts, system-level contracts between an application server and an EIS that enable outbound connectivity to an EIS.

The connection management contract supports connection pooling, a technique that enhances application performance and scalability. Connection pooling is transparent to the application, which simply obtains a connection to the EIS.
The transaction management contract extends the connection management contract and provides support for management of both local and XA transactions.

A local transaction is limited in scope to a single EIS system, and the EIS resource manager itself manages such a transaction. An XA transaction or global transaction can span multiple resource managers. This form of transaction requires transaction coordination by an external transaction manager, typically bundled with an application server. A transaction manager uses a two-phase commit protocol to manage a transaction that spans multiple resource managers or EISs, and uses one-phase commit optimization if only one resource manager is participating in an XA transaction.
The security management contract provides mechanisms for authentication, authorization, and secure communication between a Jakarta EE server and an EIS to protect the information in the EIS.

A work security map matches EIS identities to the application server domain’s identities.

Inbound contracts are system contracts between a Jakarta EE server and an EIS that enable inbound connectivity from the EIS: pluggability contracts for message providers and contracts for importing transactions.

Metadata Annotations

Jakarta Connectors provides a set of annotations to minimize the need for deployment descriptors.

The @Connector annotation can be used by the resource adapter developer to specify that the JavaBeans component is a resource adapter JavaBeans component. This annotation is used for providing metadata about the capabilities of the resource adapter. Optionally, you can provide a JavaBeans component implementing the ResourceAdapter interface, as in the following example:
```
@Connector(
    displayName = "TrafficRA",
    vendorName = "Jakarta EE Tutorial",
    version = "9.0"
)
public class TrafficResourceAdapter implements ResourceAdapter,
                                               Serializable {
    ...
}
```

The @ConnectionDefinition annotation defines a set of connection interfaces and classes pertaining to a particular connection type, as in the following example:

@ConnectionDefinition(
    connectionFactory = TradeConnectionFactory.class,
    connectionFactoryImpl = TradeConnectionFactoryImpl.class,
    connection = TradeConnection.class,
    connectionImpl = TradeConnectionImpl.class
)
public class TradeManagedConnectionFactory ... {
    ...
}

The @AdministeredObject annotation designates a JavaBeans component as an administered object.

The @Activation annotation contains configuration information pertaining to inbound connectivity from an EIS instance, as in the following example:

@Activation(
        messageListeners = { TrafficListener.class }
)
public class TrafficActivationSpec implements ActivationSpec,
                                              Serializable {
    ...
    @ConfigProperty()
    /* port to listen to requests from the EIS */
    private String port;
    ...
}

The @ConfigProperty annotation can be used on JavaBeans components to provide additional configuration information that may be used by the deployer and resource adapter provider. The preceding example code shows several @ConfigProperty annotations.
The @ConnectionFactoryDefinition annotation is a resource definition annotation that is used to define a connector connection factory and register it in JNDI under the name specified in the mandatory name annotation element. The mandatory interfaceName annotation element specifies the fully qualified name of the connection factory interface class. The transactionSupport annotation element specifies the level of transaction support the connection factory needs to support. The minPoolSize and maxPoolSize annotation elements specify the minimum or maximum number of connections that should be allocated for a connection pool that backs this connection factory resource. Additional properties associated with the connection factory being defined can be specified through the properties element.

Since repeated annotations are not allowed, the @ConnectionFactoryDefinitions annotation acts as a container for multiple connector connection factory definitions. The value annotation element contains the multiple connector connection factory definitions.
The @AdministeredObjectDefinition annotation is a resource definition annotation that is used to define an administered object and register it in JNDI under the name specified in the mandatory name annotation element. The mandatory fully qualified name of the administered object’s class must be indicated by the className element. Additional properties that must be configured in the administered object can be specified through the properties element.

Since repeated annotations are not allowed, the @AdministeredObjectDefinitions annotation acts as a container for multiple administered object definitions. The value annotation element contains the multiple administered object definitions.

The specification allows a resource adapter to be developed in mixed-mode form, that is the ability for a resource adapter developer to use both metadata annotations and deployment descriptors in applications. An application assembler or deployer may use the deployment descriptor to override the metadata annotations specified by the resource adapter developer.

The deployment descriptor for a resource adapter, if present, is named ra.xml. The metadata-complete attribute defines whether the deployment descriptor for the resource adapter module is complete or whether the class files available to the module and packaged with the resource adapter need to be examined for annotations that specify deployment information.

For the complete list of annotations and JavaBeans components provided in the Jakarta EE platform, see the Jakarta Connectors 2.0 specification.

Common Client Interface

This section explains how components use the Jakarta Connectors Common Client Interface (CCI) API and a resource adapter to access data from an EIS. The CCI API defines a set of interfaces and classes whose methods allow a client to perform typical data access operations. The CCI interfaces and classes are as follows.

ConnectionFactory: Provides an application component with a Connection instance to an EIS.
Connection: Represents the connection to the underlying EIS.
ConnectionSpec: Provides a means for an application component to pass connection-request-specific properties to the ConnectionFactory when making a connection request.
Interaction: Provides a means for an application component to execute EIS functions, such as database stored procedures.
InteractionSpec: Holds properties pertaining to an application component’s interaction with an EIS.
Record: The superinterface for the various kinds of record instances. Record instances can be MappedRecord, IndexedRecord, or ResultSet instances, all of which inherit from the Record interface.
RecordFactory: Provides an application component with a Record instance.
IndexedRecord: Represents an ordered collection of Record instances based on the java.util.List interface.

A client or application component that uses the CCI to interact with an underlying EIS does so in a prescribed manner. The component must establish a connection to the EIS’s resource manager, and it does so using the ConnectionFactory. The Connection object represents the connection to the EIS and is used for subsequent interactions with the EIS.

The component performs its interactions with the EIS, such as accessing data from a specific table, using an Interaction object. The application component defines the Interaction object by using an InteractionSpec object. When it reads data from the EIS, such as from database tables, or writes to those tables, the application component does so by using a particular type of Record instance: a MappedRecord, an IndexedRecord, or a ResultSet instance.

Note, too, that a client application that relies on a CCI resource adapter is very much like any other Jakarta EE client that uses enterprise bean methods.

Using Resource Adapters with Jakarta Contexts and Dependency Injection (CDI)

For details about CDI, see Introduction to Jakarta Contexts and Dependency Injection and Jakarta Contexts and Dependency Injection: Advanced Topics.

Do not specify the following classes in the resource adapter as CDI managed beans (that is, do not inject them), because the behavior of these classes as CDI managed beans has not been portably defined.

Resource adapter beans: These beans are classes that are annotated with the jakarta.resource.spi.Connector annotation or are declared as corresponding elements in the resource adapter deployment descriptor, ra.xml.
Managed connection factory beans: These beans are classes that are annotated with the jakarta.resource.spi.ConnectorDefinition annotation or the jakarta.resource.spi.ConnectorDefinitions annotation or are declared as corresponding elements in ra.xml.
Activation specification beans: These beans are classes that are annotated with the jakarta.resource.spi.Activation annotation or are declared as corresponding elements in ra.xml.
Administered object beans: These beans are classes that are annotated with the jakarta.resource.spi.AdministeredObject annotation or are declared as corresponding elements in ra.xml.

Other types of classes in the resource adapter can be CDI managed beans and will behave in a portable manner.

Further Information about Resource Adapters

For more information about resource adapters and annotations, see

Jakarta EE 9 Platform Specification:
https://jakarta.ee/specifications/platform/
Jakarta Connectors 2.1 specification:
https://jakarta.ee/specifications/connectors/2.1/
Jakarta Enterprise Beans specification:
https://jakarta.ee/specifications/enterprise-beans/4.0/
Jakarta Annotations:
https://jakarta.ee/specifications/annotations/2.1/