www.ironjacamar.orgCommunity Documentation

Chapter 5. Deployment

Table of Contents

5.1. Packaging requirements
5.2. Deploying resource adapters
5.2.1. Resource adapter descriptor
5.2.2. Resource adapter extensions
5.2.3. Resource adapter statistics
5.3. Deploying datasources
5.3.1. Datasource descriptor
5.3.2. Datasource extensions
5.3.3. Datasource statistics
5.4. General deployment settings
5.4.1. Flush strategies
5.4.2. Capacity policies

The IronJacamar distribution contains a deploy/ directory where all deployments should be deployed to.

A resource adapter archive is a structured Java Archive (JAR) file, which bundles all Java classes in JAR files, and optionally contains metadata, resources and native libraries.

A resource adapter archive name ends in the .rar extension.

An example of a resource adapter archive could look like


[jpederse@localhost]$ jar tf ra.rar
META-INF/ra.xml
readme.html
ra.jar
images/icon.jpg
win.dll
linux.so
 
      

See the Java EE Connector Architecture 1.7 specification chapter 20 for further requirements.

Resource adapters (.rar) are deployed by copying the resource adapter into the deploy/ directory

cp example.rar ironjacamar-1.1.0.Final/deploy
     

on a Un*x based system or

copy example.rar ironjacamar-1.1.0.Final\deploy
     

on Windows.

The resource adapter can be configured and activated through a META-INF/ironjacamar.xml file in the archive. The format of the XML document is defined by the ironjacamar_1_0.xsd or ironjacamar_1_1.xsd schemas.

A resource adapter can also be configured and activated through deployment of a -ra.xml file in the deploy/ directory - f.ex. deploy/example-ra.xml. The format of the XML document is defined by the resource-adapters_1_0.xsd or resource-adapters_1_1.xsd schemas - f.ex




<resource-adapters>
  <resource-adapter>
    <archive>example.rar</archive>
    <connection-definitions>
      <connection-definition jndi-name="java:/eis/example" class-name="com.example.ra.MCF"/>
    </connection-definitions>
  </resource-adapter>
</resource-adapters>

     

to bind the connection factory from com.example.ra.MCF under java:/eis/example.

See the schema appendix for additional details about the format.

Alternative the resource adapter deployments will be picked up by the RAActivator bean which bind a single connection factory under

java:/eis/<deploymentName>
     

- f.ex. java:/eis/example and a single admin object under

java:/eis/ao/<deploymentName>
     

- f.ex. java:/eis/ao/example.

A resource adapter can be configured using two different ways

to the resource adapter archive. Both formats share the same layout to ease configuration - only the top-level elements differ.






Table 5.6. XA pool elements

ElementDesciption
min-pool-size The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
initial-pool-size The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.1)
max-pool-size The max-pool-size element indicates the maximum number of connections for a pool. No more than max-pool-size connections will be created in each sub-pool. This defaults to 20.
prefill Whether to attempt to prefill the connection pool. Default is false
use-strict-min Specifies if the min-pool-size should be considered strictly. Default false
flush-strategy Specifies how the pool should be flush in case of an error. Valid values are: FailingConnectionOnly (default), InvalidIdleConnections (1.1), IdleConnections, Gracefully (1.1), EntirePool, AllInvalidIdleConnections (1.1), AllIdleConnections (1.1), AllGracefully (1.1), AllConnections (1.1)
capacity Specifies the capacity policies (1.1)
is-same-rm-override The is-same-rm-override element allows one to unconditionally set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns true or false
interleaving An element to enable interleaving for XA connection factories
no-tx-separate-pools Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts
pad-xid Should the Xid be padded
wrap-xa-resource Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper instance






The deployment schemas are defined in doc/ironjacamar_1_0.xsd, doc/ironjacamar_1_1.xsd, doc/resource-adapters_1_0.xsd and doc/resource-adapters_1_1.xsd.

A resource adapter can make use of a couple of Java EE Connector Architecture extensions in the IronJacamar container in order to improve the integration.

