Configuring JDBC Resources
|
|
JDBC resources in Geronimo are nothing more than a deployment plan for a resource adapter. In this chapter, the tranql-connector-1.2.rar file will be resource adapter that is being configured. Taking a peek at existing deployment plans that are already part of Geronimo is a good place to start because it will provide a base understanding before moving on to the PostgreSQL-specific deployment plan.
Listing 13-2 shows the system-database deployment plan. This section will focus on paring down this plan to manually create a deployment plan for PostgreSQL.
Listing 13-2: The system-database Deployment Plan
 |
<?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>geronimo</dep:groupId> <dep:artifactId>system-database</dep:artifactId> <dep:version>1.1</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>j2ee-server</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>geronimo-derby</dep:artifactId> <dep:type>jar</dep:type> <dep:import>classes</dep:import> </dep:dependency> <dep:dependency> <dep:groupId>org.apache.derby</dep:groupId> <dep:artifactId>derby</dep:artifactId> <dep:type>jar</dep:type> <dep:import>classes</dep:import> </dep:dependency> <dep:dependency> <dep:groupId>org.apache.derby</dep:groupId> <dep:artifactId>derbynet</dep:artifactId> <dep:type>jar</dep:type> <dep:import>classes</dep:import> </dep:dependency> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>geronimo-timer</dep:artifactId> <dep:type>jar</dep:type> <dep:import>classes</dep:import> </dep:dependency> </dep:dependencies> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.sql.DataSource</connectionfactory- interface> <connectiondefinition-instance> <name>SystemDatasource</name> <config-property-setting name="UserName"/> <config-property-setting name="Password"/> <config-property-setting name="DatabaseName">SystemDatabase</config- property-setting> <config-property-setting name="CreateDatabase">true</config-property- setting> <connectionmanager> <xa-transaction> <transaction-caching/> </xa-transaction> <single-pool> <max-size>100</max-size> <blocking-timeout-milliseconds>5000</blocking-timeout-milliseconds> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> <gbean name="DerbySystem" > <reference name="ServerInfo"> <name>ServerInfo</name> </reference> <attribute name="derbySystemHome">var/derby</attribute> </gbean> <gbean name="DerbyNetwork" > <reference name="derbySystem"> <name>DerbySystem</name> </reference> <attribute name="host">localhost</attribute> <attribute name="port">1527</attribute> </gbean> <gbean name="DerbyLog" > <reference name="DerbySystem"> <name>DerbySystem</name> </reference> </gbean> <gbean name="TransactionalThreadPooledTimer" > <attribute name="repeatCount">5</attribute> <reference name="TransactionContextManager"> <name>TransactionContextManager</name> </reference> <reference name="ManagedConnectionFactoryWrapper"> <name>SystemDatasource</name> </reference> <reference name="ThreadPool"> <name>DefaultThreadPool</name> </reference> <dependency> <name>DerbySystem</name> </dependency> </gbean> <gbean name="NonTransactionalThreadPooledTimer" > <reference name="TransactionContextManager"> <name>TransactionContextManager</name> </reference> <reference name="ManagedConnectionFactoryWrapper"> <name>SystemDatasource</name> </reference> <reference name="ThreadPool"> <name>DefaultThreadPool</name> </reference> <dependency> <name>DerbySystem</name> </dependency> </gbean> </connector>
|
Listing 13-2 contains the system-database deployment plan. This deployment plan uses the Apache Derby database, so some of the dependencies, the config-property-setting elements and the GBeans are very Derby-specific and do not apply to other databases. For example, PostgreSQL would not recognize the parameter list in Listing 13-2 named CreateDatabase. Also note that there is no JDBC URL included in the previous plan. This is because the plan is deployed with a JCA connector for the Derby embedded database that doesn’t require a URL because it makes use of Derby’s embedded API.
Conversely, PostgreSQL requires parameters that Derby would not understand. The only idea in starting with the system-database plan is that it provides a place to begin to understand an example that already works properly. To understand this plan fully, let’s examine the contents a bit more.
Table 13-2 contains the allowed content for a JCA connector and resource adapter for JDBC resources.
| Item | Description |
|---|---|
| environment | An encapsulating root element for the module plan file. |
| connector | The root element of the deployment descriptor for the resource adapter. This element includes general information and also includes information specific to the implementation of the resource adapter library as specified through the element resourceadapter. |
| moduleId | The unique identifier for the descriptor. |
| dependencies | Holds all the dependency information. |
| hidden-classes | A list of classes that will never be loaded from parent class loaders of this module. The classes are specified in zero or more child filter elements where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden. |
| non-overridable-classes | A list of classes that will only be loaded from parent class loaders of this module (never from the module’s own class loader). Just as with the hidden-classes element, the classes are specified in zero or more child filter elements where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden. |
| resourceadapter | A container element holding the resourceadapter-instance and outbound-resourceadapter elements. |
| workmanager | A container element holding one of gbean-link, target-name, or a group of elements including domain, server, application, module, type, and name. The work manager handles work on behalf of the resource adapter in a parallel-processing manner. |
| resourceadapter-instance | A container element to hold the necessary information about the resource adapter and its configuration. |
| resourceadapter-name | A simple name for the resource adapter. |
| outbound-resource adapter | Specifies information about an outbound resource adapter, including 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. |
| connection-definition | A container element holding information about a connection that implements a particular interface. |
| connectionfactory-interface | The fully qualified package path to the implemented interface. |
| connection definition-instance | Additional interfaces implemented by the connection factory, used by the application. |
| implemented-interface | The actual interface that the implementation covers. |
| connectionmanager | The configuration of the connection manager. |
| container-managed-security | A wrapper element containing information to customize the container managed security. |
| no-transaction | An empty marker element indicating that the resource adapter does not participate in transactions. |
| local-transaction | An element indicating that the resource adapter can participate in local transactions only. |
| xa-transaction | An element indicating that the resource adapter can participate in distributed transactions. |
| transaction-caching | An element that allows resources to be shared during the duration of the transaction. This is dependent upon whether the resource has been marked as shareable. |
| thread-caching | An element that allows the sharing of a single connection across transactions. |
| transaction-log | An element that allows a local JDBC resource to be able to participate in XA transactions. |
| no-pool | Indicates that no connection pool should be used (that is, each request will cause a new connection to be established). |
| single-pool | Indicates that a single connection pool should be used. |
| match-one | This element indicates that the first connection acquired from the pool should be tested for validity against the pooling criteria. |
| match-all | This element indicates that all connection acquired from the pool should be tested for validity against the pooling criteria. |
| select-one-assume-match | This element indicates that no connections acquired from the pool should be tested. |
| partitioned-pool | Indicates that a partitioned connection pool should be used. Partitioned connection pools are segregated into many single pools, using one of the marker subelements of partition-by-subject or partition-by-connectionrequestinfo. |
| partition-by-subject | An element to indicate that one partition per subject should be used. |
| partition-by-connection requestinfo | An element indicating that one partition per set of connection request information. |
| max-size | The maximum number of connections in a single pool or a partitioned pool. Once this size is reached, requests will begin to block until a connection becomes available. The default is 10. |
| min-size | The minimum number of connections in a single pool or a partitioned pool. The default is zero. |
| blocking-timeout-milliseconds | This element indicates the timeout period when waiting for a connection to be returned from a pool when all connections in a pool are in use and the pool has already reached its max-size. The default is 5000 milliseconds. |
| idle-timeout-minutes | The amount of time a connection is allowed to go unused before it is automatically closed. The default is 15 minutes. |
| adminobject | Specifies information about an administered object. Administered objects are specific to a messaging style or message provider. This contains information on the Java type of the interface implemented by an administered object, its Java class name, and its configuration properties. |
| adminobject-interface | The interface implemented by the adminobject-class element. |
| adminobject-class | The implementation class of the adminobject-interface element. |
| adminobject-instance | A container element holding the configuration information for this adminobject element. |
| message-destination-name | A unique name for the adminobject to be used for the JNDI ENC. |
| config-property-setting | Contains an arbitrary name/value pair for configuration of the adminobject. |
| gbean | An element for describing GBeans within the resource adapter. |
Open table as spreadsheetTable 13-1 covers the geronimo-connector-1.1 schema but not the connector-1.5 schema, so it’s not 100 percent exhaustive.
Table 13-2 defines the allowed contents of an instance of a resource adapter deployment plan. Now that the allowed content has been presented, the content of the instance in Listing 13-2 should be explored and Table 13-3 does just that.
| Item | Description |
|---|---|
| geronimo/system-database/1.1/car | This is the unique ID that is generated by flattening the contents of the moduleId element. This string doesn’t reside in the ra.xml but is used to uniquely identify it throughout Geronimo. |
| dependencies | The necessary dependencies for the TranQL Derby embedded resource adapter configuration. |
| javax.sql.DataSource | The fully qualified package name of the interface to be used by the connection factory. |
| <connection definition-instance> | This element contains as many config-property-setting elements as are necessary to define metadata for the connection (for example, username, password, JDBC URL, and so on). In addition, other elements are present for the configuration of the connection manager. In this particular case, there exists a parameter named CreateDatabase. This is specific to Derby and instructs the database engine to create the database if it does not already exist. |
| SystemDatasource | This is a simple string name for this connection definition instance. |
| <connectionmanager> | The connection manager is responsible for actually handling the JDBC connection pool. The contained elements inform the connection manager to participate in distributed transactions, to share connections among components, and to maintain a single connection pool whose maximum size is 100 connections with a blocking timeout of 5000 milliseconds to wait for any connection to become available and to test only one connection in the pool. |
| DerbySystem | This is a GBean that can be found already deployed to the kernel that is identified by this unique name. It is used to start an embedded instance of Derby. This is referring to the org.apache.geronimo.derby.DerbySystemGBean object. |
| DerbyNetwork | This is a GBean that can also be found already deployed to the kernel that is identified by this unique name. This GBean is used to manage network access to the embedded instance of Derby. This refers to the org.apache.geronimo.derby.DerbyNetworkGBean object. |
| Transactional ThreadPooledTimer | This is an implementation of a java.util.Timer that is persistent and transactional. |
| NonTransactional ThreadPooledTimer | This is an implementation of a java.util.Timer that is persistent but not transactional. |
Table 13-2 documents the allowed contents of the system database deployment plan, and Table 13-3 documents an instance of that plan. This is a fairly straightforward configuration of a resource adapter for a JDBC resource. With this complete, the next task is to deploy this resource so that it’s made available for use with the Geronimo server.
Creating a JDBC Deployment Plan for PostgreSQL
Creating a deployment plan for PostgreSQL is not all that different from the Apache Derby deployment plan that was reviewed earlier in this chapter. In fact, a very basic deployment plan is actually even easier than the system database deployment plan that starts up Derby. Listing 13-3 shows a deployment plan named postgresql-plan.xml.
Listing 13-3: A deployment Plan for PostgreSQL
|
<?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>postgresql</dep:groupId> <dep:artifactId>postgresql</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>postgresql</dep:groupId> <dep:artifactId>postgresql-8.1</dep:artifactId> <dep:version>404.jdbc3</dep:version> <dep:type>jar</dep:type> </dep:dependency> </dep:dependencies> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface> javax.sql.DataSource </connectionfactory-interface> <connectiondefinition-instance> <name>PostgreSQLDataSource</name> <config-property-setting name="UserName"> geronimo </config-property-setting> <config-property-setting name="Password"> geronimo </config-property-setting> <config-property-setting name="Driver"> org.postgresql.Driver </config-property-setting> <config-property-setting name="ConnectionURL"> jdbc:postgresql://localhost:5432/test </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>
|
The only real difference that this plan has over the system-database plan outlined previously is the inclusion of a global JNDI name. Table 13-4 contains a breakdown of the deployment plan for PostgreSQL.
| Item | Description |
|---|---|
| PostgreSQLDatabase | This is the unique ID for this deployment plan. The only requirement of this attribute is that it be a unique string. |
| dependencies | The necessary dependencies for the generic TranQL resource adapter. |
| postgresql/jars/postgresql-8.0-312.jdbc3.jar | This is a jar dependency that must be deployed to the kernel prior to this plan being deployed. The path to the PostgreSQL JDBC driver jar is relative to the Geronimo repository. (That is, the PostgreSQL JDBC drivers will need to be placed in the repository in this directory structure.) |
| javax.sql.DataSource | The fully qualified package name of the interface used by the connection factory. |
| <connection definition-instance> | This element contains as many config-property-setting elements as is necessary to define metadata for the connection (for example, username, password, JDBC URL, and so on). In addition, other elements are present for the configuration of the connection manager. |
| PostgreSQLDataSource | This is a simple string name for this connection definition instance. |
| <connectionmanager> | The connection manager is responsible for handling the JMS connections. The elements contained herein tell the connection manager to participate in distributed transactions, to share connections among components, and to maintain a single connection pool whose maximum size is 10 connections with a blocking timeout of 5000 milliseconds to wait for any connection to become available and to test only one connection in the pool. |
Table 13-4 documents the contents of the deployment plan for PostgreSQL. This is a fairly straightforward configuration of a resource adapter for a JDBC resource. With this complete, the next task is to deploy this resource so that it’s made available for use with the Geronimo server.
|
|
EAN: 2147483647
Pages: 148