{scrollbar}

Overview

The Geronimo deployment plan for a resource adapter, which is usually packaged as a JAR file, is called "geronimo-ra.xml". The geronimo-ra.xml deployment plan is used in conjunction with the ra.xml Java EE deplopyment plan to deploy JCA connector JAR(s) to the Geronimo application server. The geronimo-ra.xml deployment plan is an optional file, but is typically used when deploying a resource adapter JAR file. It is used to specify a moduleId for the deployed module, any third party dependencies, a description for the JCA adapter, an administration object, and additional GBeans..

Packaging

The geronimo-ra.xml deployment plan can be packaged as follows:

1. Embedded in an JAR file. In this case, a geronimo-ra.xml file must be placed in the /META-INF directory of the JAR, which is the same place where the ra.xml file must be located.
2. Maintained separately from the JAR file. In this case, the path to the file must be provided to the appropriate Geronimo deployer (e.g., command-line or console). Note that in this case, the filename can be named something other than geronimo-ra.xml but must adhere to the same schema.
3. Embedded in an application EAR file and referenced by an <alt-dd> element of the EAR deployment plan.

Schema

The geronimo-ra.xml deployment plan is defined by the geronimo-connector-1.2.xsd schema located in the <geronimo_home>/schema/ subdirectory of the main Geronimo installation directory. The geronimo-connector-1.2.xsd schema is briefly described here:

http://geronimo.apache.org/schemas-2.1/docs/geronimo-connector-1.2.xsd.html^{Image Added}

Top-level elements

The top-most element in the geronimo-connector-1.2.xsd is <connector> element. The top-level elements of the <connector> element are described below:

<sys:environment>

The <sys:environment> elements use the Geronimo deployment namespace described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html^{Image Added}. The <sys:environment> contains the following elements:

