Distributed Transactions and PegaRULES Process Commander. PegaRULES Process Commander Versions 5.1 and 5.2

Transcription

1 Distributed Transactions and PegaRULES Process Commander PegaRULES Process Commander Versions 5.1 and 5.2

2 Copyright 2007 Pegasystems Inc., Cambridge, MA All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time. This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA Phone: (617) Fax: (617) PegaRULES Process Commander Distributed Transactions and PegaRULES Process Commander Software Version 5.1 and 5.2 Updated: January 2007

3 Contents Distributed Transactions and Process Commander... 4 Distributed Transactions and Transaction Types... 5 Transaction Boundaries... 6 Container-Managed Transactions and Application Design...12 Services and Transactions...13 EJB and Java Services...13 JMS Services...14 Connectors and Transactions...16 Connectors Running in User s Requestor Context...16 SQL Connectors, the External Data Table Feature, and Bean-Managed Transactions...16 Running Connectors in Parallel...17 JMS Connectors and Container-Managed Transactions...17

4 4 Distributed Transactions and PegaRULES Process Commander Distributed Transactions and Process Commander A distributed transaction is one in which more than one resource manager participates. When PegaRULES Process Commander (Process Commander) is deployed as an enterprise application, it can participate in distributed transactions. For example, Process Commander could use two separate database drivers to write data to two databases as part of the same transaction, or, it could make a transaction in which a JMS message is sent to a queue when a database write operation occurs. This document provides an overview of how Process Commander manages or participates in transactions. It discusses transactional boundaries, transaction types, and how services enable Process Commander to participate in containermanaged transactions. For information about the Java Transaction API, see JSR 907 on the Java Community Process web site.

5 Distributed Transactions and PegaRULES Process Commander 5 Distributed Transactions and Transaction Types Starting in version 5.1 SP1, when Process Commander is deployed as an enterprise application and your system is configured to use a JDBC driver with XA support, your Process Commander applications can participate in distributed transactions. If your Process Commander system is deployed as a web application or as an enterprise application that uses non-xa JDBC drivers, it does not participate in distributed transactions. That is, commits are not transactions, they are database operations. Therefore, if your Process Commander application must participate in distributed transactions, Process Commander must be deployed as an enterprise application. If the objects your application saves are completely contained in the PegaRULES database that is, commits do not save changes to more than one database your application does not require the ability to participate in distributed transactions and there is no need for your Process Commander system to use database drivers with XA support. If your application does need to participate in a distributed transaction objects are saved to two separate databases and need a two-phased commit, for example the transaction should be bean-managed by Process Commander, which is the default state of your Process Commander system. Bean-managed transactions are those for which Process Commander directly uses the Java Transaction API (JTA) to begin, commit, or roll back changes. That is, Process Commander manages the transaction. When human users interact with Process Commander through a Web browser, transactions are beanmanaged. Container-managed transactions are those for which Process Commander participates as one resource in a distributed transaction. When service requests for transaction-aware service rules (EJB, Java, and JMS) are received, any transactions that result from the service processing can be either bean-managed or container-managed. (For information, see Services and Transactions on page 13.) When transactions are container-managed, they are committed or rolled back by the J2EE application server the container that started the transaction before Process Commander received the service request. When an application participates in container-managed transactions, it must be designed so that it does not depend on the results of an operation until the transaction is completed by the container.

