Developing Connectors

This section strictly applies to Payara Server Full Profile.

This chapter describes Payara Server support for the Jakarta Connectors specification.

Jakarta Connectors provides a Java solution to the problem of connectivity between multiple application servers and existing enterprise information systems (EIS). By using Jakarta Connectors, EIS vendors no longer need to customize their product for each application server. Application server vendors who conform to Jakarta Connectors do not need to write custom code to add connectivity to a new EIS.

This chapter uses the terms connector and resource adapter interchangeably. Both terms refer to a resource adapter module that is developed in conformance with the Jakarta Connectors Specification.

If you installed the Web Profile, connector modules that use only outbound communication features and work-management that does not involve inbound communication features are supported. Other connector features are supported only in Full Profile.

For more information about connectors, see "Resource Adapters and Contracts" in the Jakarta EE Tutorial.

Connector Support in Payara Server

Payara Server supports the development and deployment of resource adapters that are compatible with the Jakarta Connector specification in the following versions:

  • The Connector 1.0 specification defines the outbound connectivity system contracts between the resource adapter and Payara Server.

  • The Connector 1.5 specification introduces major additions in defining system level contracts between the Payara Server and the resource adapter with respect to inbound connectivity, life cycle management, and thread management.

  • The Connector 1.6 specification introduces further additions in defining system level contracts between the Payara Server and the resource adapter with respect to the following:

    Generic work context contract

    A generic contract that enables a resource adapter to control the execution context of a Work instance that it has submitted to Payara Server for execution. The Generic work contract provides the mechanism for a resource adapter to augment the runtime context of a Work instance with additional contextual information flown-in from the EIS. This contract enables a resource adapter to control, in a more flexible manner, the contexts in which the Work instances submitted by it are executed by the application server’s WorkManager.

    Security work context

    A standard contract that enables a resource adapter to establish security information while submitting a Work instance for execution to a WorkManager and while delivering messages-to-message endpoints residing in the Payara Server. This contract provides a mechanism to support the execution of a Work instance in the context of an established identity. It also supports the propagation of user information or Principal information from an EIS to a MessageEndpoint during message inflow.

    Transaction context

    The transaction context contract between the resource adapter and the application server leverages the Generic Work Context mechanism by describing a standard WorkContext, the TransactionContext. It represents the standard interface a resource adapter can use to propagate transaction context information from the EIS to the application server.

  • The Connector 2.0 specification moves the old Java Connectors Architecture specification (JCA) to Jakarta EE.

  • The Connector 2.1 specification, as part of Jakarta EE 10 has introduced Java SE 11 as the minimum requirement to run Jakarta EE applications.

Connector Architecture for JMS and JDBC

In the Administration Console, connector, JMS, and JDBC resources are handled differently, but they use the same underlying Connector architecture.

In Payara Server, all communication to an EIS, whether to a message provider or an RDBMS, happens through the Connector architecture. To provide JMS infrastructure to clients, Payara Server uses the Open Message Queue (OpenMQ) software. To provide JDBC infrastructure to clients, Payara Server uses its own JDBC system resource adapters. Payara Server automatically makes these system resource adapters available to any client that requires them.

For more information about JMS in the Payara Server, see Using the Java Message Service.

For more information about JDBC in the Payara Server, see Using the JDBC API for Database Access.

Connector Configuration

Payara Server does not need to use sun-ra.xml deployment descriptor, which previous versions used (as with GlassFish), to store server-specific deployment information inside a Resource Adapter Archive (RAR) file. (However, the sun-ra.xml file is still supported for backward compatibility.) Instead, the information is stored in the server configuration.

As a result, you can create multiple connector connection pools for a connection definition in a functional resource adapter instance, and you can create multiple user-accessible connector resources (that is, registering a resource with a JNDI name) for a connector connection pool.

Dynamic changes can be made to connector connection pools and the connector resource properties without restarting Payara Server.

Advanced Connector Configuration Options

Thread Associations

Connectors can submit work instances to Payara Server for execution. By default, Payara Server services work requests for all connectors from its default thread pool. However, you can associate a specific user-created thread pool to service work requests from a connector. A thread pool can service work requests from multiple resource adapters.

To create a thread pool:

  • In the Administration Console, select Thread Pools under the relevant configuration.

  • Use the asadmin create-threadpool command. For details, see the create-threadpool.

To associate a connector with a thread pool:

  • In the Administration Console, open the Applications component and select Resource Adapter Configs. Specify the name of the thread pool in the Thread Pool ID field.

  • Use the --threadpoolid option of the asadmin create-resource-adapter-config command. For details, see the create-resource-adapter-config.

If you create a resource adapter configuration for a connector module that is already deployed, the connector module deployment is restarted with the new configuration properties.

