Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Chapter 8 Developing Java Clients
- Next: Chapter 10 Developing Lifecycle Listeners

# Chapter 9 Developing Connectors

This chapter describes Sun Java System Application Server support for the J2EE Connector 1.5 architecture.

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

For more information about connectors, see the J2EE Connector architecture home page, at `http://java.sun.com/j2ee/connector/`.

For connector examples, see http://developers.sun.com/prodtech/appserver/reference/techart/as8_connectors.

This chapter includes the following topics:

- Connector 1.5 Support in the Application Server

- Deploying and Configuring a Stand-Alone Connector Module

- Redeploying a Stand-Alone Connector Module

- Deploying and Configuring an Embedded Resource Adapter

- Advanced Connector Configuration Options

- Inbound Communication Support

- Configuring a Message Driven Bean to Use a Resource Adapter

# Connector 1.5 Support in the Application Server

The Application Server supports the development and deployment of resource adapters that are compatible with Connector 1.5 specification (and, for backward compatibility, the Connector 1.0 specification).

The Connector 1.0 specification defines the outbound connectivity system contracts between the resource adapter and the Application Server. The Connector 1.5 specification introduces major additions in defining system level contracts between the Application Server and the resource adapter with respect to the following:

- Inbound connectivity from an EIS - The Connector 1.5 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 providers of messaging systems to seamlessly plug in their products with any application server that supports the message inflow contract.

- Resource adapter life cycle management and thread management - These features are available through the lifecycle and work management contracts.

## 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 Application 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, the Application Server uses the Sun Java System Message Queue software. To provide JDBC infrastructure to clients, the Application Server uses its own JDBC system resource adapters. The application server automatically makes these system resource adapters available to any client that requires them.

For more information about JMS in the Application Server, see Chapter 14, Using the Java Message Service. For more information about JDBC in the Application Server, see Chapter 11, Using the JDBC API for Database Access.

## Connector Configuration

The Application Server does not need to use `sun-ra.xml`, which previous Application Server 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 Application Server.

# Deploying and Configuring a Stand-Alone Connector Module

You can deploy a stand-alone connector module using the Administration Console or the `asadmin` command. For information about using the Administration Console, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide. For information about using the `asadmin` command, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

Deploying a stand-alone connector module allows multiple deployed J2EE applications to share the connector module. A resource adapter configuration is automatically created for the connector module.

## To deploy and configure a stand-alone connector module

1. Deploy the connector module in one of the following ways.

   - In the Administration Console, open the Applications component and select Connector Modules. When you deploy the connector module, a resource adapter configuration is automatically created for the connector module.

   - Use the `asadmin deploy` or `asadmin deploydir` command. To override the default configuration properties of a resource adapter, if necessary, use the `asadmin create-resource-adapter-config` command.

2. Configure connector connection pools for the deployed connector module in one of the following ways:

   - In the Administration Console, open the Resources component, select Connectors, and select Connector Connection Pools.

   - Use the `asadmin create-connector-connection-pool` command.

3. Configure connector resources for the connector connection pools in one of the following ways.

   - In the Administration Console, open the Resources component, select Connectors, and select Connector Resources.

   - Use the `asadmin create-connector-resource` command.

   This associates a connector resource with a JNDI name.

4. Create an administered object for an inbound resource adapter, if necessary, in one of the following ways:

   - In the Administration Console, open the Resources component, select Connectors, and select Admin Object Resources.

   - Use the `asadmin create-admin-object` command.

# Redeploying a Stand-Alone Connector Module

Redeployment of a connector module maintains all connector connection pools, connector resources, and administered objects defined for the previously deployed connector module. You need not reconfigure any of these resources.

However, you should redeploy any dependent modules. A dependent module uses or refers to a connector resource of the redeployed connector module. Redeployment of a connector module results in the shared class loader reloading the new classes. Other modules that refer to the old resource adapter classes must be redeployed to gain access to the new classes. For more information about classloaders, see Classloaders.

During connector module redeployment, the server log provides a warning indicating that all dependent applications should be redeployed. Client applications or application components using the connector module’s resources may throw class cast exceptions if dependent applications are not redeployed after connector module redeployment.

To disable automatic redeployment, set the `--force` option to `false`. In this case, if the connector module has already been deployed, the Application Server provides an error message.

# Deploying and Configuring an Embedded Resource Adapter

A connector module can be deployed as a J2EE component in a J2EE application. Such connectors are only visible to components residing in the same J2EE application. Simply deploy this J2EE application as you would any other J2EE application.

You can create new connector connection pools and connector resources for a connector module embedded within a J2EE application by prefixing the connector name with app-name`#`. For example, if an application `appX.ear` has `jdbcra.rar` embedded within it, the connector connection pools and connector resources refer to the connector module as `appX#jdbcra`.

However, an embedded connector module cannot be undeployed using the name app-name`#`connector-name. To undeploy the connector module, you must undeploy the application in which it is embedded.

The association between the physical JNDI name for the connector module in the Application Server and the logical JNDI name used in the application component is specified in the Application Server specific XML descriptor `sun-ejb-jar.xml`. You can either hand code this association or use the deploytool to make this association. (For more information about using the deploytool, see deploytool.)

# Advanced Connector Configuration Options

You can use these advanced connector configuration options:

- Thread Pools

- Security Maps

- Overriding Configuration Properties

- Testing a Connection Pool

- Handling Invalid Connections

- Setting the Shutdown Timeout

- Using Last Agent Optimization of Transactions

## Thread Pools

Connectors can submit work instances to the Application Server for execution. By default, the Application 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. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the `asadmin create-threadpool` command. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

To associate a connector with a thread pool:

- In the Administration Console, open the Applications component and select Connector Modules. Deploy the module, or select the previously deployed module. Specify the name of the thread pool in the Thread Pool ID field. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the `--threadpoolid` option of the `asadmin create-resource-adapter-config` command. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 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.

## 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, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the `asadmin create-connector-security-map` command. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 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 Application 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, the Application Server uses the wild card character specification, if any, to determined the mapped back end EIS principal.

## Overriding Configuration Properties

You can override the properties specified in the `ra.xml` file of a resource adapter. 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.

You can use the `asadmin create-resource-adapter-config` command either before or after resource adapter deployment. If it is executed after deploying the resource adapter, the existing resource adapter is restarted with the new properties. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## Testing a Connection Pool

After configuring a connector connection pool, use the `asadmin ping-connection-pool` command to test the health of the underlying connections. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## Handling Invalid Connections

If a resource adapter generates a `ConnectionErrorOccured` event, the Application 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 resource adapter, and so on. If the `fail-all-connections` property in the connection pool configuration is set to `true`, all connections are destroyed and the pool is recreated.

You can set the `fail-all-connections` configuration property during creation of a connector connection pool. Or, you can use the `asadmin set` command to dynamically reconfigure a previously set property. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

The interface `ValidatingManagedConnectionFactory` exposes the method `getInvalidConnections` to allow retrieval of the invalid connections. The Application 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 Connector 1.5 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 JMS/Connector Service under the relevant configuration. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the following command:

      asadmin set server-instance.connector-service.shutdown-timeout-in-seconds="num-secs"

  For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

The Application Server deactivates all message-driven bean deployments before stopping a resource adapter.

## 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 Application Server, see Chapter 12, Using the Transaction Service.

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

# Inbound Communication Support

The Connector 1.5 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 Chapter 14, Using the Java Message Service.

# Configuring a Message Driven Bean to Use a Resource Adapter

The Connectors 1.5 specification’s message inflow contract provides a generic mechanism to plug in a wide-range of message providers, including JMS, into a J2EE-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`.

    <!--  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>
           javax.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 `sun-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 Sun Java System Message Queue message provider, is specified as the resource adapter module identifier for the `SampleMDB` bean.

    <sun-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 -->
        ...
    	</ejb>
    	<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>
    ...
    </sun-ejb-jar>

When the message-driven bean is deployed, the Application 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 application 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 the Application Server 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` property 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.

## Example Resource Adapter for Inbound Communication

The inbound sample connector bundled with the Application Server is a good example of an application utilizing the inbound connectivity contract of the J2EE Connector Architecture 1.5 specification. This sample connector is available at install-dir`/samples/connectors/apps/mailconnector`.

This example connector shows how to create an inbound J2EE Connector Architecture 1.5-compliant resource adapter and deploy its components. It shows how these resource adapters interact with other application components. The inbound sample resource adapter allows message endpoints (that is, message-driven beans) to receive email messages delivered to a specific mailbox folder on a given mail server.

The application that is bundled along with this inbound sample connector provides a simple Remote Method Invocation (RMI) back end service that allows the user to monitor the mailbox folders specified by the message-driven beans. The sample application also contains a sample message-driven bean that illustrates how the activation configuration specification properties of the message-driven bean provide the configuration parameters that the back end and resource adapter require to monitor a specific mailbox folder.

The `onMessage` method of the message-driven bean uses the JavaMail API to send a reply acknowledging the receipt of the message. This reply is sufficient to verify that the full process is working.

- Previous: Chapter 8 Developing Java Clients
- Next: Chapter 10 Developing Lifecycle Listeners

- © 2010, Oracle Corporation and/or its affiliates