Skip to content

Commit 13a136d

Browse files
lorbanlorban
committed
Merge pull request #54 from maxant/BTM-51
added docs from archive
2 parents 9188ca9 + e03edaf commit 13a136d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+3326
-0
lines changed

‎btm-docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The files contained in `src/main/asciidoc` are [asciidoc](http://asciidoctor.org/) files. HTML / PDF can be generated out of them using the `asciidoc` tool, or by running `mvn generate-resources`. After Maven runs, you can read the HTML documentation by starting at `target/generated-docs/index.html`.
2+
3+
The original content was lost when the code was moved from codehaus.org over to GitHib. Thanks to web archive, it was possible to get the original content from e.g. [http://web.archive.org/web/20150520175151/https://docs.codehaus.org/display/BTM/Home](http://web.archive.org/web/20150520175151/https://docs.codehaus.org/display/BTM/Home).

‎btm-docs/pom.xml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
<parent>
5+
<groupId>org.codehaus.btm</groupId>
6+
<artifactId>btm-parent</artifactId>
7+
<version>3.0.0-SNAPSHOT</version>
8+
</parent>
9+
10+
<artifactId>btm-docs</artifactId>
11+
<name>Bitronix Transaction Manager :: Docs</name>
12+
<packaging>pom</packaging>
13+
14+
<build>
15+
<plugins>
16+
<plugin>
17+
<groupId>org.asciidoctor</groupId>
18+
<artifactId>asciidoctor-maven-plugin</artifactId>
19+
<executions>
20+
<execution>
21+
<id>output-html</id>
22+
<phase>generate-resources</phase>
23+
<goals>
24+
<goal>process-asciidoc</goal>
25+
</goals>
26+
</execution>
27+
</executions>
28+
<configuration>
29+
<backend>html</backend>
30+
</configuration>
31+
</plugin>
32+
</plugins>
33+
</build>
34+
35+
</project>

‎btm-docs/src/main/asciidoc/Build.adoc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
= Building from source
2+
3+
== Contents
4+
5+
* <<prerequisites,Prerequisites>>
6+
* <<source,Getting the Source>>
7+
* <<building,Building>>
8+
* <<ide,IDE Integration>>
9+
10+
[[prerequisites]]
11+
== Prerequisites
12+
13+
You need to have these softwares installed to be able to build BTM:
14+
15+
* GIT
16+
* JDK 1.5
17+
* Apache Maven 2.2.1 (or higher)
18+
19+
[[source]]
20+
== Getting the Source
21+
22+
The project uses GIT as it's source code control system.
23+
The source can be checked out anonymously using:
24+
25+
git clone git://git.codehaus.org/btm-git.git
26+
27+
[[building]]
28+
== Building
29+
30+
The project uses Apache Maven 2 as it's build tool.
31+
Go to the top level directory of the project and type:
32+
33+
mvn install
34+
35+
This will build BTM locally, run tests, build javadoc and install the generated artifacts in your local repository.
36+
37+
[[ide]]
38+
== IDE Integration
39+
40+
Because BTM supports JDBC3 and JDBC4 at the same time, setting up an IDE in a way that there are no errors can be "tricky". See these links for an example of how an IDE can be configured.
41+
42+
* link:ConfiguringIntelliJ.html[Configuring IntelliJ IDE]
43+
* link:ReleaseProcedure.html[Release procedure]

‎btm-docs/src/main/asciidoc/Configuration2x.adoc‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
= Configuration
2+
3+
BTM configuration settings are stored in a `Configuration` object. It can be obtained by calling `TransactionManagerServices.getConfiguration()`. All settings are documented in the javadoc and you should refer to it to know what can be configured.
4+
5+
== Contents
6+
7+
* <<howConfig,How to configure BTM>>
8+
** <<props,The properties configuration file>>
9+
** <<setting,Setting values directly on the Configuration object>>
10+
* <<configSettings,Configurable settings>>
11+
** <<txEngine,Transaction engine settings>>
12+
** <<journal,Journal settings>>
13+
** <<timers,Timers settings>>
14+
** <<resourceLoader,Resource Loader settings>>
15+
* <<pools,Connection pools settings>>
16+
17+
[[howConfig]]
18+
== How to configure BTM
19+
20+
The `Configuration` object is implemented with sensible default settings. For a first time user, all default settings are good enough. After the initial testing phase, you might want to change some settings. This can be done in two ways: via a properties configuration file or by setting values directly on the Configuration object.
21+
22+
[[props]]
23+
=== The properties configuration file
24+
25+
You can create a properties file in which you'll set some configuration settings. All the ones you omit will keep their default value.
26+
The file can be stored anywhere on the file system in which case you need to set the `bitronix.tm.configuration` system property to tell BTM where the file lies. This is generally done by adding a -D argument to the virtual machine's command line:
27+
28+
java -Dbitronix.tm.configuration=./my-btm-config.properties MyClass
29+
30+
Another way is to call the properties file `bitronix-default-config.properties` and store it at the root of your classpath.
31+
The properties file is in the default format `key=value`. Ant-like references (`${some.property.name}`) to other properties or to system properties (defined with -D on the command line) are supported.
32+
33+
[[setting]]
34+
=== Setting values directly on the Configuration object
35+
You can call any setter you want on the object you get from the call to `TransactionManagerServices.getConfiguration()`. This is convenient if you do not want to use the properties file to configure BTM but want to leverage - for instance - Spring instead.
36+
37+
Configuration conf = TransactionManagerServices.getConfiguration();
38+
conf.setServerId("jvm-1");
39+
conf.setLogPart1Filename("./tx-logs/part1.btm");
40+
conf.setLogPart2Filename("./tx-logs/part2.btm");
41+
42+
.Read only configuration
43+
****
44+
Once BTM has started, any attempt to call a set method on the Configuration object will throw a `IllegalStateException`.
45+
****
46+
47+
Since the Configuration object is a singleton, there is no need to pass it to any other object, BTM will pick it up at startup.
48+
49+
.Configuration dropped after restart
50+
****
51+
The Configuration object is dropped during BTM shutdown. You need to call all setters methods again before you restart the transaction manager. Keep this in mind if you plan to hot-redeploy your application in your application server.
52+
****
53+
54+
[[configSettings]]
55+
== Configurable settings
56+
57+
There are many different settings that are configurable in the transaction manager. Fortunately, all defaults settings are usually good enough to get started. You only need to tune them when required.
58+
59+
[[txEngine]]
60+
=== Transaction engine settings
61+
62+
These configurable properties are related to the transaction manager's core.
63+
64+
See also https://github.com/bitronix/btm/blob/master/btm/src/main/java/bitronix/tm/Configuration.java.
65+
66+
[options="header", cols="4*"]
67+
|====
68+
|File property name|Configuration property name|Default value|Description
69+
|bitronix.tm.serverId
70+
|serverId
71+
|The machine's IP address but that's unsafe for production usage
72+
|a stable ASCII string that must uniquely identify this TM instance. It must not exceed 51 characters or it will be truncated.
73+
|bitronix.tm.2pc.async
74+
|asynchronous2Pc
75+
|false
76+
|Should two phase commit be executed asynchronously? Asynchronous two phase commit will improve 2PC execution time when there are many resources enlisted in transactions but can be very CPU intensive when used on JDK 1.4 without the java.util.concurrent backport implementation available on the classpath. It also makes debugging more complex. link:ImplementationDetails.html#asynchronous2Pc[See here for more details].
77+
|bitronix.tm.2pc.warnAboutZeroResourceTransactions
78+
|warnAboutZeroResourceTransaction
79+
|true
80+
|Should transactions executed without a single enlisted resource result in a warning or not? Most of the time transactions executed with no enlisted resource reflect a bug or a mis-configuration somewhere.
81+
|bitronix.tm.2pc.debugZeroResourceTransactions debugZeroResourceTransaction false Should creation and commit call stacks of transactions executed without a single enlisted resource tracked and logged or not? This is a companion to `warnAboutZeroResourceTransaction` where the transaction creation and commit call stacks could help you identify the culprit code.
82+
|bitronix.tm.disableJmx
83+
|disableJmx
84+
|false
85+
|The transaction manager registers objects in the JMX registry by default if available. Set this to true to never register JMX objects.
86+
|bitronix.tm.jndi.userTransactionName
87+
|jndiUserTransactionName
88+
|java:comp/UserTransaction
89+
|The name under which the transaction manager will be bound in the internal JNDI provider.
90+
|bitronix.tm.allowMultipleLrc allowMultipleLrc false Should the transaction manager allow multiple LRC resources to be enlisted into the same transaction? Having multiple LRC resources participate in a transaction gives up the recovery guarantee but sometimes is useful in development mode.
91+
|bitronix.tm.currentNodeOnlyRecovery
92+
|currentNodeOnlyRecovery
93+
|true
94+
|Set this to true if you run multiple instances of the transaction manager on the same JMS and JDBC resources to avoid the recovery process to try to recover transactions started by another node. See here for more details.
95+
|====
96+
97+
[[journal]]
98+
=== Journal settings
99+
100+
These configurable properties are related to the disk journal used to record recovery information.
101+
102+
See also https://github.com/bitronix/btm/blob/master/btm/src/main/java/bitronix/tm/Configuration.java.
103+
104+
[options="header", cols="4*"]
105+
|====
106+
|File property name|Configuration property name|Default value|Description
107+
|bitronix.tm.journal
108+
|journal
109+
|disk
110+
|Set the journal to be used to record transaction logs. This can be any of `disk`, `null` or a class name. The disk journal is a classic implementation using two fixed-size files and disk forces, the null journal just allows one to disable logging. This can be useful to run tests. *Do not use the null journal on production as without transaction logs, atomicity cannot be guaranteed.*
111+
|bitronix.tm.journal.disk.logPart1Filename
112+
|logPart1Filename
113+
|btm1.tlog
114+
|Journal fragment file 1.
115+
|bitronix.tm.journal.disk.logPart2Filename
116+
|logPart2Filename
117+
|btm2.tlog
118+
|Journal fragment file 2.
119+
|bitronix.tm.journal.disk.forcedWriteEnabled
120+
|forcedWriteEnabled
121+
|true
122+
|Are logs forced to disk? *Do not set to false on production since without disk force, atomicity cannot be guaranteed.*
123+
|bitronix.tm.journal.disk.forceBatchingEnabled
124+
|forceBatchingEnabled
125+
|true
126+
|Are disk forces batched? Disabling batching can seriously lower the transaction manager's throughput.
127+
|bitronix.tm.journal.disk.maxLogSize
128+
|maxLogSize
129+
|2
130+
|Maximum size in megabytes of the journal fragments. Larger logs allow transactions to stay longer in-doubt but the TM pauses longer when a fragment is full.
131+
|bitronix.tm.journal.disk.filterLogStatus
132+
|filterLogStatus
133+
|false
134+
|Should only mandatory logs be written? Enabling this parameter lowers space usage of the fragments but makes debugging more complex.
135+
|bitronix.tm.journal.disk.skipCorruptedLogs
136+
|skipCorruptedLogs
137+
|false
138+
|Should corrupted transactions log entries be skipped? Use only at last resort when all you have to recover is a pair of corrupted files.
139+
|====
140+
141+
[[timers]]
142+
=== Timers settings
143+
144+
The transaction manager heavily relies on timeouts. All of them can be configured.
145+
146+
See also https://github.com/bitronix/btm/blob/master/btm/src/main/java/bitronix/tm/Configuration.java.
147+
148+
[options="header", cols="4*"]
149+
|====
150+
|File property name|Configuration property name|Default value|Description
151+
|bitronix.tm.timer.defaultTransactionTimeout
152+
|defaultTransactionTimeout
153+
|60
154+
|Default transaction timeout in seconds.
155+
|bitronix.tm.timer.gracefulShutdownInterval
156+
|gracefulShutdownInterval
157+
|60
158+
|Maximum amount of seconds the TM will wait for transactions to get done before aborting them at shutdown time.
159+
|bitronix.tm.timer.backgroundRecoveryInterval
160+
|backgroundRecoveryInterval
161+
|0
162+
|*Deprecated* Interval in minutes at which to run the recovery process in the background. Cannot be disabled.
163+
|bitronix.tm.timer.backgroundRecoveryIntervalSeconds
164+
|backgroundRecoveryIntervalSeconds
165+
|60
166+
|Interval in seconds at which to run the recovery process in the background. Cannot be disabled.
167+
|====
168+
169+
[[resourceLoader]]
170+
=== Resource Loader settings
171+
172+
The resource loader loads and configures XA resources using configuration stored in a properties file. See the Resource Loader page for more details.
173+
174+
See also https://github.com/bitronix/btm/blob/master/btm/src/main/java/bitronix/tm/Configuration.java.
175+
176+
[options="header", cols="4*"]
177+
|====
178+
|File property name |Configuration property name |Default value |Description
179+
|bitronix.tm.resource.configuration
180+
|resourceConfigurationFilename
181+
|none (optional)
182+
|Resource Loader configuration file name.
183+
|====
184+
185+
[[pools]]
186+
== Connection pools settings
187+
188+
JDBC and JMS connection pools configuration are discussed in details in the JDBC pools configuration and the JMS pools configuration pages. Alternatively you can use the Resource Loader instead.

‎btm-docs/src/main/asciidoc/ConfiguringIntelliJ.adoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
= Configuring IntelliJ IDE
2+
3+
Follow these steps to configure IntelliJ IDE for btm development. These guide assumes you have already downloaded and built the source successfully with Maven.
4+
5+
****
6+
Note: The following steps apply to the Bitronix 2.2 development branch, not prior releases.
7+
****
8+
9+
== Step 1
10+
11+
Start the IntelliJ IDE, and select "New Project..." from the File menu.
12+
13+
image::intellij01.png[]
14+
15+
Select the option "Import project from external model" (which includes Maven support). Click "Next".
16+
17+
image::intellij02.png[]
18+
19+
Select the "Maven" option. Click "Next".
20+
21+
image::intellij03.png[]
22+
23+
* Set the "Root directory" to point to your GIT directory that contains the bitronix project. In the example above, "/Users/brettw/Documents/dev/bitronix"
24+
* Select the checkbox to keep your project files in a separate directory, and select a directory. In the example above, "/Users/brettw/Documents/intellij".
25+
* Select the checkbox to "Import Maven projects automatically".
26+
* Select the checkbox to "Create module groups for multi-module Maven projects".
27+
* Click "Next".
28+
29+
image::intellij04.png[]
30+
31+
Select the 'dist' profile. Click "Next".
32+
33+
image::intellij05.png[]
34+
35+
Check to make sure the bitronix project shows up, and is selected. Click "Next".
36+
37+
image::intellij06.png[]
38+
39+
The defaults should be fine here, just click "Finish".
40+
Your project tree should now look like this:
41+
42+
image::intellij07.png[]
43+
44+
== Step 2
45+
Now we're going to setup the module paths so that IntelliJ can build with both JDBC3 and JDBC4 at the same time.
46+
Right-click on the bitronix project in the project tree, and choose "Open Module Settings" from the menu. A window like this should open:
47+
48+
image::intellij08.png[]
49+
50+
Now, perform these steps for the "btm" module:
51+
52+
- Select the "btm" module in the second pane from the left.
53+
- Click on the "Dependencies" tab for the btm module.
54+
- Select the "btm-jdbc3-stubs" dependency, and move it up, above the Java VM dependency ("1.6 (java version 1.6.0_26)" in the screenshot, possibly "1.5" in your environment).
55+
- The result should look like this:
56+
57+
image::intellij09.png[]
58+
59+
In IntelliJ, dependencies that appear after the JDK are added to the classpath, and dependencies that appear before the JDK are added to the bootclasspath.
60+
Now, perform these steps for the "btm-jdbc4" module:
61+
62+
- Select the "btm-jdbc4" module in the second pane from the left.
63+
- Click on the "Dependencies" tab for the btm-jdbc4 module.
64+
- Select the "btm-jdbc4-stubs" dependency, and move it up, above the Java VM dependency ("1.6 (java version 1.6.0_26)" in the screenshot, possibly "1.5" in your environment).
65+
- The result should look like this:
66+
67+
image::intellij10.png[]
68+
69+
Ok, you're done! Now, click "OK" to dismiss the module settings dialog.
70+
71+
== Step 3
72+
73+
Click on the "Build" menu, and select "Rebuild Project". The projects should now build without error.
74+
75+
*Happy developing! The Bitronix Team welcomes your contribution.*
76+

0 commit comments

Comments
 (0)