|
|
| Home > Apache Geronimo v1.1 > Documentation > Apache Geronimo v1.1 - User's Guide > Deployment plans > geronimo-ra.xml |
Enterprise Information Systems (EIS) transact enterprise level information that can be stored in various formats like ERP systems, databases, and mainframe systems. As more organizations move towards Internet-based businesses, integration between applications and these legacy heterogeneous EIS becomes necessary. But most EIS vendors and application server vendors use non-standard vendor-specific architectures to provide connectivity between application servers and EIS.
J2EE Connector Architecture (JCA) defines a standard architecture for connecting J2EE compliant applications to heterogeneous information systems. The architecture can be used to define Resource Adapters, J2EE components that implements the JCA for a specific EIS.
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:
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 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.
According to the JCA specification basic JCA architecture supports resource adapters exactly as it is expected in side geronimo.The JCA geronimo implementation fails to find the location of classes just located in a RAR file. It needs the classes to be packed in an intermediate JAR file which in its time should be put into the root of the RAR archive.JCA implementation allows to put additional deployment parameters into the geronimo-ra.xml file inside the META-INF folder of corresponding RAR archive. Also it allows to specify external deployment plan files during deployment of resource adapters.
This article will be an introduction to understand the Geronimo deployment plan to the user in J2EE connectors. As Geronimo deployment plan for JEE connector is a wide topic to discuss, in this article I will be covering the following scope with the hope of expanding to cover more topics in the future. The article will describe the geronimo-ra.xml plan's structure and elements in depth and how it's organized to work with different applications.To provide a great deal of information about the geronimo J2EE deployment plans, starting from simple sample given in the user guide and continued to discuss about more about it.
This article is organized into the following sections : -
The Geronimo implementation of J2EE Connector "RAR" is available in the geronimo-connector module. The associated geronimo-connector-builder module is used for converting the XML deployment plans into run-time connectors.
Geronimo application server is always needed to have the ra.xml file in specific format.This file location is followed *META_INF/ra.xml".In order to that ra.xml file xml schema definitions are considered according to the J2EE connector specification.
<?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>
The DTD is available at http://java.sun.com/dtd/connector_1_0.dtd
<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee"ples. 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>
The DTD is available at http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd
The Geronimo deployment plan for a resource adapter is an XML document. It is defined by the geronimo-connector_1_5.xsd schema, which can be found in the schema/ subdirectory of the main Geronimo installation directory.
There are several ways of including the deployment plan for a resource adapter : -
The deployment plan should always use the Geronimo Connector namespace. It has required attributes to identify its connector spec version and configuration name, and an optional attribute to select a parent configuration.
A typical resource adapter deployment plan is been structured.
geronimo-ra.xml
<connector version="1.5" xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <moduleId> <groupId></groupId> <artifactId></artifactId> <version></version> <type></type> </moduleId> <dependencies/> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <resourceadapter/> ..... </connector>
Following are the main attributes defined in the above given code
xmlns The main namespace for the deployment plan, which should always be http://geronimo.apache.org/xml/ns/j2ee/connector-1.1
xmlns:sys A secondary namespace, used to identify the common elements for common libraries and module-scoped services. If there are any of those present in the deployment plan, this attribute should be present, and should be set to http://geronimo.apache.org/xml/ns/deployment-1.1
moduleId
Module IDs and dependencies are defined in the <environment> block of an XML file. Any application
or module can declare a module ID for itself using the moduleId element, and can declare dependencies
using the dependency element
resourceadapter
This segment will define the attributes of configuration of the resource adapters which are going to use in the application.
There is defined structure of the deployment of a Resource Adapter
The elements in the classloader-infoGroup are used to customized the resource adapter's class path.
Following elements are done the job of configuring the class path in the resource adapter deployment plan
import This elements refers to another configuration deployed in the server. That configuration will be added as a parent of this one (a configuration may have more than one parent). The main effect is that the class loader for the resource adapter will add the class loader for that configuration as a parent. Additionally, the parent configuration will be started before the resource adapter.
dependency Dependency Adds a third-party library to the class path for the resource adapter. Any common libraries used in this manner should be located in a subdirectory of the repository/ directory of the main Geronimo installation.
hidden-classes Lists packages or classes that may be in a parent class loader, but should not be exposed from there to the resource adapter. This is typically used when the resource adapter wants to use a different version of a library that one of its parent configurations (or Geronimo itself) uses. For example, Geronimo 1.0 uses Log4J 1.2.8. If the resource adapter wanted to use a newer version, it could include the newer version in the RAR and then add org.apache.log4j to the list of hidden-classes so that the Log4J classes could not be loaded from a parent class loader.
non-overridable-classes Lists packages or classes that the resource adapter should always load from a parent class loader, and never load from JARs included in the RAR. This might be used to force a resource adapter to share the same instance of a common library with other resource adapter, even if they each include it in their own RAR.
filter Used to list classes or packages. The format is a comma-separated list of packages or fully-qualified class names (for example: javax.servlet,javax.ejb).
The import and dependency element both ultimately need to identify a URI. In the case of an import, the
URI must match the moduleId of another deployed module or configuration. In the case of a dependency,
the URI must identify an entry in the Geronimo repository.
The Geronimo repository uses URIs divided into four components
Group ID
Artifact ID
Type
Version
For example, for Log4J, the Group ID is "log4j", the Type is "jar", the Artifact ID is "log4j",and the version included with Geronimo is "1.2.8". These components correspond to the path to the file in the repository directory of the file system,which is normally repository/groupId/types/artifactId-version.type.Therefore for Log4J, repository/log4j/jars/log4j-1.2.8.jar. The URI format used by the repository looks like groupId/artifactId/version/type (so, log4j/log4j/1.0/jar). Therefore, the dependency element must use a URI of this format, either listing it as a whole string or identifying each of the component parts.
The URIs used by the import element, however, need to match the moduleId of another module or configuration in the server. The configurations shipped with Geronimo also obey the standard URI format mentioned above, but that is strictly optional. When you provide moduleIds for your own modules, you may choose to use that format or not as you please. For example, you could use the moduleId MyCon-nector, or you could use the moduleId MyCompany/MyConnector/1.0.5/rar. Therefore, the import element may list a moduleId URI as a whole String (matching exactly the moduleId for the other module). It
may instead identify each of the component parts, but only if the configuration it's referring to used the
URI syntax described above.
This syntax is used to specify the complete URI as a String
uri The value of this element should identify the JAR or configuration, using the syntax described above. For example, specifying regexp/regexp/1.3/jar would select the JAR geronimo/re-pository/regexp/jars/regexp-1.3.jar. If there is no such JAR available, the module will fail to start.
Instead of a single URI, this creates a URI out of several components. Again, this works for all dependency elements, but only works for an import element if the targeted configuration used a URI composed of all these parts separated by slashes.
groupId Identifies the "group" of the targeted library or configuration, which is usually either the name of the vendor who produced it, or an identifier for the application or project in question.
artifactId The name of the specific library or configuration (without any version information).
version The version number of the specific library or configuration.
*type * The type of the library or configuration (jar, war, ear, rar, etc.). If omitted, defaults to jar. Note that many of the components shipped with Geronimo use a type of car (for Configuration ARchive), since the Geronimo server is built from a number of separate configurations.
Assuming the repository has a file repository/org/apache/derby/derby/10.2.2.0/derby-10.2.2.0.jar
, and the server has a JMS broker configuration called MessagingServer. A resource adapter could refer to them as follows
<import><uri>MessagingServer</uri></import> <dependency> <uri>org/apache/derby/derby/10.2.2.0/jar</uri> </dependency>
It's also possible to refer to the dependency using the split-up syntax, but the import cannot use that syntax because the module that's being imported did not use that syntax in its moduleId. That would look like as follows:
<import><uri>MessagingServer</uri></import> <dependency> <moduleId>derby </moduleId> <groupId>derby</groupId> <artifactId>postgresql-8.0</artifactId> <version>314.jdbc3</version> </dependency>
The main resource adapter configuration appears in the resourceadapter element. Note that you may deploy the same resource adapter more than once by specifying more than one resourcead-apter block. For example, in the case of the TranQL resource adapter used for JDBC connection pools, you could deploy several connection pools in the same deployment plan, by configuring each in a separate resource adapter section.
______________________________________________________
| ger:resourceadapter Type |
| |
| |----------------ger:resourceadapter-instance |
ger-resource-adaper--|----| |
| |----------------ger:outbound-resourceadapter |
| |
|______________________________________________________|
Different types of connectors use different child elements here. Each of those elements holds a number
of children for further configuration settings.
Inbound Resource Adapters
These resource adapters handle asynchronous messages arriving from external systems. They use the resourceadapter-instance section for basic configuration.
Outbound Resource Adapters
These resource adapters handle connections to external systems.If they support two-way communication, it is synchronous. An outbound resource adapter uses an outbound-resourceadapter section, and may also have a resourceadapter-instance section if there is a resource adapter class or there are any resource adapter level configuration properties.
Combined Resource Adapters
If a resource adapter support both inbound and outbound communication, it will typically have a resourceadaptert stance section and an outbound-resourceadapter section.
This section will use the http://cwiki.apache.org/GMOxDOC11/jms-and-mdb-sample-application.html sample for the details of discussing the further in Resource Adapter.
<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>samples</dep:groupId> <dep:artifactId>jms-resources</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>activemq-broker</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> </dep:dependencies> </dep:environment> <resourceadapter> <resourceadapter-instance> <resourceadapter-name>CommonConnectionFactory</resourceadapter-name> <config-property-setting name="Password">geronimo</config-property-setting> <config-property-setting name="UserName">geronimo</config-property-setting> <nam:workmanager xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1"> <nam:gbean-link>DefaultWorkManager</nam:gbean-link> </nam:workmanager> </resourceadapter-instance> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.jms.QueueConnectionFactory</connectionfactory-interface> <connectiondefinition-instance> <name>CommonConnectionFactory</name> <connectionmanager> <xa-transaction> <transaction-caching/> </xa-transaction> <single-pool> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> <adminobject> <adminobject-interface>javax.jms.Queue</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQQueue</adminobject-class> <adminobject-instance> <message-destination-name>OrderQueue</message-destination-name> <config-property-setting name="PhysicalName">OrderQueue</config-property-setting> </adminobject-instance> <adminobject-instance> <message-destination-name>ConsignmentQueue</message-destination-name> <config-property-setting name="PhysicalName">ConsignmentQueue</config-property-setting> </adminobject-instance> </adminobject> <adminobject> <adminobject-interface>javax.jms.Topic</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQTopic</adminobject-class> </adminobject> </connector>
<connector> ...... <resourceadapter> ...... <resourceadapter-name>CommonConnectionFactory</resourceadapter-name> <config-property-setting name="Password">geronimo</config-property-setting> <config-property-setting name="UserName">geronimo</config-property-setting> <nam:workmanager xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1"> <nam:gbean-link>DefaultWorkManager</nam:gbean-link> </nam:workmanager> </resourceadapter-instance> ..... </resourceadapter> ...... </connector>
resourceadapter-instance This element has dose several jobs.It gives the resource adapter a name to identify it,specify a WorkManager implementation for use with inbound resource adapters and provide values for the configuration properties specified in the resourceadapter element in the ra.xml deployment descriptor
config-property-setting:name The name attribute of a config-property-setting identifies which property this value goes with. It should match the config-property-name in a config-property in the resourceadapter element of the ra.xml file.
config-property-setting The content of this element is the value to set for the selected property. It must be valid for the config-property-type for that property.
workmanager It Selects a WorkManager implementation to use for this resource adapter. This is normally only important for inbound connectors. The named work manager must exist in the Geronimo server environment. Currently the only work manager implementation is DefaultWorkManager, unless you manually configure and deploy a different WorkManager
gbean-link Specifies a WorkManager by its simple name. In the common case, the value specified here would be DefaultWorkManager. This assumes that the WorkManager is deployed as part of the same application module, or as a server-wide configuration.
target-name The full GBean Name can be used in order to select a specific WorkManager. This is typically used to distinguish between WorkManagers with the same name deployed with different scopes, or to select a WorkManager deployed as part of a different application. The value would normally look like J2EEServer=geronimo,J2EEApplication=null,J2EEModule=geronimo/j2ee-server/1.0/car, j2eeType=JCAWorkManager,name=DefaultWorkManager
objectNameGroup
Instead of specifying the only the name (with gbean-link) or the full GBean Name string (with gbean-name), some or all of the elements in this group can be used to select a specific WorkManager while leaving other values to their defaults.
The outbound resource adapter configuration is a complex topic.There are some important element to be configured in the deployment plan in order to have a external resource adapter in an application.
<outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.jms.QueueConnectionFactory</connectionfactory-interface> <connectiondefinition-instance> <name>CommonConnectionFactory</name> <connectionmanager> <xa-transaction> <transaction-caching/> </xa-transaction> <single-pool> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter>
connection-definition This element holds all the information for a particular connection style (identified by the connectionfactory-interface). For example, if a certain resource adapter supported outbound connections using JDBC (with an interface of javax.sql.DataSource) and also a proprietary API (with a custom interface), there would be two connection definitions here, one for each interface style.
connectionfactory-interface This element identifies which connection style is being configured by this connection-definition. This must match the connectionfactory-interface in the connection-definition in the ra.xml file.
connectiondefinition-instance For each connection style, there may be one or more configurations. For example, if the resource adapter supported JDBC connections using the javx.sql.DataSource interface, each connectiondefinition-instance might point to a different database. This element holds all the configuration data related to one specific connection.
Administered objects can be used by connectors to expose specific objects in addition to the inbound or outbound resource adapters, potentially each with additional configuration required. For JMS resources, this is typically used to expose specific destinations (topics or queues). The ra.xml file for a resource adapter typically indicates what types of administered objects are available, and the Geronimo deployment plan can provide a set of specific instances of each. Continuing the JMS example, the ra.xml would declare admin object types for Topic and Queue, and the Geronimo deployment plan could list any number of specific Topics and any number of specific Queues.
*Note *Admin Objects in Geronimo are separate from resource adapter instances – for example, in the case of a JMS resource adapter with several connection factories and a topic, the topic would be a standalone object, not associated with a specific connection factory. When a JMS client or Message-Driven Bean.
This code has been excerpt from the jms-resource-plan.xml from the http://cwiki.apache.org/GMOxDOC11/jms-and-mdb-sample-application.html
<adminobject> <adminobject-interface>javax.jms.Queue</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQQueue</adminobject-class> <adminobject-instance> <message-destination-name>OrderQueue</message-destination-name> <config-property-setting name="PhysicalName">OrderQueue</config-property-setting> </adminobject-instance> <adminobject-instance> <message-destination-name>ConsignmentQueue</message-destination-name> <config-property-setting name="PhysicalName">ConsignmentQueue</config-property-setting> </adminobject-instance> </adminobject> <adminobject> <adminobject-interface>javax.jms.Topic</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQTopic</adminobject-class> </adminobject>
adminobject-interface Matches the adminobject-interface specified for this adminobject type in ra.xml.
adminobject-class Matches the adminobject-class specified for this adminobject type in ra.xml.The other elements are used to configure this specific instance of the select administered object type, with a unique name, and values for any configuration properties necessary for that administered object type.
adminobject-instance The parent element that holds the other elements described in the sample
message-destination-name A unique name to identify this administered object. Application modules that want to use this object will refer to it using this name. For example, for ActiveMQ Topics and Queues, the name specified here should match the message-destination-name in a message-destination element in the application module's J2EE deployment descriptor (i.e. web.xml, ejb-jar.xml, or application-client.xml).
config-property-setting The content of this element is the value to set for the selected property. It must be valid for the config-property-type for that property.
config-property-setting:name The name attribute of a config-property-setting identifies which property this value goes with. It should match the config-property-name in a config-property in the adminobject element of the ra.xml file.
This section will discuss the existing sample and few connector samples which give a proper understand to deploy a connector in geronimo.The base of this sample has been borrowed and modified from User Guide.(Migration to Apache Geronimo-JBoss to Geronimo JCA migration.html)This sample contains a File Retriever JCA sample application it consists of two modules that, (for the purpose of this sample)for this sample purposes, are deployed separately and not as a single EAR archive.
The first module is a simple file system resource adapter that conforms to the JCA architecture without any server-specific extensions. The adapter provides two functions:
*Lists names of files and directories located in a specific repository being a directory in the underlying file system.
*Retrieves the content of one of the files.
The second module is a Web application that uses the adapter and provides online access to the files.
J2EE RAR Deployment Plan
<connector xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <display-name>FileRetriever</display-name> <vendor-name>IBM</vendor-name> <eis-type>File system</eis-type> <resourceadapter-version>1.0</resourceadapter-version> <resourceadapter> <outbound-resourceadapter> <connection-definition> <managedconnectionfactory-class>com.ibm.j2g.jca.connector.impl.FileRetrieverManagedConnectionFactory </managedconnectionfactory-class> <config-property> <description>Path to the directory being the file repository</description> <config-property-name>RepositoryPath</config-property-name> <config-property-type>java.lang.String</config-property-type> </config-property> <connectionfactory-interface>com.ibm.j2g.jca.connector.FileRetrieverConnectionFactory </connectionfactory-interface> <connectionfactory-impl-class>com.ibm.j2g.jca.connector.impl.FileRetrieverConnectionFactoryImpl </connectionfactory-impl-class> <connection-interface>com.ibm.j2g.jca.connector.FileRetrieverConnection</connection-interface> <connection-impl-class>com.ibm.j2g.jca.connector.impl.FileRetrieverConnectionImpl </connection-impl-class> </connection-definition> <transaction-support>NoTransaction</transaction-support> <reauthentication-support>false</reauthentication-support> </outbound-resourceadapter> </resourceadapter> </connector>
J2EE RAR Geronimo v1.1 deployment plan
<connector version="1.5" xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>com</dep:groupId> <dep:artifactId>ibm</dep:artifactId> <dep:version>j2g</dep:version> <dep:type>jca.rar</dep:type> </dep:moduleId> <dep:dependencies/> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>com.ibm.j2g.jca.connector.FileRetrieverConnectionFactory </connectionfactory-interface> <connectiondefinition-instance> <name>FileRetriever</name> <!--The following path refers to the Geronimo home directory--> <config-property-setting name="RepositoryPath">..</config-property-setting> <connectionmanager> <no-transaction/> <no-pool/> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> </connector>
To deploy the adapter on Geronimo it's necessary to have a deployment plan specific to the geronimo server. Such a plan can be either named geronimo-ra.xml and be placed into the META-INF folder of the corresponding RAR archive, or can have any name and stay outside the archive. In the latter case, the path to the plan should be specified during the deployment of the resource adapter.Considering the above deployment plan let have a look in details.
In this geronimo deployment plan,the attribute moduleId specifies the unique name com/ibm/j2g/jca.rar used to identify the RAR module in Geronimo.This is a module ID with all 4 components(GroupID/Artifact-ID/Version/Type) and it's fully resolved .GroupId and the artifactId specify that this module is deployed on the server as a separate component. Both attributes are required in this case.The attribute groupId name ="com" identifying a group of related modules. The important thing is that each artifact ID should be unique within the group.
The main resource adapter configuration appears in the resourceadapter element.This sample has only one resource adapter.As previously mentioned one can deploy the same resource adapter more than once by specifying more than one resourcead-apter block.As different connectors use different child elements, this sample has used Outbound Resource Adapters which is basically handled connections to external systems.Resource adapter level configuration properties are also set along the Repository Path.
 | This article is written to cover to give an basic knowledge of depcan be stored in various formats like ERP systems, databases, and mainframe systems. As more organizations move towards Internet-based businesses, integration between applications and these legacy heterogeneous EIS becomes necessary. But most EIS vendors and application server vendors use non-standard vendor-specific architectures to provide connectivity between application servers and EIS. |