Transactions and the Adept Object Database

In the normal course of events you may read in some data, mark it for update, change it then commit it. The Adept Object Database system will queue it for writing to the database as soon as possible - typically in the next tenth of a second or so.

Now, it's far easier to design software by compartmentalising functionality. This not only means keeping disparate functions in different places, but also limiting how much they need know about each other.

Let's take an example form that the user enters for an application. It could include address, contact and application specific details. The processing code would look something like:

user = createUser( form.userName);
addAddress( user, form.addressFields);
addContact( user, form.email);
addApplication( user, form.applicationDetails);

 

Now, what happens if the application includes a date of birth and that shows that the applicant is under-age. Sure, we'll output and tell the applicant, but what to do with the data? We now have user, address and contact details that are of no use without an application. We could write a delete routine to remove the information already added. This wouldn't be a bad solution - particularly if you needed a delete routine anyway for maintenance. It would be better, however, if the inconsistent or unnecessary data never saw the database. This is what transactions are for.

try
  {
    Transaction.start();
    user = createUser( form.userName);
    addAddress( user, form.addressFields);
    addContact( user, form.email);
    addApplication( user, form.applicationDetails);
 Transaction.end();
  }
catch (Throwable throwable)
  { Transaction.abort(); }

 

Note that once a transaction starts, it must be completed or aborted - otherwise the persistence is never achieved.

Nesting Transactions

The Adept Transaction system supports full transaction nesting. On every start() a new nesting level is created. An abort() will drop all items updated since the last start() while an end() will add them to the next higher transaction group. An end() for the highest transaction group will have all items within the transaction queued for a commit. A global endAll() or abortAll() will process all nesting levels at once.

The Adept Development System

If you are working inside of the Adept Development System the connection manager does this all for you. It maintains a transaction across each conversation. You only need to call transaction management explicitly if you have a group of transactions that need to be controlled - but not effect other outer transactions if they need to be aborted. The end of the conversation can use endAll() or abortAll() to clear the nested transaction stack if needed.

In short, ignore transaction management as it's all done for you behind the scenes. Throw something if you want all database writes to be rolled back.