The extensions include

The following sections will describe these extensions points.

The IronJacamar recovery extension allows the resource adapter deployment to give feedback to the container if a ManagedConnection can be used for recovery. This extension is used as part of XA recovery in the environment, and should therefore be implemented by all resource adapters capable of working in an XATransaction semantics.

The interface org.jboss.core.spi.recovery.RecoveryPlugin located in the ironjacamar-core-api artifact makes up the SPI for the extension.

The interface contains two methods that should be implemented in a resource adapter specific manner.

The method

public boolean isValid(Object c) throws ResourceException;
            

will return true if the connection can be used for recovery.

The method

public void close(Object c) throws ResourceException;
            

will close a connection that was used for recovery.

The recovery extension is activated by adding a recovery element to the deployment

<recovery>
   <recovery-plugin>com.mycompany.myproject.RecoveryPluginImpl</recovery-plugin>
</recovery>
            

The following recovery plugins are provided by IronJacamar

Resource adapter deployments has the following core statistics values

Table 5.12. Core statistics

NameDesciption
ActiveCount The number of active connections. Each of the connections is either in use by an application or available in the pool
AvailableCount The number of available connections in the pool
AverageBlockingTime The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds
AverageCreationTime The average time spent creating a connection. The value is in milliseconds
AverageGetTime The average time spent obtaining a connection. The value is in milliseconds
BlockingFailureCount The number of times where there was a time out getting an exclusive lock on the pool
CreatedCount The number of connections created
DestroyedCount The number of connections destroyed
IdleCount The number of connections currently idle
InUseCount The number of connections currently in use
MaxCreationTime The maximum time it took to create a connection. The value is in milliseconds
MaxGetTime The maximum time it took to obtain a connection. The value is in milliseconds
MaxUsedCount The maximum number of connections used
MaxWaitCount The maximum number of requests waiting for a connection at the same time
MaxWaitTime The maximum time spent waiting for an exclusive lock on the pool
TimedOut The number of timed out connections
TotalBlockingTime The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds
TotalCreationTime The total time spent creating connections. The value is in milliseconds
TotalGetTime The total time spent obtaining connections. The value is in milliseconds
WaitCount The number of requests that had to wait for a connection


Datasources (-ds.xml) are deployed by copying the definition into the deploy/ directory

cp postgres-xa-ds.xml ironjacamar-1.1.0.Final/deploy
      

on a Un*x based system or

copy postgres-xa-ds.xml ironjacamar-1.1.0.Final\deploy
      

on Windows.

You will need to install the database JDBC driver into the lib/ directory.

You can find examples of datasource definitions in the doc/datasources directory and the schemas: doc/datasources_1_0.xsd, doc/datasources_1_1.xsd and doc/datasources_1_1.xsd.

Datasource descriptors are divided into

definitions.

A datasource descriptor supports the following parameters.


Table 5.14. datasource elements

ElementDesciption
connection-url The JDBC driver connection URL
driver-class The fully qualifed name of the JDBC driver class
datasource-class The fully qualifed name of the JDBC datasource class
driver

An unique name for the JDBC driver specified in the drivers section. Or the name of the .jar file if deployed as standalone deployment

This element is mandatory when deploying in WildFly

connection-property The connection-property element allows you to pass in arbitrary connection properties to the Driver.connect(url, props) method. Each connection-property specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content
new-connection-sql Specify an SQL statement to execute whenever a connection is added to the connection pool
transaction-isolation Set java.sql.Connection transaction isolation level to use. The constants defined by transaction-isolation-values are the possible transaction isolation levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
url-delimiter Specifies the delimeter for URLs in connection-url for HA datasources
url-selector-strategy-class-name A class that implements org.jboss.jca.adapters.jdbc.spi.URLSelectorStrategy
pool Specifies the pooling settings
security Specifies the security settings
validation Specifies the validation settings
timeout Specifies the time out settings
statement Specifies the statement settings

