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 create root Transaction objects, to get or set the current Transaction, and to commit or roll back the changes you makes during a Transaction. You get a TransactionProvider by calling the getTransactionProvider method of the DataProvider for the session.

A TransactionProvider ensures the following:

• A transaction is isolated from other transactions.
• If a transaction fails, Oracle OLAP discards (rolls back) the changes made in the transaction.
• The effects of a completed transaction persist.

You create or modify MdmObject objects and derived Source objects in the context of a Transaction. The initial Transaction in a session is a root Transaction. You can explicitly create a root Transaction with the createRootTransaction method. If you have not explicitly created one, then Oracle OLAP automatically creates a root Transaction the first time that you create or modify an MdmObject or a derived Source. To make permanent the changes to an MdmObject, you must commit the root Transaction in which you made the changes.

A single-user application does not need to explicitly create a root Transaction. The ability to create multiple root Transaction objects is provided for use by multithreaded, middle-tier applications. If your application uses multiple root Transaction objects, the changes that the application makes in one root Transaction can be overwritten by changes the application makes in another root Transaction. The changes that occur in the last root Transaction that the application commits are the changes that persist.

With the beginSubtransaction method, you can create a child Transaction of a root Transaction or of another child Transaction. Only one Transaction is the current Transaction at any one time. With the methods of a TransactionProvider, you can get the current Transaction or set a previously saved Transaction as the current Transaction.

When you create a query, you create a derived Source in the context of the current Transaction. Changing the state of a Template also occurs in a transaction context. The only Source that you can modify is one generated by a Template. A Source generated by a Template has a DynamicDefinition as a proxy for the ImmutableDefinition that is associated with the Source.

A derived Source or state change is active, or valid, in the Transaction in which in which you created or modified it, or in a child of that Transaction. Any changes you make in the child Transaction do not take effect in the parent Transaction until the you commit the child Transaction by calling the commitCurrentTransaction method of the TransactionProvider.

A derived Source that you create in a child Transaction is visible in that Transaction and in subtransactions of that child Transaction but it is not visible in other children of the same parent until you commit the child Transaction into to the parent.

When you call 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 you do not want to commit a child Transaction into the parent Transaction, then you 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 parent 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();
 // Commit the child Transaction.
 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() Commits to the OLAP server changes that a client application has made in a 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 as of the 11g Release 1 (11.1) of the Oracle OLAP Java API.
void	rollbackCurrentTransaction() Rolls back, or undoes, any OLAP API operations that you 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 as of the 11g Release 1 (11.1) of the Oracle OLAP Java API.

Prepares the current Transaction for committing.

Throws:

NotCommittableException

TransactionInactiveException

ActiveSubtransactionsException

commitCurrentTransaction

void commitCurrentTransaction()
                              throws CommitException,
                                     TransactionInactiveException,
                                     ActiveSubtransactionsException

Commits to the OLAP server changes that a client application has made in a Transaction. For a root Transaction, this method commits new or modified MdmObject objects to the Oracle Database instance. Top-level metadata objects, such a MdmCube and MdmPrimaryDimension objects, that you created in the Transaction become permanent objects and appear in the data dictionary.

For Source objects, this method moves the state of a child Transaction into the parent Transaction. You must commit the Transaction in which you created the derived Source for a query before you can create a Cursor to retrieve the data specified by the query.

Throws:

CommitException

TransactionInactiveException

ActiveSubtransactionsException

rollbackCurrentTransaction

void rollbackCurrentTransaction()
                                throws TransactionInactiveException,
                                       ActiveSubtransactionsException

Rolls back, or undoes, any OLAP API operations that you performed in the current Transaction. The TransactionProvider discards the operations you 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 is 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 root Transaction for the UserSession.