Developing Connectors

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.

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.

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:

To associate a connector with a thread pool:

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:

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.

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.

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

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.

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

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:

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:

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:

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.

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:

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

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

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.

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.

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:

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.