| 13.3. Structure of the Deployment Plan | ||
|---|---|---|
 | Chapter 13. J2EE Connectors (RARs) [DRAFT (1.0)] |  |
| 13.3. Structure of the Deployment Plan | ||
|---|---|---|
| | Chapter 13. J2EE Connectors (RARs) [DRAFT (1.0)] | |
The internal structure of the resource adapter deployment plan looks like this:
The following sections discuss the elements of the deployment plan in more detail -- first the common elements, and then the specifics for inbound and outbound resource adapters and admin objects. Note that the order of the elements is fixed as shown in Figure 13.1, “Resource Adapter Deployment Plan Overview”. Of these elements, the header (discussed above) is required, and each connector requires some resource adapter configuration (though it differs by the type of connector).
The elements in the classloader-infoGroup are used to customized the resource adapter's class path.
The elements here are:
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.
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.
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.
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.
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 configId 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: the Group ID, Artifact ID, Type, and 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 (so 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 configId 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 configIds for your own modules, you may choose to use that format or not as you please. For example, you could use the configId MyConnector, or you could use the configId MyCompany/MyConnector/1.0.5/rar. Therefore, the import element may list a configId URI as a whole String (matching exactly the configId 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:
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/repository/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.
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.
The name of the specific library or configuration (without any version information).
The version number of the specific library or configuration.
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.
Here are some sample imports and dependencies.
Example 13.1. Resource Adapter: Imports and Dependencies
Assume the repository has a file repository/postgresql/jars/postgresql-8.0-314.jdbc3.jar, and the server has a JMS broker configuration called MessagingServer. A resource adapter could refer to them like this:
<import><uri>MessagingServer</uri></import> <dependency> <uri>postgresql/postgresql-8.0/314.jdbc3/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 configId. That would look like this:
<import><uri>MessagingServer</uri></import> <dependency> <groupId>postgresql</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 resourceadapter 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 resourceadapter section.
At a high level, the resource adapter configuration looks like this:
Different types of connectors use different child elements here. Each of those elements holds a number of children for further configuration settings.
These resource adapters handle asynchronous messages arriving from external systems. They use the resourceadapter-instance section for basic configuration.
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.
If a resource adapter support both inbound and outbound communication, it will typically have a resourceadapter-instance section and an outbound-resourceadapter section.
The resourceadapter-instance element has several purposes:
Give the resource adapter a name to identify it
Specify a WorkManager implementation for use with inbound resource adapters
Provide values for the configuration properties specified in the resourceadapter element in the ra.xml deployment descriptor
![[Tip]](images/tip.png) | Tip |
|---|---|
A resourceadapter-instance section should normally be used, unless the resource adapter has no ResourceAdapter implementation (i.e. does not include a resourceadapter-class element in ra.xml). While this sounds silly, it is common for certain outbound-only J2EE Connectors. | |
The contents look like this:
The elements and attributes here are:
Provides a name for this resource adapter. The name will be used to identify the resource adapter through the management interface (see Chapter 20, Management & Monitoring [EMPTY]). It can also be used by a Message-Driven Bean to refer to this resource adapter (see Section 12.3.5, “Message-Driven Beans” for more details on mapping MDBs to inbound resource adapters).
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.
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.
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 (using the procedure in Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY]).
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.
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
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 contents are described in Figure 13.5, “Resource Adapter: objectNameGroup”.
The components of the objectNameGroup are:
The domain name portion of the GBean Name identifying the WorkManager to map to. This should usually be geronimo.server, and if not specified, it defaults to the domain of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo.server unless you have substantially altered your default configuration.
The J2EE Server portion of the GBean Name identifying the WorkManager to map to. This should usually be geronimo, and if not specified, it defaults to the name of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo unless you have substantially altered your default configuration.
The name of the application that the target WorkManager is in. If the WorkManager was deployed as part of a standalone configuration, this would be null. If it was deployed as part of an EAR or module within an EAR, this should be the application-name specified for the EAR, or the configId if no application-name was specified.
The configId of the configuration or application module that the target WorkManager was declared in.
Should be JCAWorkManager.
The name of the target WorkManager as specified in its GBean declaration.
The TranQL JDBC resource adapter (outbound-only) does not have a resource adapter class or any resource adapter level configuration properties, so a Geronimo deployment plan for it does not require a resourceadapter-instance section at all.
The ActiveMQ JMS resource adapter (inbound and outbound) does require a resourceadapter-instance block:
Example 13.2. Resource Adapter: Inbound+Outbound Instance Configuration
This resource adapter needs to specify a name for the resource adapter (for MDBs to use to refer to it), values for several resource adapter level configuration parameters, and a work manager to handle inbound messages:
<resourceadapter-instance>
<resourceadapter-name>ActiveMQ RA</resourceadapter-name>
<config-property-setting name="ServerUrl">
tcp://localhost:61616
</config-property-setting>
<config-property-setting name="UserName">
geronimo
</config-property-setting>
<config-property-setting name="Password">
secret
</config-property-setting>
<workmanager>
<gbean-link>DefaultWorkManager</gbean-link>
</workmanager>
</resourceadapter-instance>The outbound resource adapter configuration is the most complex part of the resource adapter deployment plan.
The important elements and attributes here are:
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.
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.
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.
The name of the connection definition instance is how resource references in the server will identify this specific connection configuration. It must be unique across all resources deployed at the same scope (server-level if deployed standalone, or within the application if deployed within an EAR). Further, it will be easiest to configure references to this resource if the name is unique across all resources deployed in the server.
In general, the connectionfactory-interface provides the interface that clients will use to interact with connections from this configuration. However, there are some cases (such as JMS) where the connection factory implements more than one interface (i.e. ConnectionFactory, QueueConnectionFactory, and TopicConnectionFactory). Geronimo wraps the underlying objects, and only exposes to clients something that implements the connectionfactory-interface, plus any interfaces listed here. The interfaces should be listed by their fully-qualified class names.
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.
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 matching connection-definition element of the ra.xml.
Described in detail next, this element configures connection pooling, security, and transactions for connections from this factory.
The only element not fully described above is the connectionmanager -- it has very detailed settings of its own. The Connection Manager controls security, transaction, and connection pooling settings for connections through an outbound resource adapter.
The important elements and attributes here are:
Security Settings
If this element is present, the connector will use either the currently logged-on user or a pre-configured user if it needs to authenticate to the back-end server or resource. If this element not present, the client and/or connector must produce the authentication information to use. Container-managed security is usually fine unless each client component needs to manually pass a username and password to connect. Note that the setting here may be overridden when a component declares a resource reference pointing to this connector and sets the res-auth in the resource reference to Container or Application.
Transaction Settings
There are three possible transaction settings: none, local, and XA. The ra.xml file defines what transaction level a resource adapter supports, but the transaction behavior can be fine-tuned here. If no transaction setting is specified, it defaults to the same transaction level specified in ra.xml with the default behavior.
If this element is present, then the resource adapter will not participate in transactions. It should be used for resource adapters supporting no transactions.
If this element is present, then the resource adapter will participate in local transactions -- that is, transactions where the resource adapter is the only resource involved. It should be used for resource adapters supporting local transactions.
If this element is present, then the resource adapter will participate in XA transactions -- that is, transactions with one or multiple resources participating (for example, a database change and a JMS delivery in the same transaction). This element should be used for resource adapters supporting XA transactions.
Enables connection sharing for resources in the same transaction. If a component attempts to acquire a shareable connection, and another component in the same transaction has already acquired a shareable connection to the same resource, that connection will be returned again and used by both components. Note that whether a resource is shareable is configured in the resource reference in the standard J2EE deployment descriptor for the component that will acquire the resource (using the res-sharing-scope element). This is recommended. It is enabled if this element is present and disabled if the element is not present.
This is an experimental setting to be used when the number of connections in the pool equals or exceeds the number of worker threads in the server. Each worker thread gets one connection, and all work done by that thread uses that connection. It is quite efficient because there is no overhead of managing a connection pool. However, it is not currently well tested in practice (and there is not a single place to limit the number of worker threads across all of Geronimo). It is enabled if this element is present and disabled if the element is not present.
This is a special option that can be used for local-transaction JDBC resources only. It makes a local JDBC resource behave like an XA resource so it can participate in XA transactions with other XA resources. However, only one JDBC resource with this setting can participate in any single transaction. In short, this is the easy way to use transactions that span exactly one normal JDBC connection pool and other native XA resources like JMS destinations. It should be used for resource adapters which declared in ra.xml that they support local transaction, and then Geronimo will allow them to participate in XA transactions.
Connection Pooling Type
Connection pooling can be used to share a small number of connections across a large number of requests over time. When a caller closes a connection, it is not really closed, only returned to the pool so it can be reused later by a different caller. This saves the overhead of opening and closing connections on every request, which can often be substantial. It can also be used to limit the total number of connections opened by the application it the same time -- no matter how high the application load gets, the server will never open more connections than the max size of the pool. While the limit is higher for partitioned pools, there generally still is a limit.
If this element is present, connections will not be pooled. Every request that makes it past the cache settings will open a new connection to the resource, and the connection will be closed when released. This will not be very efficient if the process of connecting to the back end data source is a time-consuming or resource-intensive process (which is often the case).
If this element is present, all connections to the resource will be pooled using a single connection pool. This is the most efficient type of pool, but it means that each connection may be reused by a caller attempting to use very different connection settings.
If this element is present, there will actually be a number of connection pools, determined by the partition type. For example, if partitioned by Subject, there would be one connection pool for each Subject. Note that the maximum size applies to each partition; if the maximum pool size was 10 and there were 50 Subjects, the partitioned pool could grow to 500 connections!
| Tip |
|---|---|
Single pools are best for cases where all connections in the pool will be effectively interchangeable. For example, a JDBC connection pool that's always accessed with container-managed authentication (and the same database username and password). If an application used different database authentication for every request, then the pool might fill up with connections for a small number of database logins, and requests for connections using other logins would fail because the pool was full. That is exactly the situation where partitioned pools are better, because the pool could be partitioned by database login and each login would effectively get its own connection pool. However the limit on the total number of connections across all partitions of a partitioned pool is typically much higher than it would be for a single pool, so a partitioned pool is not as efficient when it comes to minimizing the pool size. | |
These settings can be used to customize a connection pool. A single-pool configuration looks like this:
The elements introduced here are:
Connection Pool Size Settings
The maximum size of a single pool, or the maximum size of a partition within a partitioned pool.
The minimum size of a single pool, or the minimum size of a partition within a partitioned pool. The pool will try to fill itself to its minimum size if it notices that it's fallen below that.
If a component requests a connection from the pool, all connections are in use, and the pool is at it's maximum size, the request will block until a connection becomes available or this timeout expires. If the timeout is reached, an error will be returned to the requesting component. The component may try again, though if it's in a transaction, a transaction timeout may eventually cut it off.
If a connection has been unused for at least this long, it is subject to be closed and removed from the pool. The task that checks for this checks as often as the value set here, so in the worst possible case (connection last used right after last check), a connection could go unused for almost twice this time.
Connection Pool Match Settings
When a caller requests a connection from the pool, it may pass certain request information to the pool (and the server also adds in the current Subject). Exactly what request information the caller can pass (ant what counts as a "match") would be specific to the connector type. The connection pool match settings determine how connections in the pool are evaluated to see if they are appropriate to return based on the current Subject and request information.
This is the high-performance setting. It just grabs a connection from the pool and assumes that it works, regardless of the current Subject or connection request information. This can be used if you are sure that all connections are totally equivalent, but it may cause problems if you're wrong. This is usually recommended for partitioned pools, if the partitioning guarantees that the eventual pool will only hold matching connections.
This a safer version of select-one-assume-match. It picks a single connection from the pool and tests only that connection and returns it if the connection matches. If the connection does not match, it throws an error to the effect of "please adjust your configuration and try again". This should be used if you're pretty confident that all pooled connections are equivalent, but you don't want to take any chances. It is the recommended setting for JDBC connection pools with container-managed security.
This is the high-reliability setting. It tests all the available connections in the pool to find one that matches the request information and Subject. It will likely be slower than the alternatives. It should be used if you're not familiar with the configuration or capabilities of the resource adapter, so you don't know what might count as a match. It must be used if you know the connection pool will hold a variety of connections, some of which will match any given request and some of which will not (for example, a JDBC connection pool configured as a single-pool with application-managed security and multiple database logins).
A partitioned pool is configured in essentially the same way as a single pool, except it adds partitioning settings. Each partition will behave like a single pool using all the settings common between this and the single pool, and the partitioning settings control how the pools are partitioned. The configuration looks like this:
Most of these elements are the same as for single pools (described in the previous section). The partitioning elements introduced here are:
When this element is present, there will be a separate partition for each Subject (that is, each separate authenticated caller who uses the resource adapter).
When this element is present, there will be a separate partition for each set of connection request information. The presence and content of the connection request information depends on the specific resource adapter. For example, the TranQL JDBC connection pool resource adapter includes the database username and password in the connection request information, while the ActiveMQ resource adapter includes the URL, username, and password used to connect to the ActiveMQ broker, as well as the JMS client ID.
A typical JDBC connection pool with a pre-configured username and password might use a connection manager configuration like this:
Example 13.3. Resource Adapter: Connection Manager (Typical JDBC Pool)
This connection manager uses container-managed security, local transactions, and a single pool configured with the safe match-one matching strategy:
<connectionmanager>
<container-managed-security />
<local-transaction />
<single-pool>
<max-size>100</max-size>
<blocking-timeout-milliseconds>
5000
</blocking-timeout-milliseconds>
<match-one/>
</single-pool>
</connectionmanager>A JDBC connection pool where each caller specifies a different username and password to connect (via DataSource.getConnection(username, password)) might use a connection manager configuration like this:
Example 13.4. Resource Adapter: Connection Manager (Per-User JDBC Pool)
This connection manager uses application-managed security, XA transactions with shared connections within a transaction, and a separate pool for each username:
<connectionmanager>
<xa-transaction>
<transaction-caching/>
</xa-transaction>
<partitioned-pool>
<max-size>100</max-size>
<blocking-timeout-milliseconds>
5000
</blocking-timeout-milliseconds>
<match-one/>
<partition-by-connectionrequestinfo/>
</partitioned-pool>
</connectionmanager>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]](images/note.png) | 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 | |
The first two elements define which type of administered object is being deployed in this block:
Matches the adminobject-interface specified for this adminobject type in ra.xml.
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.
The parent element that holds the other elements described here
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).
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.
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 example shows how admin objects are configured for the ActiveMQ JMS resource adapter.
Example 13.5. Resource Adapter: Admin Object Configuration
The ra.xml excerpt below declares two admin object types, one for topics and one for queues, each of which takes a single String parameter called "PhysicalName":
<adminobject>
<adminobject-interface>javax.jms.Queue</adminobject-interface>
<adminobject-class>
org.activemq.message.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.activemq.message.ActiveMQTopic
</adminobject-class>
<config-property>
<config-property-name>PhysicalName</config-property-name>
<config-property-type>java.lang.String</config-property-type>
</config-property>
</adminobject>The geronimo-ra.xml deployment plan creates specific admin object instances, configuring a number of admin object instances for each available admin object type. The excerpt below adds two queues and no topics:
<adminobject>
<adminobject-interface>javax.jms.Queue</adminobject-interface>
<adminobject-class>
org.codehaus.activemq.message.ActiveMQQueue
</adminobject-class>
<adminobject-instance>
<message-destination-name>TestDest</message-destination-name>
<config-property-setting name="PhysicalName">
TestQueue
</config-property-setting>
</adminobject-instance>
<adminobject-instance>
<message-destination-name>ErrDest</message-destination-name>
<config-property-setting name="PhysicalName">
ErrorQueue
</config-property-setting>
</adminobject-instance>
</adminobject>The gbean element lets you configure additional Geronimo services which will be deployed when the resource adapter is deployed (and stopped when the resource adapter is stopped). Normally, the implementation classes for these services are still included at the server level, and referenced using a dependency element.
A full description of the syntax for deploying GBeans is covered in Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY]. In general, the gbean element and its attributes define a GBean, and the child elements are used to configure the GBean.
| |  | |
| 13.2. The Resource Adapter Geronimo Deployment Plan |  | 13.4. Sample Resource Adapter Configurations |
