JBoss Transactions 4.2.3

Release Notes

JBTS-RN-4/12/07

Legal Notices

The information contained in this documentation is subject to change without notice.

JBoss Inc. makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. JBoss Inc. shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

Java™ and J2EE is a U.S. trademark of Sun Microsystems, Inc. Microsoft® and Windows NT® are registered trademarks of Microsoft Corporation. Oracle® is a registered U.S. trademark and Oracle9™, Oracle9 Server™ Oracle9 Enterprise Edition™ are trademarks of Oracle Corporation. Unix is used here as a generic term covering all versions of the UNIX® operating system. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

Arjuna is a trademark of Hewlett-Packard Company and is used here under licence.

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 General Public License, v. 2.0. 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 General Public License for more details. You should have received a copy of the GNU General Public License, v. 2.0 along with this distribution; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, * MA 02110-1301, USA.

Software Version

JBoss Transactions 4.2.3.

Restricted Rights Legend

Use, duplication, or disclosure is subject to restrictions as set forth in contract subdivision (c)(1)(ii) of the Rights in Technical Data and Computer Software clause 52.227-FAR14.

Contents

About This Guide

What This Guide Contains

The Release Notes contains important information on changes to JBoss Transactions 4.2.3 since the last release and information on any outstanding issues.

Audience

This guide is most relevant to engineers who are responsible for administering JBoss Transactions 4.2.3 installations.

Prerequisites

None.

Organization

This guide contains the following chapters:

· Chapter 1, Release notes: contains the actual release notes.

Documentation Conventions

The following conventions are used in this guide:

Convention	Description
Italic	In paragraph text, italic identifies the titles of documents that are being referenced. When used in conjunction with the Code text described below, italics identify a variable that should be replaced by the user with an actual value.
Bold	Emphasizes items of particular importance.
Code	Text that represents programming code.
Function \| Function	A path to a function or dialog box within an interface. For example, “Select File \| Open.” indicates that you should select the Open function from the File menu.
( ) and \|	Parentheses enclose optional items in command syntax. The vertical bar separates syntax items in a list of choices. For example, any of the following three items can be entered in this syntax: persistPolicy (Never \| OnTimer \| OnUpdate \| NoMoreOftenThan)
Note: Caution:	A note highlights important supplemental information. A caution highlights procedures or information that is necessary to avoid damage to equipment, damage to software, loss of data, or invalid test results.

Table 1 Formatting Conventions

Additional Documentation

In addition to this guide, the following guides are available in the JBoss Transactions 4.2.3 documentation set:

· JBoss Transactions 4.2.3 Administration Guide: Provides information on administering JBoss Transactions 4.2.3.

· JBoss Transactions 4.2.3 Installation Guide: This guide provides instructions for installing JBoss Transactions 4.2.3.

· JBoss Transactions 4.2.3 Programmer’s Guide: Provides guidance for writing applications.

· JBoss Transactions 4.2.3 Quick Start Guide: Getting started with JBossTS; not for a novice user.

· JBoss Transactions API Programmer’s Guide: Provides guidance when using the JTA for building transactional applications.

· JBoss Transactions Failure Recovery Guide: Describes the failure recovery aspects of JBossTS.

· TxCore Programmer’s Guide: Describes how to write transactional applications using the non-distributed transaction engine at the heart of JBossTS.

Contacting Us

Questions or comments about JBoss Transactions 4.2.3 should be directed to our support team.

Chapter 1

Release notes

Enhancements

This is the first release of JBoss Transactions, formerly the JBoss Transaction Service. In order to facilitate migration of existing JBossTS users, there have been no changes to the structure or deployment in this release of JBossTS. However, in subsequent releases there will be modifications to the package structure and other updates, so please continue to check the Release Notes.

The following enhancements have been made to the 4.2 GA version of JBossTS:

· This release supports the Last Resource Commit Optimization for resources that are not two phase aware. This functionality is only supported by the JTS Transaction Manager.

· This release supports JBoss Application Server 4.0.3SP1, 4.0.4 and 4.0.5.

Fixed issues

The following issues have been identified and fixed:

1. [JBTM-71] - Bank example still refers to ArjunaTS

2. [JBTM-72] - Trail map neglects to remind reader to start recovery manager

3. [JBTM-73] - Update trailmap text to remove Arjuna references

4. [JBTM-85] - BasicXARecovery example class is broken

5. [JBTM-92] - Print error message when prepare fails in XAResource

6. [JBTM-96] - XARecoveryModule does not use I18N logger in all info cases

7. [JBTM-110] - Fix typo in timeout section of manual

8. [JBTM-119] - Release notes are inaccurate

9. [JBTM-120] - Error in not calling end before terminating suspended RMs

10. [JBTM-124] - atsintegration must have its own logging

11. [JBTM-125] - The transaction manager implementation in JNDI should implement the org.jboss.tm.TransactionTimeoutConfiguration interface

12. [JBTM-126] - JTS XATerminator references arjunacore classes

13. [JBTM-127] - UID must befine a value for the maximum UID and enforce the ordering during comparison.

14. [JBTM-128] - warning with TransactionManager interface in JTS with external TM

15. [JBTM-130] - Validation of timeout values before calling the reaper

16. [JBTM-132] - Incorrect Uid values used in JTA/JTS XAResourceRecord

17. [JBTM-133] - Correct handling of one phase commit heuristics

18. [JBTM-135] - Null pointer exception in JCA XATerminator recover

19. [JBTM-139] - The JTA UserTransaction does not disassociate the transaction from the current thread if it has been terminated through the transaction reaper as a consequence of a timeout.

20. [JBTM-140] - The JTS UserTransaction raises the wrong exception if the transaction has been terminated through the transaction reaper as a consequence of a timeout.

21. [JBTM-152] - wsarjtx ba terminator uses the AT NotificationType instead of the wsarjtc NotificationType

22. [JBTM-154] - SOAP processor access should be serialised

23. [JBTM-157] - ParticipantRecord does not update _complete flag after calling coordinator driven complete

24. [JBTM-158] - WS-A 2005 invocations which return a null (202) response should copy the incoming message before executing on a background thread

25. [JBTM-163] - ENABLE_STATISTICS invalid reference in Programmers Guide

26. [JBTM-165] - webservice.xml for the XTS demo application should have QNames for the wsdl-port elements

Known issues

Issues that are known in this release are:

27. When running within the JBoss Application Server, there has been no attempt at modifications of either JBossMQ or JBossMessaging to make use of JBoss Transactions.

28. The Last Resource Commit Optimization is not supported by the JTS Transaction Manager when interposition is being used. The value of the property com.arjuna.ats.jts.contextPropMode must be set to CONTEXT.

29. There is an issue with Oracle 9.2 (and some older versions of Oracle 8) to do with transaction serializability. It is not possible to set the transaction isolation level to serializable on JDBC connections used in global (XA) transactions. Normally transaction isolation levels are set on a connection obtained from an XAConnection. However, if the isolation level is changed from the default (read committed) to serializable, Oracle throws an XAException (XAER_RMERR and OracleXAException code 24776) whenever XAResource.start is called (even if only on a single resource). As such, if you want to use Oracle you can only do so with the default isolation level. If you are using the Arjuna JDBC driver, this can be obtained by setting the property com.arjuna.ats.jdbc.isolationLevel to TRANSACTION_READ_COMMITTED. We are investigating other solutions to this issue. (Note, see misc/oraclexa.java for example code that illustrates the issue.)

30. The current OTS contains corrections to several errors in the CosTransactions idl which have yet to be fixed. Although these errors do not cause problems in several of the leading commercial ORBs we have had to impose our own corrections to the CosTransactions idl in order to get JBossTS to run on other, more OMG compliant ORBs. It is unlikely that the modifications we have made will correspond exactly to the final changes the OMG will make. The CosTransactions.idl and ArjunaOTS.idl files used in this document are idealised versions, i.e., how they should be if all ORBs worked correctly. You should always examine the idl files installed with your version of JBossTS to determine any differences.

31. In previous drafts of the OTS, there were several name clashes between interface names and variable names. These include, the variable names coordinator and terminator in the TransIdentity structure. These have been changed to coord and term. However, the variable current (used in the same structure), which clashes with the Current interface, has not been changed; we have changed this to currentTransaction.

32. Several ORBs cannot cope with anonymous sequences, i.e., sequence <octet> tid. Therefore, several typedefs have been added to the idl specifically for these ORBs.

33. The JacORB POA has a minimum and maximum number of threads available to it
in it's thread pool to process invocations. These values are set in the
jacorb.properties file as jacorb.poa.thread_pool_max and
jacorb.poa.thread_pool_min. If these variables are not tailored to your
application the POA can get into a state where it cannot process requests
because the pool has been exhausted and the 'in-use' request processors are
waiting to make invocations on the same POA. This has the same apparent
affect as your application being deadlocked.

34. The trail map accompanying JBossTS does not work correctly if it is installed in a directory containing spaces.

35. When doing explicit interposition on JDBC/XA connections, the calling order
should be:

begin()
registerTransaction()
getConnection()

close()
unregisterTransaction()
commit() / rollback()

If the close() is done after the unregisterTransaction(), Oracle will throw
a oracle.jdbc.xa.OracleXAException() when the next transaction is started.

36. The XTS trailmap demo application generates warning messages on the application server console if it is run in JBoss 4.0.4GA or 4.0.5GA. These warnings do not affect the funtionality of the demo application. The warning is: [JSR109ServerMetaDataBuilder] Cannot obtain SEI mapping for: