Modules | Classes
Transaction Manager

Modules

 Undo Redo
 

Classes

struct  TxnMonitor
 Interface to be implemented to monitor changes to elements. More...
 
struct  ITxn
 The interface to write changes in the context of a transaction to elements, XAttributes, and models. More...
 
struct  ITxnManager
 This interface provides a transaction mechanism for handling changes to persistent elements and models. More...
 

Detailed Description

Transaction Manager

The Transaction Manager enables you to save changes, journal transactionable changes during a session, and to organize changes into units called transactions.

Making and Saving Changes

Use the Transaction Manager in order to add, save changes to, or to delete elements, XAttributes or models.

Note that the Transaction Manager does not write anything to disk. See DgnFile::ProcessChanges.

Here are a few common patterns:

To add an element:

  1. Create an EditElementHandle. Initially, the handle is invalid.
  2. Call a static handler method to define the element. For example, LineHandler::CreateLineElement
  3. Call EditElementHandle::AddToModel to add the new element to a model.

The element is now persisent in the specified model.

To change an element:

  1. Obtain an ElementRefP that refers to the persistent element in the model.
  2. Create an EditElementHandle that can be used to access the element's data.
  3. Call handler methods such as Handler::ApplyTransform to modify the element's data.
  4. Call EditElementHandle::ReplaceInModel to update the persistent element's data to reflect the change.

Note that you could make multiple changes to the EditElementHandle before writing to the model.

To delete an element:

  1. Obtain an ElementRefP that refers to the persistent element in the model.
  2. Create an EditElementHandle from the ElementRefP and then call EditElementHandle::DeleteFromModel to delete the element.

To add an XAttribute to an element:

  1. Obtain an ElementRefP that refers to the persistent element in the model.
  2. Define the XAttribute's data and decide what XAttributeHandlerId to use.
  3. Call ITxn::AddXAttribute to add the XAttribute to the persistent element in the model.

The XAttribute is now persistent in the element's model.

To modify an XAttribute on an element:

  1. Obtain an ElementRefP that refers to the persistent element in the model.
  2. Use XAttributeHandle to locate the XAttribute on the element.
  3. Decide how you want to modify the XAttribute's data.
  4. Call ITxn::ModifyXAttributeData to update the persistent XAttribute data in the model.

Or, you could call ITxn::ReplaceXAttributeData to update the persistent XAttribute to store completely different data.

To delete an XAttribute:

  1. Obtain an ElementRefP that refers to the persistent element in the model.
  2. Use XAttributeHandle to locate the XAttribute on the element.
  3. Call ITxn::DeleteXAttribute to remove the XAttribute from the persistent element in the model.

Transactions

A transaction is defined as a set of changes that are treated as a unit. All changes and deletions are made as part of a transaction. Most transactions are undoable and can be reversed or reinstated as a unit. Undoable transactions support TxnMonitor listeners.

The Transaction Manager implements the ITxnManager interface. This interface has methods to query the current transaction, to register TxnMonitors, and to reverse, cancel, or reinstate transactions.

All changes are made in the context of the current transaction. There is always a current transaction running. You don't have to start or create one. ITxnManager::GetCurrentTxn returns the current transaction.

ITxnManager::CloseCurrentTxn defines a boundary that ends the current transaction and starts a new one. Setting a transaction boundary validates the preceeding changes (ITxnManager::ValidateCurrentTxn). Validating an undoable transaction also notifies TxnMonitor listeners. For an undoable transaction, setting a transaction boundary defines an undo point.

The current transaction implements the ITxn interface. The ITxn inteface provides methods to write changes to elements, XAttributes, and models. The EditElementHandle methods to add, replace, and delete elements turn around and call the appropriate methods on the current transaction.

Example

Here is a simple example of using the transaction manager to add two elements to a model and then close the transaction.

...
EditElementHandle eh1, eh2;
LineHandler::CreateLineElement (eh1, ...., model1);
LineHandler::CreateLineElement (eh2, ...., model1);
ITxnManager::CloseCurrentTxn(true); // Call TxnMonitors and set transaction boundary.

These two adds can now be reversed by calling ITxnManager::ReverseSingleTxn.

Note that ITxnManager::CloseCurrentTxn does not write anything to disk. See DgnFile::ProcessChanges.


Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.