<?xml version="1.0"?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2006, Red Hat Middleware LLC, and individual contributors
  as indicated by the @author tags.
  See the copyright.txt in the distribution for a full listing
  of individual contributors.
  This copyrighted material is made available to anyone wishing to use,
  modify, copy, or redistribute it subject to the terms and conditions
  of the GNU Lesser General Public License, v. 2.1.
  This program is distributed in the hope that it will be useful, but WITHOUT A
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License,
  v.2.1 along with this distribution; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  MA  02110-1301, USA.


  (C) 2005-2006,
  @author JBoss Inc.
-->
<page title="JBossTS Trail map: Configuring the JBoss Transaction Service" rootpath="../..">
	<header>
        Trail map: JBossTS Configuration
    </header>
	<content>
		<navigation>
			<links include="includes/www_arjuna_com_navigation.xml"/>
			<links include="includes/trailmap_navigation.xml"/>
			<links title="Navigation">
				<link ref="index.html">Home</link>
			</links>
			<links include="includes/trailmap_additional.xml"/>
		</navigation>
		<area title="Configuring the JBoss Transaction Service">
			<html>
				<p>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. </p>
<h4>Properties File</h4>
<p> The properties file named <font face="Courier New, Courier, mono">jbossts-properties.xml
   </font> and located under the <font face="Courier New, Courier, mono">&lt;ats_installation_directory&gt;/etc</font>
   directory is organised as a collection of property names. </p>
<blockquote>
<pre>
&lt;property>
  name="a_name"
  value="a_value"
&lt;/property>
</pre>
</blockquote>

<p>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.</p>
				<p>The following table describes some properties in the jbossts-properties.xml, where:</p>
				<ul>
					<li>
						<b>Name</b> : indicates the name of the property</li>
					<li>
						<b>Description</b>: explain the aim of the property</li>
					<li>
						<b>Possible Value</b>: indicates possible value the property can have</li>
					<li>
						<b>Default</b>
						<strong>Value</strong>: shows the default value, if any,
    assigned to the property</li>
				</ul>

				<table BORDER="" WIDTH="100%">
					<tr ALIGN="CENTER" VALIGN="CENTER" BGCOLOR="#8BD5FC">
						<td width="38%">
							<b>Name</b>
						</td>
						<td width="25%">
							<b>Description</b>
						</td>
						<td width="10%">
							<b>Possible Value</b>
						</td>
						<td width="27%">
							<b>Default Value</b>
						</td>
					</tr>

					<tr>
						<td>com.arjuna.ats.arjuna.<br/>objectstore.localOSRoot</td>
						<td>By default, all object states will be stored within the &quot;defaultStore&quot;
      subdirectory of the object store root. However, this subdirectory can be
      changed by setting the localOSRoot property variable accordingly</td>
						<td>Directory name</td>
						<td>defaultStore</td>
					</tr>
					<tr>
						<td>com.arjuna.ats.arjuna.<br/>objectstore.objectStoreDir</td>
						<td>Specify the location of the ObjectStore</td>
						<td>Directory name</td>
						<td>PutObjectStoreDirHere</td>
					</tr>
					<tr>
						<td>com.arjuna.ats.arjuna.common.varDir</td>
						<td>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.</td>
						<td>Directory name</td>
						<td>var/tmp</td>
					</tr>
				</table>
				<h4>ObjectStore management</h4>
The JBossTS layer requires an object store for transaction management <a class="linkscoloured" href="DTP.html#RecoveryLog">logs</a>. 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.
<p> The location of the ObjectStore is specified in via the properrty <font face="Courier New,Courier">com.arjuna.ats.arjuna.objectstore.objectStoreDir</font>
  that can be passed with the java flag &quot;-D&quot;. 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.</p>
				<h4>Configuring Output</h4>
				<p>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.</p>
				<p>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 &lt; INFO &lt; WARN &lt; ERROR &lt; FATAL. </p>
				<p> 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. <br/>
					<b>Note</b>: These conditions are applied if and only the DEBUG level is enabled
  and the log request performed by the application specifies debugging granularity.
  <br/>
  When enabled, Debugging is filtered conditionally on three variables: </p>
				<ul>
					<li> Debugging level: this is where the log request with the DEBUG Level is
    generated from, e.g., constructors or basic methods.</li>
					<li> Visibility level: the visibility of the constructor, method, etc. that
    generates the debugging.</li>
					<li> Facility code: for instance the package or sub-module within which debugging
    is generated, e.g., the object store.</li>
				</ul>
				<p>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:
