To deploy a server-wide database pool, you'll create a deployment plan using the format described in Section 6.4.1, “Configuring a Database Pool” and then deploy the connection pool using that plan.

First you should save the database pool deployment plan to a file like database-pool.xml (the name can be anything you like). Then you need to locate the TranQL RAR and deploy the pool using a command like this:

java -jar bin/deployer.jar deploy database-pool.xml \
  repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar

Note that this example assumes that the server is running, and it can be run from any directory, so long as you point it to the deployer JAR in geronimo/bin. The two arguments should point to the TranQL RAR file and the database pool deployment plan (the order doesn't matter). If the server is not running, you can use the command distribute instead of deploy though then you'll still have to start the configuration once the server is running. For more information on deployment commands, see Section 10.4, “The Deploy Tool”.

Other application modules can map resources to that database pool using the procedure described in Section 6.5, “Using a Database Pool”.

In contrast to server-wide database pools, application-scoped database pools are only visible to a single application by default, which must be packaged as an EAR.

To deploy an application-scoped database pool, you'll include the TranQL Connector RAR as a module in your application EAR (for normal JDBC pools; XA database pools would use a product-specific TranQL RAR, which should be in the same location.). First you should save the database pool deployment plan to a file like database-pool.xml (the name can be anything you like). Then you need to locate the TranQL RAR, and add both of these to your EAR.

For example, the EAR structure might look like this:

jar -tf my-app.ear
  my-web-app.war
  my-ejbs.jar
  tranql-connector-1.2.rar
  database-pool.xml
  META-INF/application.xml
  META-INF/geronimo-application.xml

Notice the TranQL RAR and the database configuration file. You should add a reference to the TranQL RAR to the standard META-INF/application.xml deployment descriptor, and add a reference to the database pool deployment plan to the META-INF/geronimo-application.xml deployment plan. This might be the only entry in the geronimo-application.xml file, so you'll need to create that file if you don't have one already.

The application.xml file for the EAR above would look like this:

META-INF/application.xml

<application 
       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/application_1_4.xsd"
       version="1.4">
    <module>
        <ejb>my-ejbs.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>my-web-app.war</web-uri>
            <context-root>/my-web-app</context-root>
        </web>
    </module>
    <module>
        <connector>tranql-connector-1.2.rar</connector>
    </module>
</application>

Notice the final module entry for the RAR.

The geronimo-application.xml file identifying the database pool deployment plan would look like this:

META-INF/geronimo-application.xml

<application
   xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
    <environment>
        <moduleId>
            <artifactId>MyApplication</artifactId>
        </moduleId>
    </environment>
    <module>
        <connector>tranql-connector-1.2.rar</connector>
        <alt-dd>database-plan.xml</alt-dd>
    </module>
</application>

Using the alt-dd element, the deployment plan for the application indicates that the database pool deployment plan for the connector is included as a separate file in the EAR, instead of being packaged into the RAR. The elements here look very similar to the elements in the standard application.xml deployment descriptor, but if we specify an alt-dd there it means an alternate standard J2EE deployment descriptor, whereas specifying the alt-dd here means an alternate Geronimo deployment plan for the connector.

For more information on the geronimo-application.xml file, see Chapter 15, Enterprise Applications (EARs) [DRAFT (1.0)].

The most restricted type of database pools, client-scoped database pools are only visible to the application client module that declares them. These pools are not visible to either other modules in the same application or to other applications in the same server.

To deploy a client-scoped database pool, you'll refer to a common copy of the TranQL Connector RAR (for normal JDBC pools) -- make sure it appears at geronimo/repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar. (XA database pools would use a product-specific TranQL RAR, which should be in a similar location.)

A client-scoped connection pool is declared in the Geronimo deployment plan for the application client module that should have access to the pool. The plan will have an additional resource element containing the pool definition. A deployment plan that declared a pool using the same configuration shown in Example 6.1, “Database Pool Deployment Plan” would look like this:

META-INF/geronimo-application-client.xml

<application-client xmlns=
 "http://geronimo.apache.org/xml/ns/j2ee/application-client-1.1">
  <server-environment
        xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <moduleId>
      <artifactId>MyClientJSR77</artifactId>
    </moduleId>
  </server-environment>
  <client-environment
        xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <moduleId>
      <artifactId>MyClient</artifactId>
    </moduleId>
  </client-environment>
  ...
  <resource>
    <external-rar>
      tranql/tranql-connector/1.2/rar
    </external-rar>
    <connector
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
      <environment
        xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
        <moduleId>
          <groupId>test</groupId>
          <artifactId>TestDatabase</artifactId>
          <version>1.0</version>
          <type>rar</type>
        </moduleId>
        <dependencies>
          <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>3.1.12</version>
            <type>jar</type>
          </dependency>
        </dependencies>
      </environment>

      <resourceadapter>
        <outbound-resourceadapter>
          <connection-definition>
            <connectionfactory-interface>
              javax.sql.DataSource
            </connectionfactory-interface>
            <connectiondefinition-instance>
              <name>MySQLDataSource</name>
              <config-property-setting name="UserName">
                dbuser
              </config-property-setting>
              <config-property-setting name="Password">
                dbpw
              </config-property-setting>
              <config-property-setting name="Driver">
                org.postgresql.Driver
              </config-property-setting>
              <config-property-setting name="ConnectionURL">
                jdbc:postgresql://localhost/mydb
              </config-property-setting>
              <config-property-setting
                                 name="CommitBeforeAutocommit">
                true
              </config-property-setting>
              <config-property-setting
                                  name="ExceptionSorterClass">
                org.tranql.connector.NoExceptionsAreFatalSorter
              </config-property-setting>
              <connectionmanager>
                <local-transaction/>
                <single-pool>
                  <max-size>10</max-size>
                  <min-size>0</min-size>
                  <blocking-timeout-milliseconds>
                    5000
                  </blocking-timeout-milliseconds>
                  <idle-timeout-minutes>30</idle-timeout-minutes>
                  <match-one/>
                </single-pool>
              </connectionmanager>
            </connectiondefinition-instance>
          </connection-definition>
        </outbound-resourceadapter>
      </resourceadapter>
    </connector>
  </resource>
</application-client>

The important elements here are:

In the next section you'll see how to access that pool from application code.