docs/application-development-guide/src/main/asciidoc/connectors.adoc

type=page
status=published
title=Developing Connectors
next=lifecycle-listeners.html
prev=java-clients.html
~~~~~~

= Developing Connectors

[[GSDVG00013]][[bealk]]


[[developing-connectors]]
== 11 Developing Connectors

This chapter describes {productName} support for the Jakarta EE
Connector Architecture, also known as
http://jcp.org/en/jsr/detail?id=322[JSR 322]
(`http://jcp.org/en/jsr/detail?id=322`).

The Jakarta EE Connector Architecture provides a Java solution to the
problem of connectivity between multiple application servers and
existing enterprise information systems (EISs). By using the Jakarta EE
Connector architecture, EIS vendors no longer need to customize their
product for each application server. Application server vendors who
conform to the Jakarta EE Connector architecture 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 EE Connector Architecture
Specification.

[NOTE]
====
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 the full {productName}.
====
For more information about connectors, see
https://eclipse-ee4j.github.io/jakartaee-tutorial/#resource-adapters-and-contracts[
Resource Adapters and Contracts] in The Jakarta EE Tutorial.

For information about deploying a connector to the {productName}, see
the link:application-deployment-guide.html#GSDPG[
{productName} Application Deployment Guide].

The following topics are addressed here:

* link:#beall[Connector Support in the {productName}]
* link:#bealr[Advanced Connector Configuration Options]
* link:#bealz[Inbound Communication Support]
* link:#gizdm[Outbound Communication Support]
* link:#beama[Configuring a Message Driven Bean to Use a Resource Adapter]

[[beall]][[GSDVG00162]][[connector-support-in-the-glassfish-server]]

=== Connector Support in the {productName}

The {productName} supports the development and deployment of resource
adapters that are compatible with the Connector 1.6 specification (and,
for backward compatibility, the Connector 1.0 and 1.5 specifications).

The Connector 1.0 specification defines the outbound connectivity system
contracts between the resource adapter and the {productName}. The
Connector 1.5 specification introduces major additions in defining
system level contracts between the {productName} 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 {productName} 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 the {productName} 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 {productName}. 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.

[[bealm]][[GSDVG00474]][[connector-architecture-for-jms-and-jdbc]]

==== 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 the {productName}, all communication to an EIS,
whether to a message provider or an RDBMS, happens through the Connector
architecture. To provide JMS infrastructure to clients, the {productName} uses the Open Message Queue software. To provide JDBC
infrastructure to clients, the {productName} uses its own JDBC system
resource adapters. The {productName} automatically makes these system
resource adapters available to any client that requires them.

For more information about JMS in the {productName}, see
link:jms.html#beaob[Using the Java Message Service]. For more information
about JDBC in the {productName}, see link:jdbc.html#beamj[Using the
JDBC API for Database Access].

[[bealn]][[GSDVG00475]][[connector-configuration]]

==== Connector Configuration

The {productName} does not need to use `sun-ra.xml`, which previous
{productName} versions used, 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. In addition, dynamic changes can be made to connector connection
pools and the connector resource properties without restarting the
{productName}.

[[bealr]][[GSDVG00163]][[advanced-connector-configuration-options]]

=== Advanced Connector Configuration Options

The following topics are addressed here:

* link:#beals[Thread Associations]
* link:#bealt[Security Maps]
* link:#giqgt[Work Security Maps]
* link:#bealu[Overriding Configuration Properties]
* link:#bealv[Testing a Connector Connection Pool]
* link:#gizcv[Flushing a Connector Connection Pool]
* link:#bealw[Handling Invalid Connections]
* link:#bealx[Setting the Shutdown Timeout]
* link:#gjjyy[Specifying the Class Loading Policy]
* link:#bealy[Using Last Agent Optimization of Transactions]
* link:#gizba[Disabling Pooling for a Connection]
* link:#gizcs[Using Application-Scoped Connectors]

[[beals]][[GSDVG00476]][[thread-associations]]

==== Thread Associations

Connectors can submit work instances to the {productName} for
execution. By default, the {productName} 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. For details, click the Help button in the Administration
Console.
* Use the `asadmin create-threadpool` command. For details, see the
link:reference-manual.html#GSRFM[{productName} Reference Manual].

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. For details, click the Help button in the
Administration Console.
* Use the `--threadpoolid` option of the
`asadmin create-resource-adapter-config` command. For details, see the
link:reference-manual.html#GSRFM[{productName} Reference Manual].

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.

[[bealt]][[GSDVG00477]][[security-maps]]

