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.

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.

To demonstrate how to use Transaction objects to modify dynamic queries, Example 7-2 builds on the TopBottomTest application defined in Chapter 10. 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 code from Example 7-2.

Example 7-2 Using Child Transaction Objects

    // 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