|
|
The following sections describe how to create and configure a WebLogic Server resource adapter:
This section describes how to create a new WebLogic resource adapter. The next section, Modifying an Existing Resource Adapter, describes how to take an existing resource adapter and prepare it for deployment on WebLogic Server.
To create a new WebLogic resource adapter, you must create the classes for the particular resource adapter (ConnectionFactory, Connection, and so on), write the resource adapter’s deployment descriptors, and then package everything into an archive file to be deployed to WebLogic Server.
The following are the main steps for creating a resource adapter:
ConnectionFactory, Connection, and so on) in accordance with the
J2CA 1.5 Specification. You will specify these classes in the ra.xml file. For example:<managedconnectionfactory-class>com.sun.connector.blackbox.LocalTxManagedConnectionFactory</managedconnectionfactory-class><connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface><connectionfactory-impl-class>com.sun.connector.blackbox.JdbcDataSource</connectionfactory-impl-class><connection-interface>java.sql.Connection</connection-interface><connection-impl-class>com.sun.connector.blackbox.JdbcConnection</connection-impl-class>For more information, see Programming Tasks.
ra.xml describes the resource adapter-related attributes type and its deployment properties using the standard XML schema specified by the
J2CA 1.5 Specification.weblogic-ra.xml adds additional WebLogic Server-specific deployment information, including connection and connection pool properties, security identities, Work Manager properties, and logging.For detailed information about creating WebLogic Server-specific deployment descriptors for resource adapters, refer to Configuring the weblogic-ra.xml File and weblogic-ra.xml Schema.
.rar extension.
Create a staging directory anywhere on your hard drive. Place the JAR file in the staging directory and the deployment descriptors in a subdirectory called META-INF.
Then create the resource adapter archive by executing a jar command similar to the following in the staging directory:
jar cvf myRAR.rar *
During testing, you may need to edit the resource adapter deployment descriptors. You can do this using the WebLogic Server Administration Console or manually using an XML editor or a text editor. For more information about editing deployment descriptors, see Configuring the weblogic-ra.xml File and Configure resource adapter properties in the Administration Console online help . See also weblogic-ra.xml Schema for detailed information on the elements in the deployment descriptor.
For information about these steps, see Packaging and Deploying Resource Adapters. See also Deploying WebLogic Server Applications for detailed information about deploying components and applications in general.
In some cases, you may already have a resource adapter available for deployment to WebLogic Server. This section describes how to take an existing resource adapter that is packaged in a RAR file and modify it for deployment to WebLogic Server. This involves adding the weblogic-ra.xml deployment descriptor and repackaging the resource adapter. The following procedure supposes you have an existing resource adapter packaged in a RAR file named blackbox-notx.rar.
mkdir c:/stagedir
cd c:/stagedir
jar xf blackbox-notx.rar
The staging directory should now contain the following:
weblogic-ra.xml file. This file is the WebLogic-specific deployment descriptor for resource adapters. In this file, you specify parameters for connection factories, connection pools, and security settings.
For more information, see Configuring the weblogic-ra.xml File and also refer to weblogic-ra.xml Schema, for information on the XML schema that applies to weblogic-ra.xml.
weblogic-ra.xml file into the temporary directory's META-INF subdirectory. The META-INF directory is located in the temporary directory where you extracted the RAR file or in the directory containing a resource adapter in exploded directory format. Use the following command:cp weblogic-ra.xml c:/stagedir/META-INF
c:/stagedir> ls META-INF
Manifest.mf
ra.xml
weblogic-ra.xml
jar cvf blackbox-notx.rar -C c:/stagedir
If your resource adapter does not already contain a ra.xml file, you must manually create or edit an existing one to set the necessary deployment properties for the resource adapter. You can use a text editor or XML editor to edit the properties. For information on creating a ra.xml file, refer to the
J2CA 1.5 Specification.
In addition to supporting features of the standard resource adapter configuration ra.xml file, BEA WebLogic Server defines an additional deployment descriptor file, the weblogic-ra.xml file. This file contains parameters that are specific to configuring and deploying resource adapters in WebLogic Server. This functionality is consistent with the equivalent weblogic-*.xml extensions for EJBs and Web applications in WebLogic Server, which also add WebLogic-specific deployment descriptors to the deployable archive. The basic RAR or deployment directory can be deployed to WebLogic Server without a weblogic-ra.xml file. If a resource adapter is deployed in WebLogic Server without a weblogic-ra.xml file, a template weblogic-ra.xml file populated with default element values is automatically added to the resource adapter archive. However, this automatically generated weblogic-ra.xml file is not persisted to the RAR; the RAR remains unchanged.
The following summarizes the most significant features you can configure in the weblogic-ra.xml deployment descriptor file.
ConnectionFactory objects.)ManagedConnections that WebLogic Server attempts to allocate at deployment time.ManagedConnections that WebLogic Server allows to be allocated at any one time.ManagedConnections that WebLogic Server attempts to allocate when filling a request for a new connection.ManagedConnections to save system resources.ManagedConnections.ManagedConnectionFactory or ManagedConnection.
For detailed information about configuring the weblogic-ra.xml deployment descriptor file, see the reference information in weblogic-ra.xml Schema. See also the configuration information in the following sections:
To define or make changes to the XML descriptors used in the WebLogic Server resource adapter archive, you must define or edit the XML elements in the weblogic-ra.xml and ra.xml deployment descriptor files. You can edit the deployment descriptor files with any plain text editor. However, to avoid introducing errors, use a tool designed for XML editing.You can also edit most elements of the files using the WebLogic Administration Console.
To edit XML elements manually:
<max-config-property></max-config-property>When editing or creating XML deployment files, it is critical to include the correct schema header for each deployment file. The header refers to the location and version of the schema for the deployment descriptor.
Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the schema, so your host server need not have access to the Internet. However, you must still include this <?xml version...> element in your ra.xml file, and have it reference the external URL because the version of the schema contained in this element is used to identify the version of this deployment descriptor.
Table 3-1 shows the entire schema headers for the ra.xml and weblogic-ra.xml files.
XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc):
SAXException: This document may not have the identifier ‘identifier_name’The contents and arrangement of elements in your deployment descriptor files must conform to the schema for each file you use. The following links provide the public schema locations for deployment descriptor files used with WebLogic Server:
connector_1_5.xsd contains the schema for the standard ra.xml deployment file, required for all resource adapters. This schema is maintained as part of the
J2CA 1.5 Specification. It is located at: http://java.sun.com/xml/ns/j2ee/connector_1_5.xsdweblogic-ra.xsd contains the schema used for creating weblogic-ra.xml, which defines resource adapter properties used for deployment to WebLogic Server. This schema is located at http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd| Note: | Your browser might not display the contents of files having the .xsd extension. In that case, to view the schema contents in your browser, save the links as text files and view them with a text editor. |
You can use the Administration Console to view, modify, and (when necessary) persist deployment descriptor elements. Some descriptor element changes take place dynamically at runtime without requiring the resource adapter to be redeployed. Other descriptor elements require redeployment after changes are made. To use the Administration Console to configure a resource adapter, open Deployments and click the name of the deployed resource adapter. Use the Configuration tab to change the configuration of the resource adapter and the other tabs to control, test, or monitor the resource adapter. For information about using the Administration Console, see Configure Resource Adapter Properties in the console help.
Using the Administration Console, you can modify the following weblogic-ra.xml pool parameters dynamically, without requiring the resource adapter to be redeployed:
Using the Administration Console, you can modify the following weblogic-ra.xml logging parameters dynamically, without requiring the resource adapter to be redeployed:
A resource adapter archive (RAR) deployed on WebLogic Server must include a weblogic-ra.xml deployment descriptor file in addition to the ra.xml deployment descriptor file specified in the
J2CA 1.5 Specification.
If a resource adapter is deployed in WebLogic Server without a weblogic-ra.xml file, a template weblogic-ra.xml file populated with default element values is automatically added to the resource adapter archive. However, this automatically generated weblogic-ra.xml file is not persisted to the RAR; the RAR remains unchanged. WebLogic Server instead generates internal data structures that correspond to default information in the weblogic-ra.xml file.
For a 1.0 resource adapter that is a single connection factory definition, the JNDI name will be eis/ModuleName. For example, if the RAR is named MySpecialRA.rar, the JNDI name of the connection factory will be eis/MySpecialRA.
For a 1.5 resource adapter with a ResourceAdapter bean class specified, the JNDI name of the bean would be MySpecialRA. Each connection factory would also have a corresponding instance created with a JNDI name of eis/ModuleName, eis/ModuleName_1, eis/ModuleName_2, and so on.
The Link-Ref mechanism was introduced in the 8.1 release of WebLogic Server to enable the deployment of a single base adapter whose code could be shared by multiple logical adapters with various configuration properties. For 1.5 resource adapters in the current release, the Link-Ref mechanism is deprecated and is replaced by the new J2EE libraries feature. However, the Link-Ref mechanism is still supported in this release for 1.0 resource adapters. For more information on J2EE libraries, see
“Creating Shared J2EE Libraries and Optional Packages” in Developing Applications with WebLogic Server. To use the Link-Ref mechanism, use the <ra-link-ref> element in your resource adapter’s weblogic-ra.xml file.
The deprecated and optional <ra-link-ref> element allows you to associate multiple deployed resource adapters with a single deployed resource adapter. In other words, it allows you to link (reuse) resources already configured in a base resource adapter to another resource adapter, modifying only a subset of attributes. The <ra-link-ref> element enables you to avoid—where possible—duplicating resources (such as classes, JARs, image files, and so on). Any values defined in the base resource adapter deployment are inherited by the linked resource adapter, unless otherwise specified in the <ra-link-ref> element.
If you use the optional <ra-link-ref> element, you must provide either all or none of the values in the <pool-params> element. The <pool-params> element values are not partially inherited by the linked resource adapter from the base resource adapter.
<max-capacity> element the value of 0 (zero). This allows the linked resource adapter to inherit its <pool-params> element values from the base resource adapter.<max-capacity> element any value other than 0 (zero). The linked resource adapter will inherit no values from the base resource adapter. If you choose this option, you must specify all of the <pool-params> element values for the linked resource adapter.
For further instructions on editing the weblogic-ra.xml file, see weblogic-ra.xml Schema.
|