When Tyrex is instantiated, it reads configuration properties from the Tyrex configuration file. The Tyrex configuration file is called tyrex.config.
The configuration file is loaded in the following manner. First, a default configuration file is loaded from the Tyrex JAR. This file provides the minimum set of default values required by Tyrex, including such data as the version number.
If a configuration file called tyrex.config exists in the class path, it will be loaded next. This file can override any values specified in the default configuration file.
The name of the configuration file can be specified using the system property
tyrex.config. The following example illustrates how to set the system
The following properties are supported in the current version of Tyrex:
The following example illustrates a Tyrex configuration file:
The Tyrex UUID generator is used for producing Universally Unique IDentifiers. UUIDs are 128 bit values guaranteed to be unique across all servers and applications. They are used for transaction identifiers, and by applications that rely on this service to produce unique identifiers.
In order to guarantee uniqueness, the UUID generator utilizes three parameters: the system clock, clock sequence and node identifier. The system clock simulates a resolution of 100 nanoseconds, allowing nearly ten thousand UUIDs to be generated in a second.
The clock sequence protects against a retarding clock. The clock may be set backwards accidentaly. or as a result of server down time. Day light savings time has no effect on the clock, but clustered servers will seldom have a synchronized clock. The clock sequence is automatically incremented each time Tyrex is started, rolling over after 8192 restarts.
The node identifier guarantees uniqueness across servers. The node idenifier if a 47 bit value set from the IEEE 802 address of the network card. Each network card has a universally unique 47 bit identifier. Where multiple network cards are installed, any one card can be used.
When installing Tyrex for the first time, the network card address is obtained and placed in the UUID state file. To obtain the network address under Linux/UNIX, run ifconfig from the root account. To obtain the network card address under Windows 2000, open a DOS window and type ipconfig /all.
The clock sequence can be set to any arbitrary value between 0 and 8192, but must have no correlation with the network card address to be unique. If no value is placed, the initial value will be randomly generated.
The following example illustrates the contents of a UUID state file generated from
the network card address 08:00:46:08:64:C3 with a clock sequence of 100.
The UUID state file is typically located in the installation directory of Tyrex, under the name uuid.state. The location and name of the file can be controlled using the configuration property tyrex.uuid.stateFile.
If the UUID state file could not be located, Tyrex will use random values for both the node identifier and clock sequence. Different random values will be generated each time Tyrex is used to assure uniquness. In a deployment environment it is important to gurantee that both values are truely unique. If the network card address is unavailable, use cryptographic quality random number generator by setting the configuration property tyrex.random.secure to true.
Using the cryptographic quality random number generator will slow the initialization process. It is recommended to leave this property unset in a development environment.
A Transaction Domain provides centralized management for transactions. A transaction domain defines the policy for all transactions created from that domain, such as default timeout, maximum number of open transactions, IIOP support, and journaling. In addition, the domain maintains resource managers such as JDBC data sources and JCA connectors.
Transaction domains are created from domain configuraiton files. The domain configuration file defines the properties for the specific transaction domain, and configures all the JDBC data sources and JCA connectors available in that domain.
The transaction domain configuration file is an XML document with the following structure:
One dataSource element is used for each configured JDBC data
source. The dataSource element takes the following strcture:
One connector element is used for each configured JCA connector.
The connector element takes the following strcture:
Connection pool limits are specified using the limits element
that takes the following strcture:
The various elements of the domain configuration file are explained in more detail below.
The top level element of each domain configuration file. A domain configuration file can specify exactly one transaction domain.
Each transaction domain must have a unique name in the system. Tyrex will not allow two transaction domains with the same name to be configured. Domain names are used for logging messages, and should be kept short.
The maximum number of open transactions supported by this domain. Tyrex will make sure this limit is not exceeded by blocking any attempt to create more transactions than the maximum allowed limit. This limit only applies to concurrently open (not committed or rolledback) top-level transactions.
If this element is missing, the default value (zero) is assumed, meaning no limit is placed on the number of concurrently open transaction.
The default timeout for all transactions, specified in seconds. Timeouts are used to detect and cancel blocked transactions. A different value can be specified at runtime using one of the JTA or OTS interfaces.
If this element is missing, the default (120 seconds) is assumed. It is recommended to set this value to a reasonable range that allows all transactions to complete, but does not allow blocked transactions to lock resources indefinitely.
Specifies the transaction journal factory to use. If this element is missing, journaling is not enabled for this transaction domain.
Lists zero or more JDBC data sources and JCA connectors that are available as resource managers in this transaction domain. Order is not important.
The dataSource element configures a single JDBC 2.0 (or 3.0) data source as a resource manager in this transaction domain. It provides specification of the JDBC provider, default configuration, and connection pool limits.
The connector element configures a single JCA 1.0 connector as a resource manager in this transaction domain. It provides specification of the JCA provider, default configuration, and connection pool limits.
Specifies the name by which the data source or connector resource will be known. The resource name will be used to obtain an instance from the transaction domain and for debugging purposes. It should be short and must be unique within this transaction domain.
The resource name is different than the JNDI name by which the application will obtain a connection factory from the JNDI Environment Naming Context.
File name or URL of the JAR file containing the JDBC driver, or the RAR file containing the JCA connector. A relative file name is located in the current working directory. An absolute file name or HTTP/FTP URL can be used as well. Only a single JAR or RAR file can be specified, and must contain the JDBC driver or JCA connector.
List of files names or URLs to additional JARs, libraries and support files required by a JDBC driver of JCA connector. Colon or semi-colon separators can be used.
The class of the data source implementation for a JDBC driver. When using an XA-capable data source, this should be a class implementing javax.sql.XADataSource. When using a non-XA data source, this should be a class implementing javax.sql.PoolConnectionDataSource.
This element is only used for JDBC data sources. JCA connectors specify the connection factory class in a deployment file contained within the JCA RAR.
If either dataSource/jar or dataSource/paths elements are specified - special URL class loader is used to load the dataSource class from the specified jars. Otherwise default system classloader is used (i.e. JVM's classpath is expected to have the data source class).
Configures the JDBC data source or JCA connector. This element contains a list of properties that match to the Bean-like get/set methods of the JDBC DataSource or JCA ManagedConnectionFactory.
Defines the connection pool limits placed on a JDBC data source or JCA connector. If this element is missing or empty, the default limits apply.
Maximum number of open connections allowed. Most systems impose a limit on the number of connections that can be open at any one time. When this limit is reached, the application will block until a connection becomes available or a timeout occurs.
If this element is missing, the default (zero) is assumed, implying that no limit is placed on the number of open connections.
Minimum number of connections to keep in the pool. The pool will discard connections that have not been used for more than the specified maxRetain duration. Even so, the pool will keep the minimum number of connections specified to guarantee a reasonable respnse time when new connections are required.
If this element is missing, the default (zero) is assumed, and the connection pool is allowed to shrink to zero connections.
The initial number of connections to create. When the pool is first created it will open up the specified number of connections. Even if this value is zero, one connection will always be created for access to meta-data information.
If this element is missing, the default (zero) is assumed, and only one connection will be created, as required for meta-data access.
The maximum duration to retain unused connections, in seconds. When a connection is returned to the pool, it will be retained for that duration before being discarded. The application may obtain the connection from the pool before this time has elapsed.
A high retain timeout allows the application to response better to changing loads, but may result in resource starvation for other applications using the same resource manager. This value should also take into account any idle timeout imposed on connections.
If this element is missing, the default (zero) is assumed, causing connections to be kept in the pool forever.
The timeout waiting for a new connection, in seconds. If the maximum limit has been reached, Tyrex will block the application until a connection becomes available, or the timeout has been reached.
If this element is missing, the default (zero) is assumed, meaning that the application will not be blocked and an exception will be thrown immediately if the maximum limit has been reached.
Request tracing. If the value of this element is true, Tyrex will log all usage of the JDBC data source or JCA connector.
The following example illustrates a domain configuration file using Sybase jConnect 5.2: