About TransactionProvider Objects

Using TransactionProvider objects

In the Oracle OLAP API, the TransactionProvider interface is implemented by the ExpressTransactionProvider concrete class. Before you create a DataProvider, you must create a new instance of an ExpressTransactionProvider. You then pass that TransactionProvider to the DataProvider constructor. The TransactionProvider provides Transaction objects to your application.

A TransactionProvider has the following methods:

Method	Return Value
beginSubtransaction	A Transaction that is a child Transaction of the current Transaction.
commitCurrentTransaction	Void. This method moves any changes made in the current child Transaction into the parent Transaction.
getCurrentTransaction	The current Transaction. Use this method to save the current Transaction. You can then set a different saved Transaction as the current Transaction.
prepareCurrentTransaction	Void. This method prepares the current child Transaction to be committed into the parent Transaction.
rollbackCurrentTransaction	Void. This method discards the current child Transaction, in effect rolling back any OLAP API operations an application performed in the context of the child Transaction. The parent Transaction becomes the current Transaction.
setCurrentTransaction	Void. This method sets a Transaction as the current Transaction.

As described in "Preparing and committing a Transaction", you use the prepareCurrentTransaction and commitCurrentTransaction methods to make a derived Source that you created in a child write Transaction visible in the parent read Transaction. You can then create a Cursor for that Source.

If you are using Template objects in your application, you might also use the other methods on TransactionProvider to do the following:

• Begin a child Transaction.

• Get the current Transaction so you can save it.

• Set the current Transaction to a previously saved one.

• Rollback, or undo, the current Transaction, which discards any changes made in the Transaction. Once a Transaction has been rolled back, it is invalid and cannot be committed. Once a Transaction has been committed, it cannot be rolled back. If you created a Cursor for a Source in a Transaction, you must close the CursorManager before rolling back the Transaction.

Example: Using child Transaction objects

To demonstrate how to use Transaction objects to modify dynamic queries, the following example builds on the TopBottomTest application defined in Chapter 11. To help track the Transaction objects, the example saves the different Transaction objects with calls to the getCurrentTransaction method.

Replace the last five lines of the code from the TopBottomTest class with the following.

    /*
     * The parent Transaction is the current Transaction at this point.
     * Save the parent read Transaction as parentT1.
     */
    Transaction parentT1 = tp.getCurrentTransaction();

    // Begin a child Transaction of parentT1.
    tp.beginSubtransaction();  // This is a read Transaction.

    // Save the child read Transaction as childT2.
    Transaction childT2 = tp.getCurrentTransaction();

    /*
     * Change the state of the TopBottomTemplate. This starts a
     * write Transaction, a child of the read Transaction childT2.
     */
    topNBottom.setN(15);
    topNBottom.setTopBottomType(TopBottomTemplate.TOP_BOTTOM_TYPE_BOTTOM);

    // Save the child write Transaction as writeT3.
    Transaction writeT3 = tp.getCurrentTransaction();

    // Prepare and commit the write Transaction writeT3.
    try{
      context.getTransactionProvider().prepareCurrentTransaction();
    }
    catch(NotCommittableException e){
     System.out.println("Caught exception " + e + ".");
    }
    context.getTransactionProvider().commitCurrentTransaction();

    /* 
     * The commit moves the changes made in writeT3 into its parent,
     * the read Transaction childT2. The writeT3 Transaction
     * disappears. The current Transaction is now childT2
     * again but the state of the TopBottomTemplate has changed.
     *
     * Create a Cursor and display the results of the changes to the 
     * TopBottomTemplate that are visible in childT2.
     */
    createCursor(topNBottom.getSource());

    // Begin a grandchild Transaction of the initial parent.
    tp.beginSubtransaction();  // This is a read Transaction.

    // Save the grandchild read Transaction as grandchildT4.
    Transaction grandchildT4 = tp.getCurrentTransaction();

    /*
     * Change the state of the TopBottomTemplate. This starts another
     * write Transaction, a child of grandchildT4.
     */
    topNBottom.setTopBottomType(TopBottomTemplate.TOP_BOTTOM_TYPE_TOP);

    // Save the write Transaction as writeT5.
    Transaction writeT5 = tp.getCurrentTransaction();

    // Prepare and commit writeT5.
    try{
      context.getTransactionProvider().prepareCurrentTransaction();
    }
    catch(NotCommittableException e){
      System.out.println("Caught exception " + e + ".");
    }
    context.getTransactionProvider().commitCurrentTransaction();

    /* 
     * Transaction grandchildT4 is now the current Transaction and the
     * changes made to the TopBottomTemplate state are visible.
     */

    // Create a Cursor and display the results visible in grandchildT4.
    createCursor(topNBottom.getSource());

    // Commit the grandchild into the child.
    try{
      context.getTransactionProvider().prepareCurrentTransaction();
    }
    catch(NotCommittableException e){
      System.out.println("Caught exception " + e + ".");
    }
    context.getTransactionProvider().commitCurrentTransaction();

    /* 
     * Transaction childT2 is now the current Transaction.
     * Instead of preparing and committing the grandchild Transaction,
     * you could rollback the Transaction, as in the following
     * method call:
     * rollbackCurrentTransaction();
     * If you roll back the grandchild Transaction, then the changes
     * you made to the TopBottomTemplate state in the grandchild 
     * are discarded and childT2 is the current Transaction.
     */

    // Commit the child into the parent.
    try{
      context.getTransactionProvider().prepareCurrentTransaction();
    }
    catch(NotCommittableException e){
      System.out.println("Caught exception " + e + ".");
    }
    context.getTransactionProvider().commitCurrentTransaction();

    /* 
     * Transaction parentT1 is now the current Transaction. Again,
     * you could roll back the childT2 Transaction instead of
     * preparing and committing it. If you did so, then the changes
     * you made in childT2 are discarded. The current Transaction
     * would be parentT1, which would have the original state of
     * the TopBottomTemplate, without any of the changes made in 
     * the grandchild or the child transactions.
     */

    }  // end of main() method
  }  // end of TopBottomTest class