arjuna logoarjuna strap line


print this page
email this page

This trail provides information on the way to configure environmental variables needed to define the behaviour of transactional applications managed with JBossTS. Basically, the behaviour of the JBossTS 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 JBossTS.

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 JBossTS 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 JBossTS 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 JBossTS 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. JBossTS 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. JBossTS 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 JBossTS are defined below:

  • Debugging level – JBossTS 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 – JBossTS 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 – JBossTS 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