Security Maps

Create a security map for a connector connection pool to map an application principal or a user group to a backend EIS principal. The security map is usually used in situations where one or more EIS back end principals are used to execute operations (on the EIS) initiated by various principals or user groups in the application.

To create or update security maps for a connector connection pool:

  • In the Administration Console, open the Resources component, select Connectors, select Connector Connection Pools, then select the corresponding connector connection pool, and select the _ Security Maps_ tab.

  • Use the asadmin create-connector-security-map command. For details, see the"create-connector-security-map.

If a security map already exists for a connector connection pool, the new security map is appended to the previous one. The connector security map configuration supports the use of the wildcard asterisk (*) to indicate all users or all user groups.

When an application principal initiates a request to an EIS, Payara Server first checks for an exact match to a mapped back end EIS principal using the security map defined for the connector connection pool. If there is no exact match, Payara Server uses the wild card character specification, if any, to determine the mapped back end EIS principal.

Work Security Maps

A work security map for a resource adapter maps an EIS principal or group to an application principal or group. A work security map is useful in situations where one or more application principals execute operations initiated by principals or user groups in the EIS. A resource adapter can have multiple work security maps. A work security map can map either principals or groups, but not both.

To create a work security map, use the asadmin create-connector-work-security-map command. For details, see the create-connector-work-security-map.

The work security map configuration supports the wildcard asterisk (*) character to indicate all users or all user groups. When an EIS principal sends a request to Payara Server, it will first check for an exact match to a mapped application principal using the work security map defined for the resource adapter.

If there is no exact match, Payara Server uses the wild card character specification, if any, to determine the application principal.

Overriding Configuration Properties

You can override the properties (config-property elements) specified in the ra.xml file of a resource adapter:

  • In the Administration Console, open the Resources component and select Resource Adapter Configs. Create a new resource adapter configuration or select an existing one to edit. Then enter property names and values in the Additional Properties table.

  • Use the asadmin create-resource-adapter-config command to create a configuration for a resource adapter. Use this command’s --property option to specify a name-value pair for a resource adapter property. For details, see the create-resource-adapter-config.

You can specify configuration properties either before or after resource adapter deployment. If you specify properties after deploying the resource adapter, the existing resource adapter is restarted with the new properties.

You can also use token replacement for overriding resource adapter configuration properties in individual server instances when the resource adapter is deployed to a cluster. For example, for a property called inboundPort, you can assign the value ${inboundPort}. You can then assign a different value to this system property for each server instance. Changes to system properties take effect upon server restart.

Testing a Connector Connection Pool

You can test a connector connection pool for usability in one of these ways:

  • In the Administration Console, open the Resources component, open the Connectors component, select Connection Pools, and select the connection pool you want to test. Then select the Ping button in the top right corner of the page.

  • Use the asadmin ping-connection-pool command. For details, see the ping-connection-pool.

Both these commands fail and display an error message unless they successfully connect to the connection pool.

You can also specify that a connection pool is automatically tested when created or reconfigured by setting the Ping attribute to true (the default is false) in one of the following ways:

  • Enter a Ping value in the Connector Connection Pools page in the Administration Console.

  • Specify the --ping option in the asadmin create-connector-connection-pool command. For more information, see the create-connector-connection-pool.

Flushing a Connector Connection Pool

Flushing a connector connection pool recreates all the connections in the pool and brings the pool to the steady pool size without the need for reconfiguring the pool. Connection pool reconfiguration can result in application redeployment, which is a time-consuming operation. Flushing destroys existing connections, and any existing transactions are lost and must be retired.

You can flush a connector connection pool in one of these ways:

  • In the Administration Console, open the Resources component, open the Connectors component, select Connection Pools, and select the connection pool you want to flush. Then select the Flush button in the top right corner of the page.

  • Use the asadmin flush-connection-pool command. For details, see the flush-connection-pool.

Handling Invalid Connections

If a resource adapter generates a ConnectionErrorOccured event, Payara Server considers the connection invalid and removes the connection from the connection pool. Typically, a resource adapter generates a ConnectionErrorOccured event when it finds a ManagedConnection object unusable. Reasons can be network failure with the EIS, EIS failure, fatal problems with the resource adapter, and so on.

If the fail-all-connections setting in the connection pool configuration is set to true, and a single connection fails, all connections are closed and recreated. If this setting is false, individual connections are recreated only when they are used. The default is false.

The is-connection-validation-required setting specifies whether connections have to be validated before being given to the application. If a resource’s validation fails, it is destroyed, and a new resource is created and returned. The default value is false.

The prefer-validate-over-recreate property specifies that validating idle connections is preferable to closing them. This property has no effect on non-idle connections. If set to true, idle connections are validated during pool resizing, and only those found to be invalid are destroyed and recreated. If false, all idle connections are destroyed and recreated during pool resizing. The default value is false.

