2.6.2. Specific JDBC Resource Adapter
Prev  2.6. Configuring JDBC Resource Adapters  Next

2.6.2. Specific JDBC Resource Adapter

The remainder of this section, which describes how to define and configure JDBC RAs, is specific to JOnAS. However, the way to use these JDBC RAs in the Application Component methods is standard, i.e., via the resource manager connection factory references (refer to the example in the section Writing Database Access Operations.

An RAR file must be deployed as explained in Section 2.4.16, “resource service configuration”.

Usually a resource Adapter contains in its rar file all the classes needed to access to the external resource. In the case of a specific JDBC RA it contains only a JOnAS specific deployment descriptor jonas-ra.xml that tell what sort of generic resource adapter to use and information related to the specific database used. The jar file of the actual JDBC driver mut be copied in the right place to be seen by the JOnAS classloader : $JONAS_BASE/lib/ext.

Changing the configuration of the RA requires extracting and editing the deployment descriptor and updating the archive file. There are several possible ways to do this:

2.6.2.1. Defining the JOnAS Connector Deployment Descriptor: jonas-ra.xml

The jonas-ra.xml contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values:

  • Deployment Tags:

    property name description possible values
    jndiname name the RAR will be registered as. This property is required. This value will be used in the resource-ref section of an Java EE composant.

    • Anyname (for example jdbc_1)
    rarlink jndiname of a base RAR file. Useful for deploying multiple connection factories without having to deploy the complete RAR file again. When this is used, the only entry in RAR is a META-INF/jonas-ra.xml

    • JONASJDBC_DM

    • JONASJDBC_DS

    • JONASJDBC_CP

    • JONASJDBC_XA
    native-lib defines the path where native libraries can be found.

    • Any string for a path

  • Logging Tags:

    property name description possible values
    log-enabled determines if logging should be enabled for the RAR.

    • False (default value)

    • True
    log-topic: defines the log topic that will be used to write log messages for this rar file.

    • Any topic name

    • Default value is org.objectweb.jonas.jca

  • Pooling Tags

    property name description possible values
    pool-init Initial size of the managed connection pool

    • 0 (default value)

    • n
    pool-min Minimum size of the managed connection pool.

    • 0 (default value)

    • n
    pool-max Maximum size of the managed connection pool.

    • n

    • -1 = unlimited (default value)
    pool-max-age-minutes Maximum number of minutes to keep the managed connection in the pool.

    • 0 = an unlimited amount of time.

    • n in minutes
    pstmt-max Maximum number of PreparedStatements per managed connection in the pool. Only needed with the JDBC RA of JOnAS or another database vendor's RAR. Value of 0 is unlimited and -1 disables the cache.

    • 0 = unlimited

    • n (default value = 10)

    • -1 = cache disabled
    pool-max-opentime Identifies the maximum number of minutes that a managed connection can be left busy.

    • 0 = an unlimited amount of time (default value).

    • n in minutes
    pool-max-waiters: identifies the maximum number of waiters for a managed connection. Default value is 0.

    • 0 (default value)

    • n
    pool-max-waittime identifies the maximum number of seconds that a waiter will wait for a managed connection. Default value is 0.

    • 0 (default value)

    • n in seconds
    pool-sampling-period: identifies the number of seconds that will occur between statistics samplings of the pool. Default is 30 seconds.

    • n in seconds (default value = 30s)

  • JDBC Connection Tags:

    [Note] Note

    Only valid for Connection implementation of java.sql.Connection.

    property name description possible values
    jdbc-check-level Level of checking that will be done for the jdbc connection.

    • 0 : no check (default value)

    • 1: check connection still open

    • 2 : send the test statement before reusing a connection from the pool

    • 3: (keep-alive feature) send the test statement on each connection every pool-sampling-period
    jdbc-test-statement Test SQL statement sent on the connection if the jdbc-check-level is greater than 1.

    • A SQL statement

  • Config Property Value Tags:

    Each entry must correspond to the config-property specified in the ra.xml of the RAR file. The default values specified in the ra.xml will be loaded first and any values set in the jonas-ra.xml will override the specified defaults. These tags differs dependiing on the generic JDBC RA used

    property name description possible values
    dsClass Name of the class implementing java.sql.Driver, javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, or javax.sql.XADataSource interfaces in the JDBC driver.

    • any classname representing a JDBC driver (example:org.postgresql.Driver)
    URL Database url of the form jdbc:<database_vendor_subprotocol>. This property may be used only for JDBC RA that implements the Driver (JDBC_DM)

    • Any url valid for a database provider (example:jdbc:postgresql://localhost:5432/mydb)
    user Database user name

    • any name
    password: Database password

    • any string
    loginTimeout Maximum time in seconds that the driver will wait while attempting to connect to a database.

    • no value = 0 (default value)

    • n in seconds
    isolationLevel Level of transaction isolation

    • none

    • serializable

    • read_committed

    • read_uncommitted

    • repeatable_read
    mapperName Name of the JORM mapper The possible values can be found in the List of available mappers in JORM documentation.
    databaseName Name of the database

    • any name
    description: Informal description

    • any String
    portNumber Port Number of the database server

    • a number
    serverName Name of the database server.

    • any name
    dbSpecificMethods allow flexibility to call setter methods on the dsClass as required by the database provider see below the particular syntax

  • dbSpecificMethods a specific property:

    The JOnAS JDBC Resource Adapter is built as a generic connector to any database provider. The limitation of this is that each database provider may have different requirements about the methods needed to configure the dataSource class. This dbSpecificMethods property was added to allow flexibility to call setter methods on the dsClass as required by the database provider. The specific information about what additional methods should be used is documented by the database provider. The format of the value specified is:

    [:<del_char>]<method>=<value>::<value_type>:<method>=<value>::<value_type>....with:

    : optional starting value that denotes using the next character as the delimiter instead of the default ':'
    <del_char> delimiter character to use
    <method> method to call followed by an = sign
    <value> the parameter value to pass to the method being called, followed by 2 delimiter characters.If a Properties object is being passed, then the format of this value must be (name=val, name=val, ...);
    <value_type>

    the parameter type used to construct the reflection call, followed by the delimiter character if additional methods are being called

    • Boolean or bool

    • Byte or byte

    • Character or char

    • Double or double

    • Float or float

    • Integer or int

    • Long or long

    • Properties or java.util.Properties

    • Short or short

    • String

[Note] Note

If this JDBC resource is used as a persistence unit, the persistence configuration defined in the persistence.xml file must be coherent to this jonas-ra.xml description, such as the datasource name and the dialect.

2.6.2.2. Understanding pooling tags:

At JDBC RA deployment time, if pool-init is not null pool-init JDBC connection are created.

When a user requests a jdbc connection, the JDBC RA first checks to see if a connection is already open for its transaction. If not, it tries to get a free connection from the free list. If there are no more connections available, it creates a new jdbc connection (if pool-max is not reached).

If it cannot create new connections, the user must wait (if pool-max-waiters is not reached) until a connection is released. After a limited time (pool-max-waittime), the getConnection returns an exception.

When the user calls close() on its connection, it is put back in the free list.

Many statistics are computed (every pool-sampling-period seconds) and can be viewed by JonasAdmin. This is useful for tuning these parameters and for seeing the server load at any time

When a connection has been open for a time too long (pool-max-age), the pool will try to release it from the freelist. However, the JDBC RA always tries to keep open at least the number of connections specified in pool-min.

When the user has forgotten to close a jdbc connection, the system can automatically close it, after pool-max-opentime minutes. Note that if the user tries to use this connection later, thinking it is still open, it will return an exception (socket closed).

When a connection is reused from the freelist, it is possible to verify that it is still valid. This is configured in jdbc-check-level . For levels >1 it tries a dummy statement on the connection before returning it to the caller. This statement is configured in jdbc-test-statement.

[Note] Note

this previous description is not only true for JDBC RAs but also for all types of resource adapters, except jdbc-check-level and jdbc-test-statement which are specifics for JDBC.

Prev  Up  Next
2.6. Configuring JDBC Resource Adapters  Home  2.6.3. Examples of Specific JDBC Resource Adapter