Resource adapters can be packaged and deployed in very much the same way as you would package and deploy web applications or EJB components. A resource adapter includes all the Java classes and interfaces that implement the required contracts and functionality. It also may use platform-specific libraries that enable it to talk to the EIS. All these files, along with any help files and documentation, are packaged into a JAR file, called the resource adapter archive (RAR). Just like a WAR file or an EJB JAR, a RAR file also packages XML deployment descriptors, which specify the deploy-time and runtime configuration settings for the resource adapter.
A typical RAR includes the following components:
Example 7-1 lists the contents of a typical RAR file.
Example 7-1. Contents of a resource adapter module (eis.rar)
/ra.jar /cci.jar /win.dll /solaris.so /Overview.html /GettingStarted.html /ReleaseNotes.html /LICENSE.txt /META-INF/ra.xml /META-INF/weblogic-ra.xml
Here, ra.jar and cci.jar contain the Java classes and interfaces that implement the functionality and client contracts for the resource adapter, while win.dll and solaris.so hold the platform-dependent libraries. In addition, the RAR file includes the HTML documentation and licensing information.
The standard ra.xml descriptor file captures important metadata, licensing information, and configuration settings for the transaction levels and authentication levels supported by the resource adapter. The WebLogic-specific weblogic-ra.xml descriptor file captures information about the JNDI name to which the connection factory will be bound, and additional parameters for configuring the behavior of a pool of managed connections, detecting connection leaks, and logging.
A RAR file can be created very simply by placing the contents in a staging directory say, rardir and then using the jar tool that comes with your JDK to create the archive:
jar cvf eis.rar -C rardir .
This creates a RAR file that then can be deployed to WebLogic. If you would like to deploy an existing RAR to WebLogic, you should update the Java archive to include the WebLogic-specific XML descriptor:
jar uf eis.rar -C rardir META-INF/weblogic-ra.xml
If you don't include the WebLogic-specific deployment descriptor, WebLogic automatically will include one for you when you deploy the RAR. In that case, the descriptor file will hold just dummy values that you can edit. At the very least, you will need to supply the classname for the connection factory and the JNDI name to which the connector should be bound. Your RAR also may reference support classes, perhaps shared with other modules deployed together in an EAR, in which case the JAR should include the standard JAR manifest file /META-INF/MANIFEST.MF, and it should use the Class-Path entry to point to any of the shared JARs used by the resource adapter.
A resource adapter can be deployed directly to WebLogic Server by placing it under the applications folder in a WebLogic domain. In this case, the "standalone" resource adapter can be shared by multiple J2EE applications deployed to the server. Alternatively, the adapter can be bundled as part of a J2EE application alongside other J2EE modules such as web applications and EJB JARs. This is most appropriate if the resource adapter will be used only by the other J2EE modules within an enterprise application. WebLogic allows you to deploy a resource adapter in three ways:
java weblogic.Deployer -adminurl http://localhost:7001 -username system -password mypassword -name eis.rar -activate -targets myserver -source myappseis.rar
Here, the resource adapter eis.rar is being deployed to the target server myserver. If the server has been started in development mode, in which the auto-deploy feature is enabled, you simply can drop the RAR file under the applications folder of your WebLogic domain and the resource adapter will be deployed as a standalone J2EE connector.
My Application mywebapp / ejb_foo.jar eis.rar ...
Also ensure that the XML descriptor /META-INF/application.xml includes the following DTD reference:
Once you've deployed the EAR file to WebLogic, the resource adapter will then be accessible to all web applications and EJB components within that J2EE application.
7.1.3 XML Deployment Descriptors
A resource adapter requires you to package the standard ra.xml descriptor file and the optional WebLogic-specific weblogic-ra.xml descriptor file. You can use these XML descriptors to specify metadata and adjust the runtime configuration settings for the resource adapter. The ra.xml descriptor file is defined in the JCA Specification from Sun Microsystems. It must be a valid XML document with the following DOCTYPE:
The ra.xml descriptor lets you specify the following:
A resource adapter can support one of three transaction levels: NoTransaction, LocalTransaction, or XATransaction. The JCA framework also provides for a set of well-defined configurable properties for a ManagedConnectionFactory, all of type java.lang.String:
ServerName PortNumber UserName Password ConnectionURL
These properties closely mimic the connection properties associated with a JDBC connection pool.
The weblogic-ra.xml descriptor file captures configuration settings specific to the runtime environment provided by WebLogic Server. As of WebLogic Server 8.1, the descriptor file must be a valid XML document conforming to the following DOCTYPE:
Using the weblogic-ra.xml descriptor file, you can specify the following:
We'll take a closer look at the structure of this XML descriptor file in later sections. In the meantime, you can view and configure the important deployment descriptors using the Administration Console. Select the desired connector module from the left pane, and then choose the Configuration/Descriptor option. These options are available only if the connector is deployed in an exploded form. If it is deployed as a RAR file, you need to unpack and edit the XML files using either your favorite XML editor or WebLogic Builder.
Managing the Web Server
Using JNDI and RMI
Using CMP and EJB QL
Packaging and Deployment
Performance, Monitoring, and Tuning
Logging and Internationalization