6 6 Distributed Transactions and PegaRULES Process Commander Transaction Boundaries The boundaries of a bean-managed transaction are different from those of a container-managed transaction. With bean-managed transactions, the scope of the transaction is from the begin call to the commit or rollback call. The transaction begins when the Commit or Rollback activity method starts that is, when Process Commander starts writing the operations from the deferred operations list to the database and ends when the commit or rollback succeeds. (For information about database operations and when commits occur, see Designing Applications that Ensure Data Integrity, which is posted on the Pega Developer Network (PDN.) With container-managed transactions, the transaction begins before Process Commander gets involved. The container begins a transaction that Process Commander participates in. When Process Commander is finished processing the request, any resulting operations are submitted to the resource manager. The commit or rollback operation occurs after the container considers all the operations from all the resource managers. If any of the participating applications marked the transaction for rollback, the transaction is rolled back. The rest of this section describes transaction boundaries in more detail because it is important to understand the differences when you are designing applications that rely on distributed transactions. Definition of Terms Figure 1 defines the terms used in this document. Term Server interaction Transaction Definition One request/response interaction between the Process Commander application and a server one HTTP communication, SOAP message and response, or Java invocation, for example. When an external system makes a service request to Process Commander, the request to the service rule and the service rule s response occur within one server interaction. When an end user interacts with Process Commander from a Web browser, a server interaction is one HTTP request/response. A set of related operations that need to be treated as one operation for the purposes of data integrity. All of the related operations must succeed, or none of them will. A transaction ends in either a commit or a rollback. A transaction occurs within the scope of one server interaction.

7 Distributed Transactions and PegaRULES Process Commander 7 Term Business transaction Distributed transaction Definition Some subset of operations that are grouped together conceptually according to the design of the application doing the work. In the context of Process Commander, a business transaction typically means the work done with/to an object during the scope of an object lock. For example, an assignment is a business transaction. The scope of a business transaction is based on human intent. The start and end points do not mark transactional boundaries they mark the scope of an object lock. (For information about object locking, see Designing Applications that Ensure Data Integrity, which is posted on the PDN) Depending on how a flow is designed, there can be several server interactions during one assignment (business transaction) because a separate server interaction occurs each time a form is refreshed. That is, a business transaction can span several server interactions. A set of operations that include more than one resource manager and that must be treated as one operation. For example, updates to more than one database in the same transaction, or, a database transaction and the sending or receiving of a JMS message in the same transaction. To use distributed transactions, Process Commander must be deployed as an enterprise application and must be using a JDBC driver with XA support. Bean-managed transaction When running in this mode, Process Commander is in charge of the (distributed) transaction. Process Commander issues the begin statement and the final commit or rollback. When deployed as an enterprise application, Process Commander is configured to run in this mode by default. Container-managed transaction When running in this mode, an external J2EE container starts and ends distributed transactions that Process Commander joins as one of the participating resources. When Process Commander finishes its work, it submits a list of operations to the resource manager(s) or it marks the transaction for rollback. If none of the resources participating in the transaction (including Process Commander) mark the transaction for rollback, the Process Commander operations are committed with the other operations within the boundaries of the transaction. If Process Commander or any of the other resources participating in the transaction marks the transaction for rollback, all the

8 8 Distributed Transactions and PegaRULES Process Commander Term Transaction attribute Deferred operations list Definition operations are rolled back. Note that only the processing managed by certain Process Commander service rule types (EJB, Java, and JMS ) can participate in container-managed transactions. A setting for enterprise beans that determine how the bean or an individual business method in the bean is enlisted in containermanaged transactions. For example, whether it needs a new transaction to be started, whether it must join an existing transaction, and so on. Typically, when the activity methods that save or delete objects are used, they don t cause the object to be saved or deleted immediately. Instead, these methods set up deferred write or deferred delete operations that are stored on a list of deferred operations. When a commit method is invoked and Process Commander is running in bean-managed mode, Process Commander completes all the tasks on the deferred operations list. When Process Commander is running in container-managed mode, commits are ignored. Figure 1. Definitions of Terms

9 Distributed Transactions and PegaRULES Process Commander 9 Web Application: Boundaries of Write Operations When Process Commander is deployed as a Web application rather than an enterprise application, it does not support distributed transactions. The following example shows an assignment that performs two deferred database write operations, each one for a different database. Figure 2 illustrates how the write operations are managed when Process Commander is deployed as a Web application. Commit Without Transaction Process Commander Web Application Assignment Assignment begins Deferred write to DB 1 Deferred write to DB 2 Commit begins Assign and commit ends Key Business transaction JDBC connection Figure 2. Transaction Boundaries When Process Commander is Deployed as a Web Application When the commit for the assignment is triggered, two separate JDBC connections are opened for two separate write operations. It is possible for one write operation to succeed and one to fail.

10 10 Distributed Transactions and PegaRULES Process Commander Enterprise Application: Boundaries of Bean-Managed Transactions Figure 3 shows the same example assignment, but this time Process Commander is deployed as an enterprise application, is using a JDBC driver with XA support, and the transaction type is bean-managed. Bean-Managed Transaction Process Commander Enterprise Application Assignment Assignment begins Deferred write to DB 1 Deferred write to DB 2 Commit begins Assign and commit ends Key Business transaction JTA transaction Figure 3. Boundaries of a Bean-Managed Transaction When the commit for the assignment is triggered, two write operations occur within the same transaction. Both write operations must succeed for either to succeed. If one fails, the other will also fail. Notice that the database transaction occurs within the scope of the business transaction (the assignment) when the transaction is bean-managed.

11 Distributed Transactions and PegaRULES Process Commander 11 Enterprise Application: Boundaries of Container-Managed Transactions In Figure 4, the example is an EJB service implementation, Process Commander is deployed as an enterprise application using a JDBC driver with XA support, and the service processing is configured to participate in container-managed transactions. The service processing results in two write operations to two different databases, as in the previous example. Container-Managed Transaction J2EE Application Server Process Commander Enterprise Application EJB Service Rule Service request delivered Deferred write to DB 1 Deferred write to DB 2 Response returned Container begins transaction Container ends transaction Key Business transaction JTA transaction Figure 4. Transactional boundaries of container-managed transactions In this case, when the EJB service rule is finished marshalling its response, the write operations are submitted to the database resource manager. The operations are committed if all parts of the distributed transaction succeed. If Process Commander throws a runtime exception or any other participant in the distributed transaction has a failure, all operations are rolled back. Notice that in this case the business occurs within the scope of the containermanaged transaction.

12 12 Distributed Transactions and PegaRULES Process Commander Container-Managed Transactions and Application Design If you determine that you need to use container-managed transactions for your Process Commander application, be sure to carefully consider all aspects of both your application architecture and your system architecture. For example, take another look at the example in Figure 4: If the service processing from this example results in the creation of a new work object, what do the boundaries of a container-managed transaction mean about the lifespan of a work object? The work object does not exist until the container completes the transaction. In such a case, both the Process Commander application and the external client application that submitted the request must be aware that the work object is transient until the container commits the object. Any subsequent actions in the business transaction described in Figure 4 that were based on the assumption that the object was created would become invalid if the transaction were rolled back by the container. You would need to design the application so that additional actions occur in a new transaction, after the application can determine whether the work object was created. To summarize: when Process Commander participates in container-managed transactions, all data operations are deferred. The Commit activity method and the Obj-Save and Obj-Delete methods with the WriteNow parameter selected cause operations to occur immediately when Process Commander is running in bean-managed mode. However, in container-managed mode, the Commit method and the WriteNow parameter are ignored. All operations are deferred. None of the operations on the deferred operations list are performed until the container completes the transaction.

13 Distributed Transactions and PegaRULES Process Commander 13 Services and Transactions The processing performed by three of the Process Commander service rule types EJB, Java, and JMS can participate in either bean-managed or container-managed transactions, as necessary. Before you decide to create services that participate in container-managed transactions, be sure to consider the design implications of such a choice. See Container-Managed Transactions and Application Design on page12. By default, transactions are bean-managed. Therefore, if you determine that a service needs to participate in container-managed transactions, you must perform additional configuration steps. EJB and Java Services When you implement an integration project with EJB or Java service rules, you use the service package to generate a JAR file. When deployed appropriately, the JAR file serves as a proxy for the service rules it makes the service rules available to an external Java-based application as though they were business methods of a session bean (EJB) or Java class (Java). In its default state, a Process Commander system is configured for beanmanaged transactions. Therefore, when you generate the proxy JAR that represents a set of service rules, the proxy expects that service transactions will be bean-managed by Process Commander: the transaction type of the generated proxy is set to Bean, and none of the methods that represent the service rules have transaction attributes defined for them. EJB Services If you want the container in which the proxy is deployed to manage the transactions of your EJB services, open the generated ejb-jar.xml file and configure transaction attributes appropriately for the methods (service rules) that the proxy represents. Change the transaction type of the proxy EJB from Bean to Container Add assembly-descriptor entries for each of the service methods (service rules) that specify the transaction attribute for the method Add environment entries in the enterprise-beans section for each of the service methods (service rules) that tell the PRService EJB which of its invokeservice() methods to use when routing a request to that service rule. The transaction attribute of a service method must be compatible with the transaction attribute of the invokeservice() method used to route a request to that service method.

14 14 Distributed Transactions and PegaRULES Process Commander For more information, see Building EJB Services, which is posted on the Pega Developers Network (PDN): Java Services If the host application in which you will use the generated JAR for a set of Process Commander Java services is running in an environment that can support distributed transactions, the host application can manage the transactions in which the Java services participate. In this case, open the PegaRULESSession.properties file from the generated proxy JAR and add environment entries to it for each of the service methods, using the following syntax: TXN_ATTR_FOR_METHOD_<name of method>=<transaction attribute> The transaction attribute specified for the service method tells the PRService EJB which of its invokeservice() methods to use when routing a request to that Java service rule. For example, to set the transaction attribute for a service method (rule) named createphonebook to required, you would insert the following entry: TXN_ATTR_FOR_METHOD_createPhonebook=REQUIRED Then, the PRService EJB uses its method invokeservicetxnreq to invoke the createphonebook service rule. For a list of the PRService methods and their transaction attributes, see the section on transaction support in Building EJB Services, which is posted on the PDN. JMS Services When Process Commander is deployed as an enterprise application, you can deploy JMS listeners as Process Commander application components message-driven beans managed by the application server. The MDB that represents a listener routes messages to the JMS service rule. When configuring the data object that represents the JMS MDB listener the Data-Admin-Connect-JMSMDBListener instance determine whether you want messages to be redelivered if something goes wrong while they are being delivered or processed. To do so, select the container-managed transaction field on the Listener Properties tab of the object. When the container-managed transaction field is selected, the MDB starts a transaction when it gets a message from the queue and the service processing participates in that transaction. If there are problems either with the message

15 Distributed Transactions and PegaRULES Process Commander 15 delivery or with the service processing, the message will be delivered again so the service can attempt to process it again. When the container-managed transaction field is cleared, message delivery and service processing occur outside of a transaction. If the service processing fails, the message is not redelivered. For more information, see the Application Developer Help and the PDN article PRKB How to: Deploy a JMS Listener as a Message-Driven Bean (MDB).

16 16 Distributed Transactions and PegaRULES Process Commander Connectors and Transactions Whether connectors can participate in container-managed transactions depends on their requestor context: Typically, connectors run in the requestor context of a user rather than as a background process. Users create a work object and when the work object reaches the Integrator task that invokes the connector, the connector runs in the user s requestor context. When the connector runs in a human user s requestor context, transactions are bean-managed by Process Commander. A service runs in the background, in a new requestor session. If the service processing for an EJB, Java, or JMS service invokes a connector, the connector runs in the service s requestor context. Whether the connector participates in a container-managed transaction depends on the transactional state of the service. Connectors Running in User s Requestor Context When a connector runs in a user s requestor context, transactions are beanmanaged. In this case, the information that a connector brings back from an external source is written to the Process Commander database when Process Commander issues the commit command. However, the external processing invoked from the connector cannot participate in the Process Commander transaction because the boundaries of Process Commander s bean-managed transactions do not extend outside of Process Commander. When running in bean-managed mode, Process Commander does not start a transaction until a commit or rollback operation is started. Therefore, when the connector invokes the external system, there is no transaction open for it to participate in. Whatever processing and database writes occur in the external system occur separately from any processing in Process Commander and do not depend on a commit operation from Process Commander. SQL Connectors, the External Data Table Feature, and Bean-Managed Transactions Although the database write operations performed by SQL connectors cannot be included in Process Commander bean-managed transactions, the operations performed when using the external data table rules feature are included. Starting in Process Commander version 5.1, the Create External Data Table Rules wizard (External Table wizard) creates rules and data objects that implement in Process Commander the data model of an external database table. With these rules and data objects in place, you can use the Obj-Open, Obj-Openby-Handle, Obj-Save and Obj-Delete activity methods to interact with the data in

17 Distributed Transactions and PegaRULES Process Commander 17 an external table in the same way that you use them to read and write data to the Process Commander database. Rather than using SQL connector rules for simple read statements, you can use the Obj-Open activity method. Instead of using a SQL connector for a simple write or delete operations, you can use the Obj-Save or Obj-Delete activity methods to put those operations on the deferred operations list. Then, when the final Commit activity method is invoked, all the deferred writes to both the Process Commander database and the external database occur in the same bean-managed transaction. For more information about the external data table wizard, see the Application Developer Help. Running Connectors in Parallel When connectors run in parallel, a new requestor is created for each connector invocation. Because they are separate requestors, they cannot participate in distributed transactions they initiate separate transactions. If you want the results from multiple connector calls to participate in the same distributed transaction, do not run them in parallel. JMS Connectors and Container-Managed Transactions As mentioned, the only way for a connector to run in a container-managed transaction is if it is invoked by the processing of a service that is participating in a container-managed transaction. If you plan to use a JMS connector as part of a container-managed transaction, remember that the JMS message is not actually delivered to the JMS service provider until the container managing the transaction issues the commit. That is, the message is not delivered until the container-managed transaction is completed. Therefore, you cannot configure a JMS connector to wait for a response if it is running in a container-managed transaction. If you do so, then at runtime the session will hang until Process Commander times out and ends the server interaction.