Skip navigation links

oracle.olapi.transaction
Interface TransactionProvider

public interface TransactionProvider

An interface that defines an OLAP transaction provider. The Oracle OLAP Java API implementation of this interface provides methods to get Transaction objects and to commit or roll back the changes an application makes during a Transaction. An application gets a TransactionProvider by calling the getTransactionProvider method of the DataProvider for the session.

A transaction is represented by an instance of the Oracle OLAP Java API implementation of the Transaction interface. An application does not directly create new Transaction objects. Instead, a TransactionProvider supplies them as they are needed. Only one Transaction is the current Transaction at any one time. With the methods of a TransactionProvider, an application can get the current Transaction or set a previously saved Transaction as the current Transaction.

Creating a derived Source or changing the state of a Template occurs in a transaction context. A TransactionProvider ensures the following:

• A transaction is isolated from other transactions.
• If a transaction fails, its effects are undone (rolled back).
• The effects of a completed transaction persist.

An application creates a derived Source or changes the state of a Template in the current Transaction. A Source or state change is active, or valid, in the Transaction in which in which it was created or modified, or in a child of that Transaction. Any changes that occur in the child Transaction do not take effect in the parent Transaction until the application commits the Transaction by calling the commitCurrentTransaction method of the TransactionProvider. The only Source that can be modified is one produced by a Template and which therefore has a DynamicDefinition as a proxy for the ImmutableDefinition that is associated with the Source.

When the application calls the commitCurrentTransaction method, the state of the child Transaction moves up into the parent Transaction. The child Transaction disappears. The updated Transaction is still the parent Transaction for any other child Transaction of the original parent Transaction. If the application does not want to commit a child Transaction into the parent Transaction, then it can call the rollbackCurrentTransaction method. The TransactionProvider then discards any changes made in the child Transaction and makes the parent Transaction the current Transaction.

The following example illustrates a rollback.

 // dp is the DataProvider for the session.
 TransactionProvider transactionProvider = dp.getTransactionProvider();
 // Save the top-level Transaction.
 Transaction parent = transactionProvider.getCurrentTransaction();
 // Begin a child Transaction.
 transactionProvider.beginSubtransaction();

 // The createCube() method returns a Source that was produced by a Template.
 // That Source represents the joining of a measure and some dimensions into a cube.
 // The context input parameter is an object that supplies a MetadataProvider and a
 // DataProvider for the cube Template to use to get primary Source objects and
 // derived Source objects.

 // Create a cube in the child Transaction.
 Source cube = createCube(context);
 // Save the child Transaction.
 Transaction child = transactionProvider.getCurrentTransaction();
 // Begin a grandchild Transaction.
 transactionProvider.beginSubtransaction();
 // Add another dimension as an edge.
 cube.addEdge(edge);
 // Discard the grandchild Transaction that added the edge.
 transactionProvider.rollbackCurrentTransaction();
 // Prepare and commit the child Transaction.
 transactionProvider.prepareCurrentTransaction();
 transactionProvider.commitCurrentTransaction();
 // The cube now exists in the parent Transaction.

See Also:

Cursor, Source, Template

Method Summary

Transaction	beginSubtransaction() Begins a child Transaction of the current Transaction.
void	commitCurrentTransaction() Moves the state of a child Transaction into the parent Transaction.
Transaction	createRootTransaction(UserSession session) Creates a new root Transaction for the specified UserSession.
Transaction	getCurrentTransaction() Gets the current Transaction.
void	prepareCurrentTransaction() Calling this method before calling commitCurrentTransaction is no longer necessary.
void	rollbackCurrentTransaction() Rolls back, or undoes, any OLAP API operations the application performed in the current Transaction.
void	setCurrentTransaction(Transaction transaction) Specifies a Transaction as the current Transaction.

Method Detail

getCurrentTransaction

Transaction getCurrentTransaction()

Gets the current Transaction.

Returns:

The current Transaction.

setCurrentTransaction

void setCurrentTransaction(Transaction transaction)

Specifies a Transaction as the current Transaction.

Parameters:

transaction - A Transaction object to specify as the current Transaction.

prepareCurrentTransaction

void prepareCurrentTransaction()
                               throws NotCommittableException,
                                      TransactionInactiveException,
                                      ActiveSubtransactionsException

Calling this method before calling commitCurrentTransaction is no longer necessary.

Prepares the current Transaction for committing.

Throws:

NotCommittableException

TransactionInactiveException

ActiveSubtransactionsException

commitCurrentTransaction

void commitCurrentTransaction()
                              throws CommitException,
                                     TransactionInactiveException,
                                     ActiveSubtransactionsException

Moves the state of a child Transaction into the parent Transaction. Before calling commitCurrentTransaction, an application must call prepareCurrentTransaction.

Throws:

CommitException

TransactionInactiveException

ActiveSubtransactionsException

rollbackCurrentTransaction

void rollbackCurrentTransaction()
                                throws TransactionInactiveException,
                                       ActiveSubtransactionsException

Rolls back, or undoes, any OLAP API operations the application performed in the current Transaction. The TransactionProvider discards the operations the application performed in the child Transaction and makes the parent Transaction the current Transaction.

Throws:

TransactionInactiveException

ActiveSubtransactionsException

beginSubtransaction

Transaction beginSubtransaction()
                                throws TransactionInactiveException

Begins a child Transaction of the current Transaction. The child Transaction becomes the current Transaction.

Returns:

A Transaction object that represents the current Transaction.

Throws:

TransactionInactiveException

createRootTransaction

Transaction createRootTransaction(UserSession session)

Creates a new root Transaction for the specified UserSession.

Parameters:

session - The UserSession for which to create a new root Transaction.

Returns:

A Transaction that is the root Transaction for the UserSession.

Skip navigation links