Chapter 20. Configuring jeus-connector-dd.xml
Prev   Next

Chapter 20. Configuring jeus-connector-dd.xml

Table of Contents

20.1. Introduction
20.2. XML Schema/XML Tree
20.3. Element Reference
20.4. Example File

This chapter explains the contents of jeus-connector-dd.xml, an resource adapter module deployment descriptor.

20.1. Introduction

XML references are configured in the following format.

  1. XML Schema/XML Tree: Summarizes all the tags of XML configuration file. Each node is defined in the following format.

    1. Tag reference enables quick search for tags. Each tag is attached with index numbers ( ex: (11) ). Tags are explained with this number in tag reference.

    2. The XML tag name defined in the XML schema is expressed in the format of <tag name>.

    3. Tags are set with cardinality defined in XML schema.

      “?” is for 0 or 1 element, “+” is for 1 or more elements, “*” is for 0 or more elements, (no symbol) is for exactly one element

    4. Several tags have "P" character, meaning that they are the tags related to performance. These tags are used to tune the setting.

  2. Element Reference: Explains XML tags in the tree.

    1. Dynamic: Allowed to change the configuration dynamically.

    2. Non-Dynamic: Not allowed to change the configuration dynamically. This is expressed only for the special case to comment out.

    3. Description: A short description for tags.

    4. Value Description: The value and type.

    5. Value Type: Data type of the value. (ex: String)

    6. Value Type Description: Description for the data type of the value.

    7. Default Value: The value to be used by default when the XML is not used.

    8. Defined Value: The default value.

    9. Example: The XML tag example.

    10. Performance Recommendation: The value recommended to improve performance.

    11. Child Elements:The tags contained in its own tag element.

20.2. XML Schema/XML Tree

20.3. Element Reference

(1) <jeus-connector-dd>
Description Root element of a resource adaptor module. This element exists in each jeus-connector-dd.xml file.
Value Type jeus-connector-ddType
Child Elements

(3) module-name

(4) use-workmanager

(5) worker-pool

(16) connection-pool

(65) java-security-permission

(2) < jeus-connector-dd > <module-name>
Description @Deprecated. Name of the resource adapter module. This element is no longer supported for JEUS 6 Fix#7 or later.
Value Type token

(3) < jeus-connector-dd > <use-workmanager>
Description @Deprecated. Indicates whether to use Work Manager. If this element is set to true, Work Manager will be initialized just before the resource adapter starts.
Value Type boolean
Default Value false

(4) < jeus-connector-dd > <worker-pool>
Description Use this to configure Work Manager.
Value Type deprecated-worker-poolType
Child Elements

(6) min

(7) max

(8) step

(9) keep-alive-time

(10) pooled-timeout

(11) queue-size

(12) pre-allocation

(13) submit-timeout

(14) release-timeout

(15) shutdown-timeout

(5) < jeus-connector-dd >< worker-pool > <min>
Description Minimum number of threads to be managed by the Work Manager.
Value Type nonNegativeIntType
Default Value 0

(6) < jeus-connector-dd >< worker-pool > <max>
Description Maximum number of threads managed by the Work Manager.
Value Type nonNegativeIntType
Default Value 5

(7) < jeus-connector-dd >< worker-pool > <step>
Description @Deprecated. Always set to 1.
Value Type nonNegativeIntType
Default Value 1

(8) < jeus-connector-dd >< worker-pool > <keep-alive-time>
Description Keep-alive time for inactive threads. If the thread pool contains more than the minimum number of threads, inactive threads will be automatically removed from the thread pool after the specified period of time. The unit is milliseconds. The default value is 1 minute. If this option is set to 0, threads will not be removed.
Value Type nonNegativeLongType
Default Value 60000

(9) < jeus-connector-dd >< worker-pool > <pooled-timeout>
Description @Deprecated. Using Keep Alive Time is recommended.
Value Type nonNegativeLongType
Default Value 60000

(10) < jeus-connector-dd >< worker-pool > <queue-size>
Description Size of the Work Manager queue.
Value Type nonNegativeIntType
Default Value 4096

(11) < jeus-connector-dd >< worker-pool > <pre-allocation>
Description Number of initial threads to allocate when Work Manager is initialized.
Value Type boolean
Default Value true

