- User forum
- Developer forum
- Anonymous SVN
- JIRA issue tracker
- Downloads
- Blog
- Wiki Knowledge Base
- Subversion
- Latest release
- Documentation
- Transaction Fundamentals
- Overview of JBossTS
- History
- Why Choose JBossTS?
- Features
- JEE Support
- Web Services Support
- WS-TX Bridging
- Platform Support
- Deployment Options
- Transaction Recovery
- Product Architecture
- Realtime chat (IRC)
- The team
- Mailing lists
- Presentations
- Student Projects
- Additional Material
JBTS-PG-3/31/06
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.
Copyright
JBoss, Home of Professional Open Source Copyright 2006, JBoss Inc., and individual contributors as indicated by the @authors tag.� All rights reserved.
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
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.
� Copyright 2006 JBoss Inc.
Contents
An overview of transaction processing
The Object Transaction Service
Advanced application programmer interface
JBossTS and the OTS specification
Application programming models
ORB specific location mechanism
Overriding the default location mechanism
Transactions and registered resources
Asynchronously committing a transaction
Summary of JBossTS implementation decisions
Constructing an OTS application
Implicit context propagation and interposition
Writing applications using the raw OTS interfaces
Transaction context management
A transaction originator: indirect and implicit
Transaction originator: direct and explicit
Implementing a transactional client
Implementing a recoverable server
Example of a recoverable server
Example of a transactional object
JBossTS interfaces for extending the OTS
Configuring the failure recovery subsystem for your ORB
Configuring the Recovery Manager
Transaction statuses and replay_completion
Starting the Transaction Service tools
Using Attributes and Operations
The JTS Programmers Guide contains information on how to use JBoss Transactions 4.2. This document provides a detailed look at the design and operation of.� It describes the architecture and the interaction of components and within this architecture.
Although this guide is specifically intended for service developers using JBoss Transactions 4.2, it will be useful to anyone who would like to gain an understanding of the transactions and how they function.
This guide assumes a basic familiarity with Java� service development and object-oriented programming.� A fundamental level of understanding in the following areas will also be useful:
� A general understanding of the APIs, components, and objects that are present in Java applications.
� A general understanding of the Windows and UNIX operating systems.
This guide contains the following chapters:
� Chapter 1, An Overview of transaction processing: gives an brief overview of the transaction processing.
� Chapter 2, JBossTS basics: presents JBossTS and describes its features in terms on compliance to JTS/OTS specifications and enhancements it provides in regards to the OTS specification.
� Chapter 3, An introduction to the OTS: describes OTS and the programming models from the User point of view. The way JBossTS offers these programming models and JBossTS enhancements are described.�
� Chapter 4, Constructing an OTS application: describes how to build an OTS application using JBossTS.
� Chapter 5, JBossTS interfaces for extending the OTS: contains a description of the use of JBossTS classes that provide extensions to the OTS interfaces.
� Chapter 6, Example: illustrates a detailed client/server example.
� Chapter 7, Failure Recovery: describes how to configure JBossTS to manage Failure recovery.
� Chapter 8, JTA and the JTS: describes how to configure JTA to be aware of JTS.
� Chapter 9, Tools: explains how to start and use the tools framework and what tools are available.
� Chapter 10, ORB specific configurations: describes how to configure specific ORBs.
� Chapter 11, Configuring JBossTS: shows configurations features of JBossTS.
The following conventions are used in this guide:
|
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: |
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
In addition to this guide, the following guides are available in the JBoss Transactions 4.2 documentation set:
� JBoss Transactions 4.2 Release Notes:� Provides late-breaking information about JBoss Transactions 4.2.
� JBoss Transactions 4.2 Installation Guide:� This guide provides instructions for installing JBoss Transactions 4.2.
� JBoss Transactions 4.2 Administration Guide:� Provides guidance for writing applications.
� JBoss Transactions 4.2 Quick Start Guide:� Getting started quickly with the system.
� Arjuna Transactions API Programmer�s Guide: Provides guidance when using the JTA for building transactional applications.
� TxCore 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.
Questions or comments about JBoss Transactions 4.2 should be directed to our support team. Send email to support@arjuna.com.
An overview of transaction processing
Consider the following situation: a user wishes to purchase access to an on-line newspaper and requires to pay for this access from an account maintained by an on-line bank. Once the newspaper site has received the user�s credit from the bank, they will deliver an electronic token to the user granting access to their site. Ideally the user would like the debiting of the account, and delivery of the token to be �all or nothing� (atomic). However, hardware and software failures could prevent either event from occurring, and leave the system in an indeterminate state.
Atomic transactions (transactions) possess an �all-or-nothing� property, and are a well-known technique for guaranteeing application consistency in the presence of failures. Transactions possess the following ACID properties:
� Atomicity: The transaction completes successfully (commits) or if it fails (aborts) all of its effects are undone (rolled back).
� Consistency: Transactions produce consistent results and preserve application specific invariants.
� Isolation: Intermediate states produced while a transaction is executing are not visible to others. Furthermore transactions appear to execute serially, even if they are actually executed concurrently.
� Durability: The effects of a committed transaction are never lost (except by a catastrophic failure).
A transaction can be terminated in two ways: committed or aborted (rolled back). When a transaction is committed, all changes made within it are made durable (forced on to stable storage, e.g., disk). When a transaction is aborted, all of the changes are undone. Atomic actions can also be nested; the effects of a nested action are provisional upon the commit/abort of the outermost (top-level) atomic action.
Commit protocol
A two-phase commit protocol is required to guarantee that all of the action participants either commit or abort any changes made. Figure 1 illustrates the main aspects of the commit protocol: during phase 1, the action coordinator, C, attempts to communicate with all of the action participants, A and B, to determine whether they will commit or abort. An abort reply from any participant acts as a veto, causing the entire action to abort. Based upon these (lack of) responses, the coordinator arrives at the decision of whether to commit or abort the action. If the action will commit, the coordinator records this decision on stable storage, and the protocol enters phase 2, where the coordinator forces the participants to carry out the decision. The coordinator also informs the participants if the action aborts.
When each participant receives the coordinator�s phase 1 message, they record sufficient information on stable storage to either commit or abort changes made during the action. After returning the phase 1 response, each participant who returned a commit response must remain blocked until it has received the coordinator�s phase 2 message. Until they receive this message, these resources are unavailable for use by other actions. If the coordinator fails before delivery of this message, these resources remain blocked. However, if crashed machines eventually recover, crash recovery mechanisms can be employed to unblock the protocol and terminate the action.
Figure 1: Two-phase commit protocol.
Transactional proxies
The action coordinator maintains a transaction context where resources taking part in the action are required to be registered. Such a resource must obey the transaction commit protocol guaranteeing ACID properties; typically this means that the resource will provide specific operations which the action can invoke during the commit/abort protocol. However, it may not be possible to make all resources transactional in this way, e.g., legacy code which cannot be modified. To use these resources within an action it is often possible to provide transactional proxies: the proxy is registered with, and manipulated by, the action as though it were a transactional resource, and the proxy performs implementation specific work to make the resource it represents transactional. This requires that the proxy participate within the commit/abort protocol. Because the work of the proxy is performed as part of the action, it is guaranteed to be completed or undone despite failures of the action coordinator or action participants.
Nested transactions
Given a system that provides transactions for certain operations, it is sometimes necessary to combine them to form another operation, which is also required to be a transaction. The resulting transaction�s effects are a combination of the effects of the transactions from which it is composed. The transactions which are contained within the resulting transaction are said to be nested (or subtransactions), and the resulting transaction is referred to as the enclosing transaction. The enclosing transaction is sometimes referred to as the parent of a nested (or child) transaction. A hierarchical transaction structure can thus result, with the root of the hierarchy being referred to as the top-level transaction.
An important difference exists between nested and top-level transactions: the effect of a nested transaction is provisional upon the commit/roll back of its enclosing transaction(s), i.e., the effects will be recovered if the enclosing transaction aborts, even if the nested transaction has committed.
Subtransactions are a useful mechanism for two reasons:
� fault-isolation: if subtransaction rolls back (e.g., because an object it was using fails) then this does not require the enclosing transaction to rollback, thus undoing all of the work performed so far.
� modularity: if there is already a transaction associated with a call when a new transaction is begun, then the transaction will be nested within it. Therefore, a programmer who knows that an object require transactions can use them within the object: if the object�s methods are invoked without a client transaction, then the object�s transactions will simply be top-level; otherwise, they will be nested within the scope of the client�s transactions. Likewise, a client need not know that the object is transactional, and can begin its own transaction.
The Object Transaction Service
The CORBA architecture, as defined by the OMG, is a standard derived by an industrial consortium which promotes the construction of interoperable applications that are based upon the concepts of distributed objects. The architecture principally contains the following components:
� Object Request Broker (ORB), which enables objects to transparently make and receive requests in a distributed, heterogeneous environment. This component is the core of the OMG reference model.
� Object Services, a collection of services that support functions for using and implementing objects. Such services are considered to be necessary for the construction of any distributed application. Of particular relevance to this manual is the Object Transaction Service (OTS).
� Common Facilities, are other useful services that applications may need, but which are not considered to be fundamental such as desktop management and help facilities.
The CORBA architecture is structured to allow both its implementation in, and the integration of, a wide variety of object systems. In particular, applications are independent of the loca