==== Security Maps

Create a security map for a connector connection pool to map an
application principal or a user group to a back end 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, and select the Security
Maps tab. For details, click the Help button in the Administration
Console.
* Use the `asadmin create-connector-security-map` command. For details,
see the link:reference-manual.html#GSRFM[{productName} Reference
Manual].

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, the
{productName} 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, the {productName} uses
the wild card character specification, if any, to determined the mapped
back end EIS principal.

[[giqgt]][[GSDVG00478]][[work-security-maps]]

==== Work Security Maps

A work security map for a resource adapter maps an EIS principal or
group to a 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 link:reference-manual.html#GSRFM[{productName} Reference Manual].

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 the {productName}, the {productName}
first checks 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, the {productName} uses the wild card character
specification, if any, to determine the application principal.

[[bealu]][[GSDVG00479]][[overriding-configuration-properties]]

==== 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. For details, click the Help button in
the Administration Console.
* 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 link:reference-manual.html#GSRFM[{productName}
Reference Manual].

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 property for each server instance.
Changes to system properties take effect upon server restart.

[[bealv]][[GSDVG00480]][[testing-a-connector-connection-pool]]

==== 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
Connector 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. For details, click the Help button in the
Administration Console.
* Use the `asadmin ping-connection-pool` command. For details, see the
link:reference-manual.html#GSRFM[{productName} Reference Manual].

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. For more information, click the Help button in
the Administration Console.
* Specify the `--ping` option in the
`asadmin create-connector-connection-pool` command. For more
information, see the link:reference-manual.html#GSRFM[{productName}
Reference Manual].

[[gizcv]][[GSDVG00481]][[flushing-a-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
Connector 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. For details, click the Help button in the
Administration Console.
* Use the `asadmin flush-connection-pool` command. For details, see the
link:reference-manual.html#GSRFM[{productName} Reference Manual].

[[bealw]][[GSDVG00482]][[handling-invalid-connections]]

==== Handling Invalid Connections

If a resource adapter generates a `ConnectionErrorOccured` event, the
{productName} 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 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 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:

[source]
----
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"
----

For details, see the link:reference-manual.html#GSRFM[{productName}
Reference Manual].

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

[[bealx]][[GSDVG00483]][[setting-the-shutdown-timeout]]

==== Setting the Shutdown Timeout

According to the Connector 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. For details,
click the Help button in the Administration Console.
* Use the following `asadmin set` command:
+
[source]
----
asadmin set server.connector-service.shutdown-timeout-in-seconds="num-secs"
----
For details, see the link:reference-manual.html#GSRFM[{productName}
Reference Manual].

The {productName} deactivates all message-driven bean deployments
before stopping a resource adapter.

[[gjjyy]][[GSDVG00484]][[specifying-the-class-loading-policy]]

==== Specifying the Class Loading Policy

Use the `class-loading-policy` setting to determine which resource
adapters 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:

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

For details, see the link:reference-manual.html#GSRFM[{productName}
Reference Manual].

[[bealy]][[GSDVG00485]][[using-last-agent-optimization-of-transactions]]

==== 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. For more information about
transactions in the {productName}, see
link:transaction-service.html#beanm[Using the Transaction Service].

The Connector 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.

[[gizba]][[GSDVG00486]][[disabling-pooling-for-a-connection]]

==== 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. For more information, click the Help button in
the Administration Console.
* Specify the `--pooling` option in the
`asadmin create-connector-connection-pool` command. For more
information, see the link:reference-manual.html#GSRFM[{productName}
Reference Manual].

[[gizcs]][[GSDVG00487]][[using-application-scoped-connectors]]

==== 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 `glassfish-resources.xml`
deployment descriptor file. For details, see
"link:application-deployment-guide/deploying-applications.html#GSDPG00075[Application-Scoped Resources]" in {productName} Application Deployment Guide.

[[bealz]][[GSDVG00164]][[inbound-communication-support]]

=== Inbound Communication Support

The Connector 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
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 link:jms.html#beaob[Using the
Java Message Service].

[[gizdm]][[GSDVG00165]][[outbound-communication-support]]

=== Outbound Communication Support

The Connector 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.

The 1.6 Connector specification introduces 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.

For more information, click the Help button in the Administration
Console.

[[beama]][[GSDVG00166]][[configuring-a-message-driven-bean-to-use-a-resource-adapter]]

=== 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 EJB 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`.

[source,xml]
----
<!--  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.

[source,xml]
----
<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, the {productName} 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 {productName} 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 the {productName}
7 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.