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 jbossts-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 jbossts-properties.xml.
The following table describes some properties in the jbossts-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
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 jbossts-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. JBossTS 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 |