(12) < jeus-connector-dd >< worker-pool > <submit-timeout>
Description @Deprecated
Value Type nonNegativeLongType
Default Value 0

(13) < jeus-connector-dd >< worker-pool > <release-timeout>
Description @Deprecated
Value Type nonNegativeLongType
Default Value 0

(14) < jeus-connector-dd >< worker-pool > <shutdown-timeout>
Description Shutdown timeout in milliseconds for Work Manager. This option allows graceful shutdown for Work Manaer by shutting it down after the specified period of time. When this element is set to -1 or 0, Work Manager will not wait before shutting down.
Value Type long
Default Value -1

(15) < jeus-connector-dd > <connection-pool>
Description Use this to configure an outbound connection pool.
Value Type connection-poolType
Child Elements

(17) connectionfactory-interface

(18) export-name

(19) log-file

(23) transaction-support

(24) user

(25) password

(26) use-wrapper

(27) dissociation-timeout

(28) invalidation-timeout

(29) validation-timeout

(30) skip-connection-matching

(31) use-lazy-transaction-enlistment

(32) pool-management

(61) property

(16) < jeus-connector-dd >< connection-pool > <connectionfactory-interface>
Description Value for <connectionfactory-interface> in <connection-definition> that is registered in ra.xml. It is possible to set more than one <connection-definition> in a single resource adapter, and this entails a commensurate number of connection pools. Therefore, when there are more than one <connection-definition>in ra.xml, the value for <connectionfactory-interface> must be configured.
Value Type token

(17) < jeus-connector-dd >< connection-pool > <export-name>
Description JNDI name of the connection pool. This must be unique in the node for the resource adapter module.
Value Type token

(18) < jeus-connector-dd >< connection-pool > <log-file>
Description @Deprecated. Log file that managed connection factory in the resource adapter will use.
Value Type log-fileType
Child Elements

(20) file-name

(21) buffer-size

(22) valid-day

(19) < jeus-connector-dd >< connection-pool >< log-file > <file-name>
Description Name of the log file to be used by the connection pool.
Value Type token

(20) < jeus-connector-dd >< connection-pool >< log-file > <buffer-size>
Description Size of the buffer to use when the the status of a connection pool is recorded.
Value Type nonNegativeIntType
Value Description Bytes.
Default Value 512

(21) < jeus-connector-dd >< connection-pool >< log-file > <valid-day>
Description Number of days after which a log files is rotated. After the specified number of days, the log file is archived and another file is used instead. If the number is greater than 1, the log file name will contain at the end the date when the file was opened.
Value Type off-intType
Value Description day

(22) < jeus-connector-dd >< connection-pool > <transaction-support>
Description Transaction type supported by the connection pool. The value for this element override the one configured in ra.xml. XATransactionOnly is no longer used and will be treated as a XATransaction.
Value Type transaction-supportType
Defined Value

NoTransaction

LocalTransaction

XATransaction

XATransactionOnly

(23) < jeus-connector-dd >< connection-pool > <user>
Description Name of the user used for server authentication.
Value Type token

(24) < jeus-connector-dd >< connection-pool > <password>
Description Password used for server authentication. To save the password in an encrypted form, type the password in the format of {algorithm}ciphertext.
Value Type token

(25) < jeus-connector-dd >< connection-pool > <use-wrapper>
Description @Deprecated.
Value Type boolean
Default Value true

(26) < jeus-connector-dd >< connection-pool > <dissociation-timeout>
Description @Deprecated. Dissociation timeout. This option is ignored if it is not supported by the resource adapter.
Value Type nonNegativeLongType
Default Value 0

(27) < jeus-connector-dd >< connection-pool > <invalidation-timeout>
Description @Deprecated. Invalidation timeout. If a connection is not returned after the specified time, it will be forcibly removed.
Value Type nonNegativeLongType
Default Value 0

(28) < jeus-connector-dd >< connection-pool > <validation-timeout>
Description @Deprecated. Connection verification timeout. If ValidatingManagedConnectionFactory interface has been implemented, invalid connections that have timed out will be removed from the connection pool.
Value Type nonNegativeLongType
Default Value 0

(29) < jeus-connector-dd >< connection-pool > <skip-connection-matching>
Description @Deprecated. Indicates whether the connection matching process will be skipped.
Value Type boolean
Default Value false

