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 property:

java -Dtyrex.config=tyrex.config $1 

The following properties are supported in the current version of Tyrex:

-	tyrex.log.verbose Specifies whether to run Tyrex in verbose mode. When this property is set to true, Tyrex will emit additional information to the log to assist in troubleshtooting and debugging. It is recommended to leave this property to the default value (false) in a deployment environment.
-	tyrex.log.console Specifies whether to enable console logging. When this property is set to true (the default), Tyrex will emit various information (in both verbose and non-verbose mode) to the console.
-	tyrex.clock.unsynchTicks Determines the number of clocks ticks to skip before incrementing the internal clock. The value of this property is an integer, the precision is milliseconds. The default value is 100 milliseconds.
-	tyrex.clock.synchEvery Determines the number of unsynchronized cycles before synchronizing the clock. The value of this property is an integer that, when multiplied by tyrex.clock.unsynchTicks, determines the clock synchronization interval (in milliseconds). The default value is 10 cycles.
-	tyrex.random.secure Determines whether to use secure (cryptographic quality) or standard (pseudo) random number generator. Setting this property to true assures that random numbers are truely random, but results in a longer statup sequence. The default value is false.
-	tyrex.uuid.stateFile The name of the UUID state file, see UUID State File for more information. The default value is uuid.state.
-	tyrex.domain.files Specifies the name of the default domain configuration file(s). This property is a list of file names that must be accessible from the current directory. All domain configuration files specified in this property will be loaded automatically by Tyrex. If this property is missing, Tyrex loads up with no transaction domain.

The following example illustrates a Tyrex configuration file:

tyrex.log.verbose=false
tyrex.log.console=true

tyrex.clock.unsynchTicks=100
tyrex.clock.synchEvery=10
tyrex.random.secure=true
tyrex.uuid.stateFile=uuid.state
tyrex.domain.files=domain.xml 

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.

uuid.nodeIdentifier=08:00:46:08:64:C3
uuid.clockSequence=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:

domain		Top level element
name	required	The name of the domain
maximum	optional	Maximum number of open transactions allowed
timeout	optional	Default timeout for transactions, in seconds
journalFactory	optional	Implementation of transaction journal factory
resources	optional	Top level element for list of JDBC data sources and JCA connectors
dataSource	zero or more	Specification for a JDBC data source
connector	zero or more	Specification for a JCA connector

One dataSource element is used for each configured JDBC data source. The dataSource element takes the following strcture:

dataSource		Top level element for each JDBC data source specification
name	required	The name of the data source
jar	optional	The name of the data source JAR.
paths	optional	Paths to additional JARs and dependent files.
class	required	The data source implementation class name.
config	optional	Configuration for the JDBC data source
limits	optional	Resource limit for the JDBC connection pool

One connector element is used for each configured JCA connector. The connector element takes the following strcture:

connector		Top level element for each JCA connector specification
name	required	The name of the connector source
jar	required	The name of the connector RAR
paths	optional	Paths to additional JARs and dependent files
config	optional	Configuration for the connection factory
limits	optional	Resource limit for the JCA connection pool

Connection pool limits are specified using the limits element that takes the following strcture: >

limits		Top level element for each connection pool limits specification
maximum	optional	Maximum number of connections allowed
minimum	optional	Minimum number of connections to keep in the pool
initial	optional	Initial size of pool
maxRetain	optional	Maximum duration to retain open connections, in seconds
timeout	optional	Maximum timeout waiting for a new connection, in seconds
trace	optional	True to enable tracing

The various elements of the domain configuration file are explained in more detail below.

domain

The top level element of each domain configuration file. A domain configuration file can specify exactly one transaction domain.

domain/name

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.

domain/maximum

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.

domain/timeout

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.

domain/journalFactory

Specifies the transaction journal factory to use. If this element is missing, journaling is not enabled for this transaction domain.

domain/resources

Lists zero or more JDBC data sources and JCA connectors that are available as resource managers in this transaction domain. Order is not important.

resources/dataSource

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.

resources/connector

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.

[dataSource|connector]/name

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.

[dataSource|connector]/jar

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.

[dataSource|connector]/paths

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.

dataSource/class

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).

[dataSource|connector]/config

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.

[dataSource|connector]/limits

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.

limits/maximum

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.

limits/minimum

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.

limits/initial

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.

limits/maxRetain

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.

limits/timeout

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.

limits/trace

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:

<domain>
  <name>default</name>
  <!-- Limit to 50 concurrent transactions -->
  <maximum>50</maximum>
  <!-- Default transaction timeout: 2 minutes -->
  <timeout>120</timeout>
  <resources>
    <!-- Specification for data source myDb -->
    <dataSource>
      <name>myDb</name>
      <jar>jconnect_5.2.jar</jar>
      <class>com.sybase.jdbc2.jdbc.SybXADataSource</class>
      <config>
        <!-- Configuration for SybXADataSource -->
        <user>arkin</user>
        <password>secret</password>
        <serverName>tyrex.sourceforge.net</serverName>
        <postNumber>4100</portNumber>
      </config>
      <limits>
        <!-- Start with 5 connections, never go below 5,
             and never go above 50 -->
        <maximum>50</maximum>
        <minimum>5</minimum>
        <initial>5</initial>
        <!-- Discard connections idle for 5 minutes -->
        <maxRetain>300</maxRetain>
        <!-- If maximum reached, block for 10 seconds -->
        <timeout>10</timeout>
      </limits>
    </dataSource>
  </resources>
</domain>