Chapter 13. J2EE Connectors (RARs) [DRAFT (1.0)]

Chapter 13. J2EE Connectors (RARs) [DRAFT (1.0)]
	Part III. J2EE Applications on Geronimo

Table of Contents

13.1.1. ra.xml Format

13.2. The Resource Adapter Geronimo Deployment Plan

13.3. Structure of the Deployment Plan

13.3.1. Customizing the Resource Adapter Class Path
13.3.2. Resource Adapter Configuration
13.3.3. Admin Object Configuration
13.3.4. Adding Module-Scoped Services

13.4. Sample Resource Adapter Configurations

	Warning
	This chapter has not yet been updated to cover Geronimo 1.1 (note the title of each chapter includes "1.0" or "1.1"). As a result, the syntax and examples are all from the Geronimo 1.0 release. Stay tuned for an update of this chapter.

J2EE Connector resource adapters allow you to hook in systems or functions outside of what the application server normally provides, with full support for transactions, security, resource pooling, thread management, and other advanced features. In Geronimo, resource adapters are used to provide JDBC connection pools and JMS connection factories and destinations. Applications can use resource adapters to integrate with external systems, to encapsulate restricted operations such as network or file system access, and more. In some cases a resource adapter will be deployed server wide, so multiple applications can access it and share the same connections and resources. In other cases, a resource adapter will be deployed solely within a single application.

Geronimo supports J2EE Connectors version 1.5, with backward compatibility to 1.0. In the case of J2EE Connectors, Geronimo does not provide many additional features above and beyond what's covered in the spec, but the configuration of a connector to communicate with a specific back-end server or resource can be intricate. Overall, deploying connectors to Geronimo involves a process like:

Create the resource adapter classes, and package them into one or more JARs
Create the standard ra.xml deployment descriptor
Create a Geronimo-specific geronimo-ra.xml deployment plan
Package the connector JAR(s) and deployment descriptors into a RAR file, or a directory tree laid out like a RAR
Use the deployment tool described in Section 10.4, “The Deploy Tool” to deploy the RAR (or an EAR containing the RAR) into the server

The process of developing connectors and the standard ra.xml deployment descriptor should be familiar already. After a brief review of what Geronimo expects from a RAR, this chapter focuses mainly on the contents of the Geronimo geronimo-ra.xml deployment plan. This plan may be packaged within the connector RAR, or provided as a separate file in the EAR or to the deployment tool.

Note

	Note
In this chapter, I use "resource adapter" to mean a specific J2EE Connector deployment. Strictly speaking, a J2EE Connector does not actually need to include an implementation of `javax.resource.spi.ResourceAdapter` (though most do). Still, given the terminology used in the specification and the names of the elements in the ra.xml deployment descriptor, it seems like this is the best way to describe a specific J2EE Connector.

In this chapter, I use "resource adapter" to mean a specific J2EE Connector deployment. Strictly speaking, a J2EE Connector does not actually need to include an implementation of javax.resource.spi.ResourceAdapter (though most do). Still, given the terminology used in the specification and the names of the elements in the ra.xml deployment descriptor, it seems like this is the best way to describe a specific J2EE Connector.

13.1. Creating a J2EE Connector RAR

Geronimo doesn't have any special requirements on RAR files -- any RAR produced according to the standard J2EE process should work in Geronimo. However, there are a couple points to note:

Geronimo requires that every RAR file has a standard META-INF/ra.xml deployment descriptor. This may be configured for J2EE Connectors 1.0, or J2EE Connectors 1.5, and should follow the appropriate XML format (see below).
Any JARs included in the RAR file will be added to the resource adapter class path, and also the class loader of any other modules in the same EAR. Beyond that, external libraries can also be placed in the Geronimo server repository and referenced with dependency elements in the Geronimo deployment plan (see Section 13.3.1, “Customizing the Resource Adapter Class Path”).

13.1.1. `ra.xml` Format

Geronimo expects the META-INF/ra.xml file to obey one of the following standard formats:

J2EE Connectors 1.0

Defined by the DTD at http://java.sun.com/dtd/connector_1_0.dtd, a Connector 1.0 deployment descriptor looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE connector PUBLIC
    "-//Sun Microsystems, Inc.//DTD Connector 1.0//EN"
    "http://java.sun.com/dtd/connector_1_0.dtd">

<connector>
  ...
</connector>

J2EE Connectors 1.5

Defined by the XML schema at http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd, a Connector 1.0 deployment descriptor looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<connector xmlns="http://java.sun.com/xml/ns/j2ee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
          http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
       version="1.5">
  ...
</connector>


12.3. Structure of the Deployment Plan		13.2. The Resource Adapter Geronimo Deployment Plan