About Transaction Objects

About creating a query in a Transaction

The Oracle OLAP API is transactional. Each step in creating a query occurs in the context of a Transaction. One of the first actions of an OLAP API application is to create a TransactionProvider. The TransactionProvider provides Transaction objects to the application.

The TransactionProvider ensures the following:

• A Transaction is isolated from other Transaction objects. Operations performed in a Transaction are not visible in, and do not affect, other Transaction objects.

• If an operation in a Transaction fails, its effects are undone (the Transaction is rolled back).

• The effects of a completed Transaction persist.

When you create a derived Source by calling a method on another Source, that Source is created in the context of the current Transaction. The Source is active in the Transaction in which you create it or in a child Transaction of that Transaction.

You get or set the current Transaction, or begin a child Transaction, by calling methods on a TransactionProvider. In a child Transaction you can change the state of a Template that you created in the parent Transaction. By displaying the data specified by the Source produced by the Template in the parent Transaction and also displaying the data specified by the Source produced by the Template in the child Transaction, you can provide the end user of your application with the means of performing what-if analysis.

Types of Transaction objects

The OLAP API has the following two types of Transaction objects:

• A read Transaction. Initially, the current Transaction is a read Transaction. A read Transaction is required for creating a Cursor to fetch data from an OLAP service. For more information on Cursor objects, see Chapter 9.

• A write Transaction. A write Transaction is required for creating a derived Source or for changing the state of a Template. For more information on creating a derived Source, see Chapter 5. For information on Template objects, see Chapter 11.

In the initial read Transaction, if you create a derived Source or if you change the state of a Template object, then a child write Transaction is automatically generated. That child Transaction becomes the current Transaction.

If you then create another derived Source or change the Template state again, that operation occurs in the same write Transaction. You can create any number of derived Source objects, or make any number of Template state changes, in that same write Transaction. You can use those Source objects, or the Source produced by the Template, to define a complex query.

Before you can create a Cursor to fetch the result set specified by a derived Source, you must move the Source from the child write Transaction into the parent read Transaction. To do so, you prepare and commit the Transaction.

Preparing and committing a Transaction

To move a Source that you created in a child Transaction into the parent read Transaction, call the prepareCurrentTransaction and commitCurrentTransaction methods on the TransactionProvider. When you commit a child write Transaction, a Source you created in the child Transaction moves into the parent read Transaction. The child Transaction disappears and the parent Transaction becomes the current Transaction. The Source is active in the current read Transaction and you can therefore create a Cursor for it.

The following figure illustrates the process of moving a Source created in a child write Transaction into its parent read Transaction. The figure has a box that represents a read Transaction, t1, in which an application gets MdmDimension and MdmMeasure objects and gets primary Source objects from them. The application then creates derived Source objects by making selections on the primary Source objects from t1.

When the application calls the selectValues method on products, a primary Source, the write Transaction t2 is created, which is represented by a box below t1. The derived Source objects prodSel and timeSel are created in t2. Also in t2 the application joins the derived Source objects to the unitCost primary Source to create the unitCostForSelections derived Source. The application then calls the prepareCurrentTransaction and commitCurrentTransaction methods on the TransactionProvider, which prepares the t2 Transaction and commits it. Committing t2 makes the new Source objects that were created in t2 visible and active in t1, the parent read Transaction. The application can then create a Cursor for unitCostForSelections. The t2 Transaction is no longer active and it disappears.

About Transaction and Template objects

Getting and setting the current Transaction, beginning a child Transaction, and rolling back a Transaction are operations that you use to allow an end user to make different selections starting from a given state of a dynamic query. This creating of alternatives based on an initial state is known as what-if analysis.

To present the end user with alternatives based on the same initial query, you do the following:

1. Create a Template in a parent Transaction and set the initial state for the Template.

2. Get the Source produced by the Template, create a Cursor to retrieve the result set, get the values from the Cursor, and then display the results to the end user.

3. Begin a child Transaction and modify the state of the Template.

4. Get the Source produced by the Template in the child Transaction, create a Cursor, get the values, and display them.

You can then replace the first Template state with the second one or discard the second one and retain the first.

Beginning a child Transaction

To begin a child Transaction, call the beginSubtransaction method on the TransactionProvider you are using. Initially, the child Transaction is a read Transaction. If you then change the state of a Template, a child write Transaction begins automatically. The write Transaction is a child of the child read Transaction.

To get the data specified by the Source produced by the Template, you prepare and commit the write Transaction into its parent read Transaction. You can then create a Cursor to fetch the data. The changed state of the Template is not visible in the original parent. The changed state does not become visible in the parent until you prepare and commit the child read Transaction into the parent read Transaction.

The following figure illustrates beginning a child Transaction. In the figure, a box represents t1, which is a read Transaction in which a TopBottomTemplate object exists. TopBottomTemplate is an example of a Template that is described in Chapter 11.