(30) < jeus-connector-dd >< connection-pool > <use-lazy-transaction-enlistment>
Description Indicates whether to enable the lazy transaction enlist option. Lazy transaction enlist is a transaction optimization function provided by the JCA specificiations. Note that enabling this option may produce unexpected transaction results.
Value Type boolean
Default Value false

(31) < jeus-connector-dd >< connection-pool > <pool-management>
Description Use this to configure a connection pool.
Value Type pool-managementType
Child Elements

(33) min

(34) max

(35) step

(36) pooled-timeout

(37) period

(38) wait-connection

(43) use-match-connection

(44) allow-disposable-connection-when-match-failed

(45) connection-validation

(51) action-on-connection-leak

(52) connection-trace

(56) max-use-count

(57) pool-destroy-timeout

(58) disposable-connection

(32) < jeus-connector-dd >< connection-pool >< pool-management > <min>
Description Minimum number of connections managed by a connection pool.
Value Type nonNegativeIntType
Default Value 2

(33) < jeus-connector-dd >< connection-pool >< pool-management > <max>
Description Maximum number of connections managed by a connection pool.
Value Type nonNegativeIntType
Default Value 10

(34) < jeus-connector-dd >< connection-pool >< pool-management > <step>
Description Number of connections to add as a unit when you want add more connections.
Value Type nonNegativeIntType
Default Value 1

(35) < jeus-connector-dd >< connection-pool >< pool-management > <pooled-timeout>
Description @Deprecated. Use <period> instead.
Value Type nonNegativeLongType
Default Value 600000

(36) < jeus-connector-dd >< connection-pool >< pool-management > <period>
Description Period of time after which the number of connections in a connection pool are adjusted. If the number of connections exceed the minimum number, extra connections will be deleted. If the number of connections is less than the minimum number, connections will be added up to the minimum number. If connection pool management is handled by applications, this option will not be used.
Value Type nonNegativeLongType
Value Description Milliseconds. 0 indicates that connections will not be removed.
Default Value 600000

(37) < jeus-connector-dd >< connection-pool >< pool-management > <wait-connection>
Description Indicates whether threads will wait to receive connections when there are no idle connections in the connection pool. If this option is not configured, and if the connection pool has reached the maximum number of connections, a disposable connection will be created and sent to an application.
Value Type wait-connectionType
Child Elements

(39) wait-connection

(40) max-waiter-count

(41) max-wait-trial

(42) wait-timeout

(38) < jeus-connector-dd >< connection-pool >< pool-management >< wait-connection > <wait-connection>
Description Indicates whether to wait to receive a connection.
Value Type boolean
Default Value false

(39) < jeus-connector-dd >< connection-pool >< pool-management >< wait-connection > <max-waiter-count>
Description @Deprecated. Maximum number of clients allowed to acquire a connection. If more clients than allowed request a connection, the request will be rejected. This setting is no longer supported for JEUS 6 Fix#7 and later.
Value Type nonNegativeIntType
Default Value 5

(40) < jeus-connector-dd >< connection-pool >< pool-management >< wait-connection > <max-wait-trial>
Description @Deprecated. Maximum failure count allowed for connection matching. If connection matching fails for the specified number of times, the connection is regarded as having failed. This setting is no longer supported for JEUS 6 Fix#7 and later.
Value Type nonNegativeIntType
Default Value 5

(41) < jeus-connector-dd >< connection-pool >< pool-management >< wait-connection > <wait-timeout>
Description Maximum connection wait timeout.
Value Type nonNegativeLongType
Default Value 10000

(42) < jeus-connector-dd >< connection-pool >< pool-management > <use-match-connection>
Description Indicates whether to enable connection matching. For detailed information, refer to the JCA standard.
Value Type boolean
Default Value false

(43) < jeus-connector-dd >< connection-pool >< pool-management > <allow-disposable-connection-when-match-failed>
Description Indicates whether to use a disposable connection when a connection match fails. This option is enabled only when connection matching is enabled.
Value Type boolean
Default Value false

(44) < jeus-connector-dd >< connection-pool >< pool-management > <connection-validation>
Description Indicates whether to enable connection validation. This option can be enabled when the resource adapter's managed connection factory implements jakarta.resource.spi.ValidatingManagedConnectionFactory.
Value Type jcaConnectionValidationType
Child Elements

(46) enabled

(47) period

(48) non-validation-interval

(49) validation-retrial-count

