www.arjuna.com news company products standards research library forums contact
Trail map 1. Installation Content 2. The Sample Application 3. Deploying and Testing the Sample Application 4. Making the Sample Application Persistent 5. Recovery From Failure 6. Where Next? Navigation Home Additional Trails Distributed Transaction Processing The X/Open DTP Model The OMG OTS Model Transactions in J2EE Configuring ATS Configuring the Recovery Manager ORB Portability Transactional Object For Java
| print this page
| email this page
> Configuring the Arjuna Transaction Service This trail provides information on the way to configure environmental variables needed to define the behaviour of transactional applications managed with ArjunaTS. Basically, the behaviour of the ArjunaTS product is configurable through property attributes. Although these property attributes may be specified as command line arguments, it is more convenient to organise and initialise them through properties files. #### Properties File The properties file named arjunajts-properties.xml and located under the <ats_installation_directory>/etc directory is organised as a collection of property names.
>     <property>
>       name="a_name"
>       value="a_value"
>     </property>
Some properties must be specified by the developer while others do not need to be defined and can be used with their default values. Basically the properties file that does not provide default values to all its properties is the arjuna-properties.xml. Indeed, the most important properties that must be provided are the licences needed to execute ArjunaTS. The following table describes some properties in the arjuna-properties.xml, where: Name : indicates the name of the property Description: explain the aim of the property Possible Value: indicates possible value the property can have Default Value: shows the default value, if any, assigned to the property Note : In the first table ATL means Arjuna Technologies Ltd.
Name | Description | Possible Value | Default Value
com.arjuna.ats.arjuna. objectstore.localOSRoot | By default, all object states will be stored within the "defaultStore" subdirectory of the object store root. However, this subdirectory can be changed by setting the localOSRoot property variable accordingly | Directory name | defaultStore
com.arjuna.ats.arjuna. objectstore.objectStoreDir | Specify the location of the ObjectStore | Directory name | PutObjectStoreDirHere
com.arjuna.ats.arjuna.common.varDir | ArjunaTS needs to be able to write temporary files to a well known location during execution. By default this location is var. However, by setting the varDir property variable this can be overridden. | Directory name | var/tmp
#### ObjectStore management The ArjunaTS layer requires an object store for transaction management logs. Within the transaction service installation, object store is updated regularly whenever transactions are created, or when Transactional Objects for Java is used. In a failure free environment, the only object states which should reside within the object store are those representing objects created with the Transactional Objects for Java API. However, if failures occur, transaction logs may remain in the object store until crash recovery facilities have resolved the transactions they represent. As such it is very important that the contents of the object store are not deleted without due care and attention, as this will make it impossible to resolve in doubt transactions. In addition, if multiple users share the same object store it is important that they realise this and do not simply delete the contents of the object store assuming it is an exclusive resource. The location of the ObjectStore is specified in via the properrty com.arjuna.ats.arjuna.objectstore.objectStoreDir that can be passed with the java flag "-D". For convenience this property is defined in the properties file arjuna-properties.xml, and its value is set during the ArjunaTS installation. At any time, the location of the ObjectStore may be changed. #### Configuring Output Sometimes it is desirable, mainly in case of debugging, to have some form of output during execution to trace internal actions performed. ArjunaTS uses the logging tracing mechanism provided by the Arjuna Common Logging Framework (CLF) version 2.4, which provides a high level interface that hides differences that exist between logging APIs such Jakarta log4j, JDK 1.4 logging API or dotnet logging API. With the CLF applications make logging calls on commonLogger objects. These commonLogger objects pass log messages to Handler for publication. Both commonLoggers and Handlers may use logging Levels to decide if they are interested in a particular log message. Each log message has an associated log Level, that gives the importance and urgency of a log message. The set of possible Log Levels are DEBUG, INFO, WARN, ERROR and FATAL. Defined Levels are ordered according to their integer values as follows: DEBUG < INFO < WARN < ERROR < FATAL. The CLF provides an extension to filter logging messages according to finer granularity an application may define. That is, when a log message is provided to the commonLogger with the DEBUG level, additional conditions can be specified to determine if the log message is enabled or not. Note: These conditions are applied if and only the DEBUG level is enabled and the log request performed by the application specifies debugging granularity. When enabled, Debugging is filtered conditionally on three variables: Debugging level: this is where the log request with the DEBUG Level is generated from, e.g., constructors or basic methods. Visibility level: the visibility of the constructor, method, etc. that generates the debugging. Facility code: for instance the package or sub-module within which debugging is generated, e.g., the object store. According to these variables the Common Logging Framework defines three interfaces. A particular product may implement its own classes according to its own finer granularity. ArjunaTS uses the default Debugging level and the default Visibility level provided by CLF, but it defines its own Facility Code. ArjunaJTS uses the default level assigned to its commonLoggers objects (DEBUG). However, it uses the finer debugging features to disable or enable debug messages. Finer values used by the ArjunaTS are defined below: Debugging level – ArjunaTS uses the default values defined in the class com.arjuna.common.util.logging.CommonDebugLevel
Debug Level | Value | Description
NO_DEBUGGING | 0x0000 | A commonLogger object assigned with this values discard all debug requests
CONSTRUCTORS | 0x0001 | Diagnostics from constructors
DESTRUCTORS | 0x0002 | Diagnostics from finalizers.
CONSTRUCT_AND_DESTRUCT | CONSTRUCTORS | DESTRUCTORS | Diagnostics from constructors and finalizers
FUNCTIONS | 0x010 | Diagnostics from functions
OPERATORS | 0x020 | Diagnostics from operators, such as equals
FUNCS_AND_OPS | FUNCTIONS | OPERATORS | Diagnostics from functions and operations.
ALL_NON_TRIVIAL | CONSTRUCT_AND_DESTRUCT | FUNCTIONS | OPERATORS | Diagnostics from all non-trivial operations
TRIVIAL_FUNCS | 0x0100 | Diagnostics from trivial functions.
TRIVIAL_OPERATORS: | 0x0200 | Diagnostics from trivial operations, and operators.
ALL_TRIVIAL | TRIVIAL_FUNCS | TRIVIAL_OPERATORS | Diagnostics from all trivial operations
FULL_DEBUGGING | 0xffff | Full diagnostics.
Visibility level – ArjunaTS uses the default values defined in the class com.arjuna.common.util.logging.CommonVisibilityLevel
Debug Level | Value | Description
VIS_NONE | 0x0000 | No Diagnostic
VIS_PRIVATE | 0x0001 | only from private methods.
VIS_PROTECTED | 0x0002 | only from protected methods.
VIS_PUBLIC | 0x0004 | only from public methods.
VIS_PACKAGE | 0x0008 | only from package methods.
VIS_ALL | 0xffff | Full Diagnostic
Facility Code – ArjunaTS uses the following values
Facility Code Level | Value | Description
FAC_ATOMIC_ACTION | 0x00000001 | atomic action core module
FAC_BUFFER_MAN | 0x00000004 | state management (buffer) classes
FAC_ABSTRACT_REC | 0x00000008 | abstract records
FAC_OBJECT_STORE | 0x00000010 | object store implementations
FAC_STATE_MAN | 0x00000020 | state management and StateManager)
FAC_SHMEM | 0x00000040 | shared memory implementation classes
FAC_GENERAL | 0x00000080 | general classes
FAC_CRASH_RECOVERY | 0x00000800 | detailed trace of crash recovery module and classes
FAC_THREADING | 0x00002000 | threading classes
FAC_JDBC | 0x00008000 | JDBC 1.0 and 2.0 support
FAC_RECOVERY_NORMAL | 0x00040000 | normal output for crash recovery manager
To ensure appropriate output, it is necessary to set some of the finer debug properties explicitly as follows:
     <properties>
       <!-- CLF 2.4 properties -->
       <property
         name="com.arjuna.common.util.logging.DebugLevel"
         value="0x00000000"/>
       <property
         name="com.arjuna.common.util.logging.FacilityLevel"
         value="0xffffffff"/>
       <property
         name="com.arjuna.common.util.logging.VisibilityLevel"
         value="0xffffffff"/>
       <property
         name="com.arjuna.common.util.logger"
         value="log4j"/>
     </properties>