A second box represents t2, which is a write Transaction begun when the state of the Template changes to specify selecting the top ten values, which results from the following operations.

topNBottom.setTopBottomType(TOP);
topNBottom.setN(10);

In t2, the prepareCurrentTransaction and commitCurrentTransaction methods are called on the TransactionProvider. The changes to the state of the TopBottomTemplate become active in t1 and t2 disappears. The getSource method on the DynamicDefinition created by the TopBottomTemplate is called. A Cursor for the Source is created, which retrieves the data from the OLAP service. The values from the Cursor are displayed.

A third box in the figure represents the read Transaction t3, which is a child of t1 that results from the following operation.

t1.beginSubtransaction();

A fourth box represents t4, which is a write Transaction that begins as a result of the following changes to the state of the TopBottomTemplate.

topNBottom.setTopBottomType(BOTTOM);
topNBottom.setN(15);

The Source produced by the TopBottomTemplate now represents the selection of the bottom fifteen values. In t4, the prepareCurrentTransaction and commitCurrentTransaction methods are called on the TransactionProvider. The changes to the state of the TopBottomTemplate made in t4 become active in t3 and t4 disappears.

In t3, the getSource method is called on the DynamicDefinition, a Cursor for the Source is created, and values from the Cursor are displayed. The prepareCurrentTransaction and commitCurrentTransaction methods are called. The result is that the state of the TopBottomTemplate from t3, representing the bottom fifteen values, moves into t1 and replaces the state of the TopBottomTemplate that represented the top ten values. The t3 Transaction disappears and t1 is again the current Transaction.

In the following figure, tp is the TransactionProvider.

After beginning a child read Transaction, you can begin a child read Transaction of that child, or a grandchild of the initial parent Transaction. For an example of creating child and grandchild Transaction objects, see "Example: Using child Transaction objects".

About rolling back a Transaction

You roll back, or undo, a Transaction by calling the rollbackCurrentTransaction method on the TransactionProvider you are using. Rolling back a Transaction discards any changes that you made during that Transaction and makes the Transaction disappear.

Before rolling back a Transaction, you must close any CursorManager objects you created in that Transaction. After rolling back a Transaction, any Source objects that you created or Template state changes that you made in the Transaction are no longer valid. Any Cursor objects you created for those Source objects are also invalid.

Once you roll back a Transaction, you cannot prepare and commit that Transaction. Likewise, once you commit a Transaction, you cannot roll it back.

Example: Rolling back a Transaction

The following example creates a TopBottomTemplate and sets its state. The example begins a child Transaction that sets a different state for the TopBottomTemplate and then rolls back the child Transaction. The TransactionProvider is tp.

/*
 * The current Transaction is a read Transaction, t1.
 * Create a TopBottomTemplate using product as the base
 * and dp as the DataProvider.
 */
TopBottomTemplate topNBottom = new TopBottomTemplate(product, dp);

/*
 * Changing the state of a Template requires a write Transaction, so a
 * write child Transaction, t2, is automatically started.
 */
topNBottom.setTopBottomType(TopBottomTemplate.TOP_BOTTOM_TYPE_TOP);
topNBottom.setN(10);
topNBottom.setCriterion(singleSelections.getSource());

// Prepare and commit the Transaction t2.
tp.prepareCurrentTransaction();
tp.commitCurrentTransaction();           //t2 disappears

/*
 * The current Transaction is now t1.
 * Create a Cursor and display the results (operations not shown).
 */

// Start a child Transaction, t3. It is a read Transaction.
tp.beginSubtransaction();          // t3 is the current Transaction

/*
 * Change the state of topNBottom. Changing the state requires a
 * write Transaction so Transaction t4 starts automatically,
 */
topNBottom.setTopBottomType(TopBottomTemplate.TOP_BOTTOM_TYPE_BOTTOM);
topNBottom.setN(15);

// Prepare and commit the Transaction.
tp.prepareCurrentTransaction();
tp.commitCurrentTransaction();           // t4 disappears

/*
 * Create a Cursor and display the results. // t3 is the current Transaction
 * Close the CursorManager for the Cursor created in t3.
 * Undo t3, which discards the state of topNBottom that was set in t4.
 */
tp.rollbackCurrentTransaction()         // t3 disappears

/* Transaction t1 is now the current Transaction and the state of
 * topNBottom is the one defined in t2.
 */

Getting and setting the current Transaction

You get the current Transaction by calling the getCurrentTransaction method on the TransactionProvider you are using, as in the following example.

Transaction t1 = getCurrentTransaction();

To make a previously saved Transaction the current Transaction, you call the setCurrentTransaction method on the TransactionProvider, as in the following example.

setCurrentTransaction(t1);