You can set the fail-all-connections, is-connection-validation-required, and prefer-validate-over-recreate configuration settings during creation of a connector connection pool. Or, you can use the asadmin set command to dynamically reconfigure a setting. For example:

asadmin set server.resources.connector-connection-pool.CCP1.fail-all-connections="true"
asadmin set server.resources.connector-connection-pool.CCP1.is-connection-validation-required="true"
asadmin set server.resources.connector-connection-pool.CCP1.property.prefer-validate-over-recreate="true"

The interface ValidatingManagedConnectionFactory exposes the method getInvalidConnections to allow retrieval of the invalid connections. Payara Server checks if the resource adapter implements this interface, and if it does, invalid connections are removed when the connection pool is resized.

Setting the Shutdown Timeout

According to the Jakarta Connectors specification, while an application server shuts down, all resource adapters SHOULD be stopped. A resource adapter might hang during shutdown, since shutdown is typically a resource intensive operation. To avoid such a situation, you can set a timeout that aborts resource adapter shutdown if exceeded.

The default timeout is 30 seconds per resource adapter module. To configure this timeout:

  • In the Administration Console, select Connector Service under the relevant configuration and edit the Shutdown Timeout field.

  • Use the following asadmin set command:

    asadmin set server.connector-service.shutdown-timeout-in-seconds="num-secs"
Payara Server deactivates all message-driven bean deployments before stopping a resource adapter.

Specifying the Class Loading Policy

Use the class-loading-policy setting to determine which resource adapters are accessible to applications. Allowed values are:

derived

Applications access resource adapters based on references in their deployment descriptors. These references can be resource-ref, resource-env-ref, resource-adapter-mid, or equivalent annotations.

global

All stand-alone resource adapters are available to all applications.

To configure this setting, use the asadmin set command. For example:

asadmin set server.connector-service.class-loading-policy="global"

Using Last Agent Optimization of Transactions

Transactions that involve multiple resources or multiple participant processes are distributed or global transactions. A global transaction can involve one non-XA resource if last agent optimization is enabled. Otherwise, ALL resources must be XA-aware.

For more information about transactions in Payara Server, see Using the Transaction Service.

The Jakarta Connectors specification requires that if a resource adapter supports XATransaction, the ManagedConnection created from that resource adapter must support BOTH distributed and local transactions. Therefore, even if a resource adapter supports XATransaction, you can configure its connector connection pools as non-XA or without transaction support for better performance.

A non-XA resource adapter becomes the last agent in the transactions in which it participates.

The value of the connection pool configuration property transaction-support defaults to the value of the transaction-support property in the ra.xml file.

The connection pool configuration property can override the ra.xml file property if the transaction level in the connection pool configuration property is lower. If the value in the connection pool configuration property is higher, it is ignored.

Disabling Pooling for a Connection

To disable connection pooling, set the Pooling attribute to false. The default is true. You can enable or disable connection pooling in one of the following ways:

  • Enter a Pooling value in the Connector Connection Pools page in the Administration Console.

  • Specify the --pooling option in the asadmin create-connector-connection-pool command. For more information, see the create-connector-connection-pool.

Using Application-Scoped Connectors

You can define an application-scoped connector or other resource for an enterprise application, web module, EJB module, connector module, or application client module by supplying a payara-resources.xml or glassfish-resources.xml deployment descriptor file. For details, see "Application-Scoped Resources" in the Payara Server Application Deployment section.

Inbound Communication Support

The Jakarta Connectors specification defines the transaction and message inflow system contracts for achieving inbound connectivity from an EIS. The message inflow contract also serves as a standard message provider’s pluggability contract, thereby allowing various message providers to seamlessly plug in their products with any application server that supports the message inflow contract.

In the inbound communication model, the EIS initiates all communication to an application. An application can be composed of enterprise beans (session, entity, or message-driven beans), which reside in an EJB container.

Incoming messages are received through a message endpoint, which is a message-driven bean. This message-driven bean asynchronously consumes messages from a message provider. An application can also synchronously send and receive messages directly using messaging style APIs.

A resource adapter supporting inbound communication provides an instance of an ActivationSpec JavaBean class for each supported message listener type. Each class contains a set of configurable properties that specify endpoint activation configuration information during message-driven bean deployment. The required config-property element in the ra.xml file provides a list of configuration property names required for each activation specification.

An endpoint activation fails if the required property values are not specified. Values for the properties that are overridden in the message-driven bean’s deployment descriptor are applied to the ActivationSpec JavaBean when the message-driven bean is deployed.

Administered objects can also be specified for a resource adapter, and these JavaBeans are specific to a messaging style or message provider. For example, some messaging styles may need applications to use special administered objects (such as Queue and Topic objects in JMS). Applications use these objects to send and synchronously receive messages using connection objects using messaging style APIs. For more information about administered objects, see Using the Java Message Service.

Outbound Communication Support

The Jakarta Connectors specification defines the system contracts for achieving outbound connectivity from an EIS. A resource adapter supporting outbound communication provides an instance of a ManagedConnectionFactory JavaBean class. A ManagedConnectionFactory JavaBean represents outbound connectivity information to an EIS instance from an application.

Version 1.6 of the specification introduced a mechanism through which the transaction level of a ManagedConnectionFactory can be detected at runtime. During the configuration of a ManagedConnectionFactory in the Connector Connection Pools page in the Administration Console, the Administration Console can instantiate the ManagedConnectionFactory and show the level of transaction support.

The three levels are no-tx, local-tx, xa-tx. If a ManagedConnectionFactory returns local-tx as the level it can support, it is assumed that xa-tx is not supported, and the Administration Console shows only no-tx and local-tx as the available support levels.

Configuring a Message Driven Bean to Use a Resource Adapter

The Connectors specification’s message inflow contract provides a generic mechanism to plug in a wide-range of message providers, including JMS, into a Java-EE-compatible application server. Message providers use a resource adapter and dispatch messages to message endpoints, which are implemented as message-driven beans.

The message-driven bean developer provides activation configuration information in the message-driven bean’s ejb-jar.xml file. Configuration information includes messaging-style-specific configuration details, and possibly message-provider-specific details as well. The message-driven bean deployer uses this configuration information to set up the activation specification JavaBean. The activation configuration properties specified in ejb-jar.xml override configuration properties in the activation specification definition in the ra.xml file.

According to the Jakarta Enterprise Beans specification, the messaging-style-specific descriptor elements contained within the activation configuration element are not specified because they are specific to a messaging provider. In the following sample message-driven bean ejb-jar.xml, a message-driven bean has the following activation configuration property names: destinationType, SubscriptionDurability, and MessageSelector.

<!--  A sample MDB that listens to a JMS Topic -->
<!-- message-driven bean deployment descriptor -->
 <activation-config>
   <activation-config-property>
     <activation-config-property-name>
       destinationType
     </activation-config-property-name>
     <activation-config-property-value>
       jakarta.jms.Topic
     </activation-config-property-value>
  </activation-config-property>
  <activation-config-property>
     <activation-config-property-name>
       SubscriptionDurability
     </activation-config-property-name>
     <activation-config-property-value>
       Durable
     </activation-config-property-value>
  </activation-config-property>
  <activation-config-property>
     <activation-config-property-name>
       MessageSelector
     </activation-config-property-name>
     <activation-config-property-value>
       JMSType = 'car' AND color = 'blue'
     </activation-config-property-value>
  </activation-config-property>
 ...
 </activation-config>

When the message-driven bean is deployed, the value for the resource-adapter-mid element in the glassfish-ejb-jar.xml file is set to the resource adapter module name that delivers messages to the message endpoint (to the message-driven bean). In the following example, the jmsra JMS resource adapter, which is the bundled resource adapter for the Message Queue message provider, is specified as the resource adapter module identifier for the SampleMDB bean.

<glassfish-ejb-jar>
<enterprise-beans>
    <unique-id>1</unique-id>
    <ejb>
       <ejb-name>SampleMDB</ejb-name>
       <jndi-name>SampleQueue</jndi-name>
    <!-- JNDI name of the destination from which messages would be
         delivered from MDB needs to listen to -->
    ...
    <mdb-resource-adapter>
       <resource-adapter-mid>jmsra</resource-adapter-mid>
       <!-- Resource Adapter Module Id that would deliver messages to
            this message endpoint -->
       </mdb-resource-adapter>
    ...
 </ejb>
 ...
</enterprise-beans>
...
</glassfish-ejb-jar>

When the message-driven bean is deployed, Payara Server uses the resourceadapter-mid setting to associate the resource adapter with a message endpoint through the message inflow contract. This message inflow contract with the server gives the resource adapter a handle to the MessageEndpointFactory and the ActivationSpec JavaBean, and the adapter uses this handle to deliver messages to the message endpoint instances (which are created by the MessageEndpointFactory).

When a message-driven bean first created for use on Payara Server is deployed, the connector runtime transparently transforms the previous deployment style to the current connector-based deployment style. If the deployer specifies neither a resource-adapter-mid element nor the Message Queue resource adapter’s activation configuration properties, the Connector runtime maps the message-driven bean to the jmsra system resource adapter and converts the JMS-specific configuration to the Message Queue resource adapter’s activation configuration properties.