Table 5.15. xa-datasource elements

ElementDesciption
xa-datasource-property Specifies a property to assign to the XADataSource implementation class. Each property is identified by the name attribute and the property value is given by the xa-datasource-property element content. The property is mapped onto the XADataSource implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the java.beans.PropertyEditor for the type
xa-datasource-class The fully qualifed name of the javax.sql.XADataSource implementation class
driver

An unique name for the JDBC driver specified in the drivers section. Or the name of the .jar file if deployed as standalone deployment.

This element is mandatory when deploying in WildFly

url-delimiter Specifies the delimeter for URLs in the connection url for HA datasources
url-property Specifies the property for the URL property in the xa-datasource-property values (1.2)
url-selector-strategy-class-name A class that implements org.jboss.jca.adapters.jdbc.spi.URLXASelectorStrategy
new-connection-sql Specifies an SQL statement to execute whenever a connection is added to the connection pool
transaction-isolation Set java.sql.Connection transaction isolation level to use. The constants defined by transaction-isolation-values are the possible transaction isolation levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
xa-pool Specifies the pooling settings
security Specifies the security settings
validation Specifies the validation settings
timeout Specifies the time out settings
statement Specifies the statement settings
recovery Specifies the recovery settings

Table 5.16. Pool settings

ElementDesciption
min-pool-size The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
initial-pool-size The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.2)
max-pool-size The max-pool-size element indicates the maximum number of connections for a pool. No more connections will be created in each sub-pool. This defaults to 20
prefill Whether to attempt to prefill the connection pool. Empty element denotes a true value. Default is false
use-strict-min Define if the min-pool-size should be considered a strictly. Default false
flush-strategy Specifies how the pool should be flush in case of an error. Valid values are: FailingConnectionOnly (default), InvalidIdleConnections (1.2), IdleConnections, Gracefully (1.2), EntirePool, AllInvalidIdleConnections (1.2), AllIdleConnections (1.2), AllGracefully (1.2), AllConnections (1.2)
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method and hence if the internal pool type should account for that (1.1)
capacity Specifies the capacity policies (1.2)
connection-listener An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides a possible to listen for connection activation and passivation in order to perform actions before the connection is returned to the application or returned to the pool (1.2)

Table 5.17. XA pool settings

ElementDesciption
min-pool-size The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
initial-pool-size The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.2)
max-pool-size The max-pool-size element indicates the maximum number of connections for a pool. No more connections will be created in each sub-pool. This defaults to 20
prefill Whether to attempt to prefill the connection pool. Empty element denotes a true value. Default is false
use-strict-min Define if the min-pool-size should be considered a strictly. Default false
flush-strategy Specifies how the pool should be flush in case of an error. Valid values are: FailingConnectionOnly (default), InvalidIdleConnections (1.2), IdleConnections, Gracefully (1.2), EntirePool, AllInvalidIdleConnections (1.2), AllIdleConnections (1.2), AllGracefully (1.2), AllConnections (1.2)
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method and hence if the internal pool type should account for that (1.1)
capacity Specifies the capacity policies (1.2)
connection-listener An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides a possible to listen for connection activation and passivation in order to perform actions before the connection is returned to the application or returned to the pool (1.2)
is-same-rm-override The is-same-rm-override element allows one to unconditionally set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns true or false
interleaving An element to enable interleaving for XA connection factories
no-tx-separate-pools Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts
pad-xid Should the Xid be padded
wrap-xa-resource Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper instance


Table 5.19. Validation settings