</p>
				<ul>
					<li>Debugging level – JBossTS uses the default values defined in the class
    com.arjuna.common.util.logging.CommonDebugLevel </li>
				</ul>
				<table width="83%" border="1">
					<tr bgcolor="#8BD5FC">
						<td width="33%">
							<div align="center">
								<strong>Debug Level</strong>
							</div>
						</td>
						<td width="24%">
							<div align="center">
								<strong>Value</strong>
							</div>
						</td>
						<td width="43%">
							<div align="center">
								<strong>Description</strong>
							</div>
						</td>
					</tr>
					<tr>
						<td>NO_DEBUGGING</td>
						<td>
							<font face="Courier New, Courier, mono">0x0000</font>
						</td>
						<td>A commonLogger object assigned with this values discard all debug requests</td>
					</tr>
					<tr>
						<td>CONSTRUCTORS</td>
						<td>
							<font face="Courier New, Courier, mono"> 0x0001</font>
						</td>
						<td>Diagnostics from constructors</td>
					</tr>
					<tr>
						<td>DESTRUCTORS</td>
						<td>
							<font face="Courier New, Courier, mono">0x0002</font>
						</td>
						<td>Diagnostics from finalizers.</td>
					</tr>
					<tr>
						<td>CONSTRUCT_AND_DESTRUCT</td>
						<td>
							<font face="Courier New, Courier, mono">CONSTRUCTORS | DESTRUCTORS</font>
						</td>
						<td>Diagnostics from constructors and finalizers</td>
					</tr>
					<tr>
						<td>FUNCTIONS</td>
						<td>
							<font face="Courier New, Courier, mono">0x010</font>
						</td>
						<td>Diagnostics from functions</td>
					</tr>
					<tr>
						<td>OPERATORS</td>
						<td>
							<font face="Courier New, Courier, mono">0x020</font>
						</td>
						<td>Diagnostics from operators, such as equals</td>
					</tr>
					<tr>
						<td>FUNCS_AND_OPS</td>
						<td>
							<font face="Courier New, Courier, mono">FUNCTIONS | OPERATORS</font>
						</td>
						<td>Diagnostics from functions and operations.</td>
					</tr>
					<tr>
						<td>ALL_NON_TRIVIAL</td>
						<td>
							<font face="Courier New, Courier, mono">CONSTRUCT_AND_DESTRUCT | FUNCTIONS
      | OPERATORS</font>
						</td>
						<td>Diagnostics from all non-trivial operations</td>
					</tr>
					<tr>
						<td>TRIVIAL_FUNCS</td>
						<td>
							<font face="Courier New, Courier, mono">0x0100</font>
						</td>
						<td>Diagnostics from trivial functions.</td>
					</tr>
					<tr>
						<td>TRIVIAL_OPERATORS:</td>
						<td>
							<font face="Courier New, Courier, mono">0x0200</font>
						</td>
						<td>Diagnostics from trivial operations, and operators.</td>
					</tr>
					<tr>
						<td> ALL_TRIVIAL</td>
						<td>
							<font face="Courier New, Courier, mono">TRIVIAL_FUNCS | TRIVIAL_OPERATORS</font>
						</td>
						<td>Diagnostics from all trivial operations</td>
					</tr>
					<tr>
						<td>FULL_DEBUGGING</td>
						<td>
							<font face="Courier New, Courier, mono">0xffff</font>
						</td>
						<td>Full diagnostics.</td>
					</tr>
				</table>
				<ul>
					<li>Visibility level – JBossTS uses the default values defined in the class
    com.arjuna.common.util.logging.CommonVisibilityLevel </li>
				</ul>
				<table width="83%" border="1">
					<tr bgcolor="#8BD5FC">
						<td width="33%">
							<div align="center">
								<strong>Debug Level</strong>
							</div>
						</td>
						<td width="24%">
							<div align="center">
								<strong>Value</strong>
							</div>
						</td>
						<td width="43%">
							<div align="center">
								<strong>Description</strong>
							</div>
						</td>
					</tr>
					<tr>
						<td>VIS_NONE</td>
						<td>
							<font face="Courier New, Courier, mono">0x0000</font>
						</td>
						<td>No Diagnostic</td>
					</tr>
					<tr>
						<td>VIS_PRIVATE</td>
						<td>
							<font face="Courier New, Courier, mono">0x0001</font>
						</td>
						<td>only from private methods.</td>
					</tr>
					<tr>
						<td>VIS_PROTECTED</td>
						<td>
							<font face="Courier New, Courier, mono">0x0002</font>
						</td>
						<td>only from protected methods.</td>
					</tr>
					<tr>
						<td>VIS_PUBLIC</td>
						<td>
							<font face="Courier New, Courier, mono">0x0004</font>
						</td>
						<td>only from public methods.</td>
					</tr>
					<tr>
						<td>VIS_PACKAGE</td>
						<td>
							<font face="Courier New, Courier, mono">0x0008</font>
						</td>
						<td>only from package methods.</td>
					</tr>
					<tr>
						<td>VIS_ALL</td>
						<td>
							<font face="Courier New, Courier, mono">0xffff</font>
						</td>
						<td>Full Diagnostic</td>
					</tr>
				</table>
				<ul>
					<li>Facility Code – JBossTS uses the following values </li>
				</ul>
				<table width="83%" border="1">
					<tr bgcolor="#8BD5FC">
						<td>
							<div align="center">
								<strong>Facility Code Level </strong>
							</div>
						</td>
						<td>
							<div align="center">
								<strong>Value</strong>
							</div>
						</td>
						<td>
							<div align="center">
								<strong>Description</strong>
							</div>
						</td>
					</tr>
					<tr>
						<td>FAC_ATOMIC_ACTION</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000001</font>
						</td>
						<td>atomic action core module</td>
					</tr>
					<tr>
						<td>FAC_BUFFER_MAN</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000004</font>
						</td>
						<td>state management (buffer) classes</td>
					</tr>
					<tr>
						<td>FAC_ABSTRACT_REC</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000008</font>
						</td>
						<td>abstract records</td>
					</tr>
					<tr>
						<td>FAC_OBJECT_STORE</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000010</font>
						</td>
						<td>object store implementations</td>
					</tr>
					<tr>
						<td> FAC_STATE_MAN</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000020</font>
						</td>
						<td>state management and StateManager)</td>
					</tr>
					<tr>
						<td>FAC_SHMEM</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000040 </font>
						</td>
						<td>shared memory implementation classes</td>
					</tr>
					<tr>
						<td>FAC_GENERAL</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000080</font>
						</td>
						<td>general classes</td>
					</tr>
					<tr>
						<td>FAC_CRASH_RECOVERY</td>
						<td>
							<font face="Courier New, Courier, mono">0x00000800</font>
						</td>
						<td>detailed trace of crash recovery module and classes</td>
					</tr>
					<tr>
						<td>FAC_THREADING</td>
						<td>
							<font face="Courier New, Courier, mono">0x00002000</font>
						</td>
						<td>threading classes</td>
					</tr>
					<tr>
						<td>FAC_JDBC</td>
						<td>
							<font face="Courier New, Courier, mono">0x00008000</font>
						</td>
						<td>JDBC 1.0 and 2.0 support</td>
					</tr>
					<tr>
						<td>FAC_RECOVERY_NORMAL</td>
						<td>
							<font face="Courier New, Courier, mono">0x00040000</font>
						</td>
						<td>normal output for crash recovery manager</td>
					</tr>
				</table>
				<p>To ensure appropriate output, it is necessary to set some of the finer debug
  properties explicitly as follows:</p>
				<pre> &lt;properties&gt;
   &lt;!-- CLF 2.4 properties --&gt;
   &lt;property
     name=&quot;com.arjuna.common.util.logging.DebugLevel&quot;
     value=&quot;0x00000000&quot;/&gt;
   &lt;property
     name=&quot;com.arjuna.common.util.logging.FacilityLevel&quot;
     value=&quot;0xffffffff&quot;/&gt;
   &lt;property
     name=&quot;com.arjuna.common.util.logging.VisibilityLevel&quot;
     value=&quot;0xffffffff&quot;/&gt;
   &lt;property
     name=&quot;com.arjuna.common.util.logger&quot;
     value=&quot;log4j&quot;/&gt;
 &lt;/properties&gt;</pre>
				<p>By default, debugging messages are not enabled since the DebugLevel is set
  to NO_DEBUGGING (<font face="Courier New, Courier, mono">0x00000000</font>).
  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
  (<font face="Courier New, Courier, mono">0xffffffff</font>) and the FacilityCode
  Level FAC_CRASH_RECOVERY. </p>
				<p>
					<strong>Note</strong>: To enable finger debug messages, the logging level should
  be set to the DEBUG level as described below.</p>
				<p>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. </p>
				<p>The property <font face="Courier New, Courier, mono">com.arjuna.common.util.logger</font>
  allows to select the underlying logging system. Possible value are listed in
  the following table.</p>
				<table width="93%" border="1">
					<tr bgcolor="#8BD5FC">
						<td width="14%">
							<div align="center">
								<strong>Property Value</strong>
							</div>
						</td>
						<td width="86%">
							<div align="center">
								<strong>Description</strong>
							</div>
						</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">log4j</font>
						</td>
						<td>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: <font face="Courier New, Courier, mono">log4j.configuration</font>
						</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">jdk14</font>
						</td>
						<td>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.</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">simple</font>
						</td>
						<td>Selects the simple JDK 1.1 compatible console-based logger provided by
      Jakarta Commons Logging</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">csf</font>
						</td>
						<td>Selects CSF-based logging (CSF embeddor must be available)</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">jakarta</font>
						</td>
						<td>Uses the default log system selection algorithm of the Jakarta Commons
      Logging framework</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">dotnet</font>
						</td>
						<td>Selects a .net logging implementation <br/>
      Since a dotnet logger is not currently implemented, this is currently identical
      to <font face="Courier New, Courier, mono">simple</font>. Simple is a purely
      JDK1.1 console-based log implementation.</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">avalon</font>
						</td>
						<td>Uses the Avalon Logkit implementation</td>
					</tr>
					<tr>
						<td>
							<font face="Courier New, Courier, mono">noop</font>
						</td>
						<td>Disables all logging </td>
					</tr>
				</table>
			</html>
		</area>
	</content>
	<footer/>
</page>