• The <moduleId> element is used to provide the configuration name for the web application as deployed in the Geronimo server. It contains elements for the groupId, artifactId, version and module type. Module IDs are normally printed with slashes between the four components, such as GroupID/ArtifactID/Version/Type.
• The <dependencies> element is used to provide the configurations and third party libraries on which the web module is dependent upon. These configurations and libraries are made available to the web module via the Geronimo classloader hierarchy.
• The <hidden-classes> element can be used to specify a list of classes which will never be loaded from parent ClassLoaders of this module. For example, if Log4J was listed here, the module would never see Geronimo's copy of Log4J. If the module provided it's own Log4J JAR it would use that, otherwise it would not be able to load Log4J at all.
• The <non-overridable-classes> element can be used to specify a list of classes which will only be loaded from parent ClassLoaders of this module (never from the module's own ClassLoader). For example, this is used to prevent a web application from redefining "javax.servlet", so those classes will always be loaded from the server instead of from the web application's own ClassPath.
• The <inverse-classloading> element can be used to specify that standard classloader delegation is to be reversed for this module.
• The <suppress-default-environment> element can be used to suppress inheritance of environment by module (i.e., any default environment built by a Geronimo builder when deploying the plan will be suppressed).

An example geronimo-ra.xml file is shown below using the <sys:environment> elements:

<conn:connector xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2"
  xmlns:conn="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
  <dep:environment>
    <dep:moduleId>
      <dep:groupId>connector</dep:groupId>
      <dep:artifactId>ConnectorProj</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>jar</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>org.apache.geronimo.configs</dep:groupId>
        <dep:artifactId>sharedlib</dep:artifactId>
        <dep:type>car</dep:type>
      </dep:dependency>
    </dep:dependencies>
  </dep:environment>
</conn:connector>

<resourceadapter>

The <resourceadapter> uses the Geronimo default namespace for a geronimo-ra.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-connector-1.2.xsd.html^{Image Added}. This element is used to define a single JDBC connector or JMS connection factory. The <resourceadapter-instance> element provides resource adapter instance specific information like configuration properties and workmanager implementation. The <outboundresource-adapter> specifies information about an outbound resource adapter. The information includes fully qualified names of classes and interfaces required as part of the connector architecture specified contracts for connection management, level of transaction support provided, one or more authentication mechanisms supported and additional required security permissions. If there is no authentication mechanism specified as part of the resource adapter element, then the resource adapter does not support any standard security contract. The application server ignores the security part of the system contracts in this case.

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <dep:moduleId>
      <dep:groupId>console.dbpool</dep:groupId>
      <dep:artifactId>AuthorConnectionsPool</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>rar</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>org.apache.derby</dep:groupId>
        <dep:artifactId>derby</dep:artifactId>
        <dep:version>10.1.1.0</dep:version>
        <dep:type>jar</dep:type>
      </dep:dependency>
    </dep:dependencies>
  </dep:environment> 
  <resourceadapter>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-
interface>javax.sql.DataSource</connectionfactory-interface>
        <connectiondefinition-instance>
          <name>AuthorConnectionsPool</name>
          <config-property-setting name="Password">APP</config-property-
setting>
          <config-property-setting
name="Driver">org.apache.derby.jdbc.EmbeddedDriver</config-property-setting>
          <config-property-setting name="UserName">APP</config-property-
setting>
          <config-property-setting
name="ConnectionURL">jdbc:derby:wroxauthors</config-property-setting>
          <connectionmanager>
            <local-transaction/>
            <single-pool>
              <max-size>10</max-size>
              <min-size>0</min-size>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition
    </outbound-resourceadapter>
  </resourceadapter>
</connector>

<adminobject>

The <adminobject> uses the Geronimo default namespace for a geronimo-ra.xml file that is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-connector-1.2.xsd.html. This element can be used to define a JMS topic or queue. The <adminobject> contains the following elements:

• The <adminobject-interface> element is used to specify the fully qualified name of the implemented Java interface of the admin object. One example of this is javax.jms.Topic.
• The <adminobject-class> element specifies the full qualified name of the Java class of the admin object.
• The <adminobject-intstance> element contains the configuration for this specific instance of the administered object type, with a unique name, and values for any configuration properties necessary for that administered object type. Two elements for defining the instance of the admin object are provided. The <message-destination-name> element can be referred to by other deployment plans by using the <naming:message-destination> element. This is also used as a unique object name of the GBean for the instance. The <config-property-setting> specifies the set of properties for the admin object instance.

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <dep:moduleId>
      <dep:groupId>console.dbpool</dep:groupId>
      <dep:artifactId>AuthorConnectionsPool</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>rar</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>org.apache.derby</dep:groupId>
        <dep:artifactId>derby</dep:artifactId>
        <dep:version>10.1.1.0</dep:version>
        <dep:type>jar</dep:type>
      </dep:dependency>
    </dep:dependencies>
  </dep:environment> 
  <resourceadapter>
    <inbound-resourceadapter>
      <messageadapter>
        <messagelistener>
          <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
          <activationspec>
            <activationspec-class>org.apache.activemq.ra.ActiveMQActivationSpec</activationspec-class>                     
            <required-config-property>
              <config-property-name>destination</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>destinationType</config-property-name>
            </required-config-property>
          </activationspec>
        </messagelistener>
      </messageadapter>
    </inbound-resourceadapter>
    <adminobject>
      <adminobject-interface>javax.jms.Queue</adminobject-interface>
      <adminobject-class>org.apache.activemq.command.ActiveMQQueue</adminobject-class>
      <config-property>
        <config-property-name>PhysicalName</config-property-name>
        <config-property-type>java.lang.String</config-property-type>
      </config-property>
    </adminobject>
    <adminobject>
      <adminobject-interface>javax.jms.Topic</adminobject-interface>
      <adminobject-class>org.apache.activemq.command.ActiveMQTopic</adminobject-class>
      <config-property>
        <config-property-name>PhysicalName</config-property-name>
        <config-property-type>java.lang.String</config-property-type>
      </config-property>
    </adminobject>
  </resourceadapter>
</connector>

<sys:service>

The <sys:service> element uses the Geronimo deployment namespace described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html^{Image Added}. It is an empty generic element to be extended by GBean and other module types.