By default, debugging messages are not enabled since the DebugLevel is set to NO_DEBUGGING (0x00000000). You can enable debugging by providing one of the appropriate value listed above - for instance with you wish to see all internal actions performed by the RecoveryManager to recover transactions from a failure set the DebugLevel to FULL_DEBUGGING (0xffffffff) and the FacilityCode Level FAC_CRASH_RECOVERY. Note: To enable finger debug messages, the logging level should be set to the DEBUG level as described below. From the program point of view a same API is used whatever the underlying logging mechanism, but from a configuration point of view is that the user is totally responsible for the configuration of the underlying logging system. Hence, the properties of the underlying log system are configured in a manner specific to that log system, e.g., a log4j.properties file in the case that log4j logging is used. To set the logging level to the DEBUG value, the log4j.properties file can be edited to set that value. The property com.arjuna.common.util.logger allows to select the underlying logging system. Possible value are listed in the following table.
Property Value | Description
log4j | Log4j logging (log4j classes must be available in the classpath); configuration through the log4j.properties file, which is picked up from the CLASSPATH or given through a System property: log4j.configuration
jdk14 | JDK 1.4 logging API (only supported on JVMs of version 1.4 or higher). Configuration is done through a file logging.properties in the jre/lib directory.
simple | Selects the simple JDK 1.1 compatible console-based logger provided by Jakarta Commons Logging
csf | Selects CSF-based logging (CSF embeddor must be available)
jakarta | Uses the default log system selection algorithm of the Jakarta Commons Logging framework
dotnet | Selects a .net logging implementation Since a dotnet logger is not currently implemented, this is currently identical to simple. Simple is a purely JDK1.1 console-based log implementation.
avalon | Uses the Avalon Logkit implementation
noop | Disables all logging
Copyright 2002-2005 Arjuna Technologies All Rights Reserved. info@arjuna.com +44 191 243 0676