(50) destroy-policy-on-validation

(45) < jeus-connector-dd >< connection-pool >< pool-management >< connection-validation > <enabled>
Description Option to use Connection Validation. Available only when a resource adapter implements jakarta.resource.spi.ValidatingManagedConnectionFactory.
Value Type boolean
Default Value false

(46) < jeus-connector-dd >< connection-pool >< pool-management >< connection-validation > <period>
Description Interval at which Connection Validation is executed.
Value Type nonNegativeLongType
Default Value 0

(47) < jeus-connector-dd >< connection-pool >< pool-management >< connection-validation > <non-validation-interval>
Description Minimum interval at which Connection Validation is executed. The unit is milliseconds. Set this when overhead occurs due to frequent Connection Validation. For example, if set to 5000 ms, Connection Validation is executed after at least 5 seconds from the last execution.
Value Type nonNegativeLongType
Default Value 0

(48) < jeus-connector-dd >< connection-pool >< pool-management >< connection-validation > <validation-retrial-count>
Description Connection Validation execution count. In addition to the set count, Connection Validation can be executed once more when Destroy Policy On Validation is set to FAILED_CONNECTION_ONLY. If Destroy Policy On Validation is set to ALL_CONNECTIONS, it can be executed twice more if there is a connection issue at the first execution.
Value Type nonNegativeIntType
Default Value 0

(49) < jeus-connector-dd >< connection-pool >< pool-management >< connection-validation > <destroy-policy-on-validation>
Description Indicates how to handle connections in a connection pool with an invalid connection. If set to FAILED_CONNECTION_ONLY, only invalid connections are removed from the pool. If set to ALL_CONNECTIONS, invalid connections are removed from the pool and the other connections in the pool are checked whether they are valid. Invalid connections are removed.
Value Type destroy-policy-on-check-queryType
Default Value FailedConnectionOnly
Defined Value

FailedConnectionOnly

AllConnections

(50) < jeus-connector-dd >< connection-pool >< pool-management > <action-on-connection-leak>
Description Indicates actions for the connections that available to the component. The components are usually stateless components, including servlets/JSPs, stateless session beans, and MDBs.
Value Type action-on-resource-leakType
Defined Value

NoAction

Warning

AutoClose

(51) < jeus-connector-dd >< connection-pool >< pool-management > <connection-trace>
Description Monitors connections. This option displays stack traces on each getConnection call so that you can see which application is using a connection.
Value Type jca-connection-traceType
Child Elements

(53) enabled

(54) get-connection-trace

(55) local-transaction-trace

(52) < jeus-connector-dd >< connection-pool >< pool-management >< connection-trace > <enabled>
Description Option to use connection monitoring.
Value Type boolean
Default Value false

(53) < jeus-connector-dd >< connection-pool >< pool-management >< connection-trace > <get-connection-trace>
Description Saves StackTrace at the time when an application requests a connection (getConnection). When a connection leak occurs, StackTrace shows which application was using the connection. This can be checked with server log or an administration tool, such as WebAdmin.
Value Type boolean
Default Value true

(54) < jeus-connector-dd >< connection-pool >< pool-management >< connection-trace > <local-transaction-trace>
Description Option to trace information about applications' jobs for resource adapters and local transactions. If used along with Get Connection Trace, it is helpful to trace an application that does not commit or rollback a local transaction. If this option is set and jeus.connector.pool.transaction logger's level is set to FINE, the information can be checked with server log.
Value Type boolean
Default Value false

(55) < jeus-connector-dd >< connection-pool >< pool-management > <max-use-count>
Description Maximum use count of a physical connection. After a connection has been used the specified number of times, it will be replaced with a new connection.
Value Type nonNegativeIntType
Default Value 0

(56) < jeus-connector-dd >< connection-pool >< pool-management > <pool-destroy-timeout>
Description Destroy timeout value for a connection pool. When a resource adapter is undeployed, the connection pool is destroyed. Destroying a connection being used to communicate with resources across a network might cause a hang problem. If the connection pool is not destroyed after the timeout, the resource adapter will be undeployed regardless of any connection issues.
Value Type nonNegativeLongType
Default Value 10000

(57) < jeus-connector-dd >< connection-pool >< pool-management > <disposable-connection>
Description @Deprecated. No longer supported by JEUS 6 Fix#7 and later. This setting indcates whether to create disposable connections when wait connection properties are not used.
Value Type disposable-connectionType
Child Elements

(59) allow-disposable-connection

(60) max-disposable-count

(58) < jeus-connector-dd >< connection-pool >< pool-management >< disposable-connection > <allow-disposable-connection>
Description @Deprecated. Indicates whether to use a temporary connection if no connection has been obtained.
Value Type boolean
Default Value true

(59) < jeus-connector-dd >< connection-pool >< pool-management >< disposable-connection > <max-disposable-count>
Description @Deprecated. Maximum number of temporary connections. Temporary connections are automatically removed after they are used.
Value Type nonNegativeIntType
Default Value 3

(60) < jeus-connector-dd >< connection-pool > <property>
Description Managed connection factory properties. The properties override those configured in ra.xml.
Value Type typePropertyType
Child Elements

(62) name

(63) value

(64) type

(61) < jeus-connector-dd >< connection-pool >< property > <name>
Description Property name.
Value Type token

(62) < jeus-connector-dd >< connection-pool >< property > <value>
Description Property value. If the value type is java.util.Properties, it must be specified in the format of 'key=value
Value Type token

(63) < jeus-connector-dd >< connection-pool >< property > <type>
Description Type of a property.
Value Type token
Value Description Java primitive type. This must be specified before the property value can be specified.

(64) < jeus-connector-dd > <java-security-permission>
Description J2SE permission to grant to an application when J2SE Security is enabled.
Value Type securityPermissionType
Child Elements

(66) security-permission-spec

(67) description

(65) < jeus-connector-dd >< java-security-permission > <security-permission-spec>
Description Security permission specifications in the format for the Java security policy.
Value Type token

(66) < jeus-connector-dd >< java-security-permission > <description>
Description Description of the security permission configuration.
Value Type token

20.4. Example File

[Example 20.1] Example File

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-connector-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <module-name>whitebox-xa</module-name>

    <use-workmanager>true</use-workmanager>

    <!--
        Work Manager Configuration
    -->
    <worker-pool>
        <min>3</min>
        <max>10</max>
        <step>1</step>
        <pre-allocation>true</pre-allocation>
        <submit-timeout>5000</submit-timeout>
        <release-timeout>60000</release-timeout>
        <!-- Do not wait for running tasks
             while work manager is shutting down. -->
        <shutdown-timeout>-1</shutdown-timeout>
        <pooled-timeout>600000</pooled-timeout>
    </worker-pool>

    <!--
        Connection Pool Configuration
    -->
    <connection-pool>
        <export-name>datasource1</export-name>
        <log-file>
            <file-name>c:\logs\whitebox-xa.log</file-name>
            <buffer-size>512</buffer-size>
            <!-- To roll over log file every day. -->
            <valid-day>1</valid-day>
        </log-file>
        <!-- Defined values are NoTransaction, LocalTransaction,
             XATransaction and XATransactionOnly. -->
        <transaction-support>XATransaction</transaction-support>
        <user>scott</user>
        <password>tiger</password>
        <use-wrapper>true</use-wrapper>
        <!-- Works only if the resource adapter supported dissociation. -->
        <dissociation-timeout>60000</dissociation-timeout>
        <invalidation-timeout>300000</invalidation-timeout>
        <!-- Works only if the resource adapter
             implemented ValidatingManagedConnectionFactory -->
        <validation-timeout>600000</validation-timeout>
        <skip-connection-matching>false</skip-connection-matching>
        <pool-management>
            <min>0</min>
            <max>20</max>
            <pooled-timeout>600000</pooled-timeout>
            <wait-connection>
                <wait-connection>true</wait-connection>
                <max-waiter-count>5</max-waiter-count>
                <max-wait-trial>5</max-wait-trial>
                <wait-timeout>10000</wait-timeout>
            </wait-connection>
            <disposable-connection>
                <allow-disposable-connection>true</allow-disposable-connection>
                <max-disposable-count>3</max-disposable-count>
            </disposable-connection>
        </pool-management>
        <property>
            <name>Vendor</name>
            java.lang.String
            <value>TmaxSoft</value>
        </property>
    </connection-pool>
</jeus-connector-dd>

Prev   Next
Chapter 19. Configuring jeus-ejb-dd.xml Home Chapter 21. Configuring jeus-client-dd.xml