ElementDesciption
valid-connection-checker An org.jboss.jca.adapters.jdbc.spi.ValidConnectionChecker that provides a SQLException isValidConnection(Connection e) method to validate is a connection is valid. An exception means the connection is destroyed. This overrides the check-valid-connection-sql when present
check-valid-connection-sql Specify an SQL statement to check validity of a pool connection. This may be called when managed connection is taken from pool for use.
validate-on-match The validate-on-match element indicates whether or not connection level validation should be done when a connection factory attempts to match a managed connection for a given set. This is typically exclusive to the use of background validation
background-validation An element to specify that connections should be validated on a background thread versus being validated prior to use
background-validation-millis The background-validation-millis element specifies the amount of time, in milliseconds, that background validation will run
use-fast-fail Whether fail a connection allocation on the first connection if it is invalid (true) or keep trying until the pool is exhausted of all potential connections (false) default false
stale-connection-checker An org.jboss.jca.adapters.jdbc.spi.StaleConnectionChecker that provides a boolean isStaleConnection(SQLException e) method which if it it returns true will wrap the exception in an org.jboss.jca.adapters.jdbc.StaleConnectionException which is a subclass of SQLException
exception-sorter An org.jboss.jca.adapters.jdbc.spi.ExceptionSorter that provides a boolean isExceptionFatal(SQLException e) method to validate is an exception should be broadcast to all javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message

Table 5.20. Time out settings

ElementDesciption
blocking-timeout-millis The blocking-timeout-millis element indicates the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 30000 (30 seconds).
idle-timeout-minutes The idle-timeout-minutes elements indicates the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.
set-tx-query-timeout Whether to set the query timeout based on the time remaining until transaction timeout, any configured query timeout will be used if there is no transaction. The default is false
query-timeout Any configured query timeout in seconds The default is no timeout
use-try-lock Any configured timeout for internal locks on the resource adapter objects in seconds The default is a 60 second timeout
allocation-retry The allocation retry element indicates the number of times that allocating a connection should be tried before throwing an exception. The default is 0.
allocation-retry-wait-millis The allocation retry wait millis element indicates the time in milliseconds to wait between retrying to allocate a connection. The default is 5000 (5 seconds).
xa-resource-timeout Passed to XAResource.setTransactionTimeout() Default is zero which does not invoke the setter. In seconds





The datasource deployment schema is defined in doc/datasources_1_0.xsd and doc/datasources_1_1.xsd.

The datasource deployments can make use of a couple of extensions in the JDBC resource adapter to improve the connection validation and checking if an exception should reestablish the connection in question.

The extensions include

Configuration of the extensions are done by using

IronJacamar features implementations of these extensions for a couple of popular databases. Contributions in this area are most welcome either generic solutions or for a specific database.

Informix:

Microsoft SQLServer:

PostgreSQL:

MySQL:

IBM DB2:

Generic:

Sybase:

Oracle:

Datasources has the following core statistics values

Table 5.25. Core statistics

NameDesciption
ActiveCount The number of active connections. Each of the connections is either in use by an application or available in the pool
AvailableCount The number of available connections in the pool
AverageBlockingTime The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds
AverageCreationTime The average time spent creating a connection. The value is in milliseconds
AverageGetTime The average time spent obtaining a connection. The value is in milliseconds
BlockingFailureCount The number of times where there was a time out getting an exclusive lock on the pool
CreatedCount The number of connections created
DestroyedCount The number of connections destroyed
IdleCount The number of connections currently idle
InUseCount The number of connections currently in use
MaxCreationTime The maximum time it took to create a connection. The value is in milliseconds
MaxGetTime The maximum time it took to obtain a connection. The value is in milliseconds
MaxUsedCount The maximum number of connections used
MaxWaitCount The maximum number of requests waiting for a connection at the same time
MaxWaitTime The maximum time spent waiting for an exclusive lock on the pool
TimedOut The number of timed out connections
TotalBlockingTime The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds
TotalCreationTime The total time spent creating connections. The value is in milliseconds
TotalGetTime The total time spent obtaining connections. The value is in milliseconds
WaitCount The number of requests that had to wait for a connection


Datasources has the following JDBC statistics values


This section will provide an overview of general deployment settings that are shared between resource adapter activations, and datasource deployments.

The policy for creating and destroying physical connections for a pool can be controlled by specifying which policy that should be used.

The default policies are only to create one connection per request, and to destroy all connections timed out when the idle timeout is scheduled.