[okfn-help] vdm with pending support

[Martijn Faassen]

Hi there,

I managed to create some modifications to vdm that include support for
"pending" data. I'll describe briefly what I've done.

There is one primary use case:

Not all data in the database is considered "published", some data is
pending. It should be possible to extract a snapshot of the database
for a particular revision that includes only the published data. It
should also be possible to use the database and makes changes to it
that are not published but pending.

I've not implemented the "extract snapshot" functionality itself yet,
but I believe it's not difficult to implement now. I have focused on
adding support for creating pending modifications.

First, you need to enable the pending support, by setting it on the session:

session.pending_enabled = True

If you don't do this, vdm will continue to function as before.

If you do enable pending support:

* when you insert a new item to the database, its state will be set to
PENDING_INSERT automatically.

* when you update an item in the database (and you don't explicitly
modify its state yourself), its state will be set to PENDING_UPDATE

* you can also manually set the state to PENDING_DELETE

There are a few new methods available on the StatefulObjectMixin, in particular:

* is_pending: check whether an item is pending

* publish: publish a pending item to make it an ACTIVE item

* revert: throw away pending changes for item (that means throwing
away the item in case of PENDING_INSERT)

* get_nonpending: get the last non-pending historical revision for an
item (in case of PENDING_UPDATE)

publish and revert are aware of relations. This means, by the way,
that you need to express as relations those foreign key relations your
database has, preferably with backrefs in place, otherwise you risk
creating inconsistent state.

Some of the rules:

if you publish PENDING_INSERT, it will automatically publish any
MANYTOONE relation that's also PENDING_INSERT.

You can do publish PENDING_INSERT with the cascade argument set to
True, in which case it will also publish any related items through a
ONETOMANY relation.

If you publish PENDING_UPDATE, it will simply make it ACTIVE. If you
set cascade, any related objects through ONETOMANY will also be
published.

If you publish PENDING_DELETE, it will remove the item. It will also
remove all items related to it through a ONETOMANY relation. Those
items *have* to be PENDING_DELETE as well. Again, with cascade set any
one to many related items will be published.

If you revert a PENDING_INSERT, it will be removed from the database.
Any related items (through one to many) will also be removed, and they
all have to be set to PENDING_INSERT.

If you revert a PENDING_UPDATE, the last non-pending version's data
will be written back to this item. (you might need to re-query the
objects to see the result, underlying relations might have changed)

If you revert a PENDING_DELETE, the objects will return to ACTIVE state.

Again reversion can be done with 'cascade' set to True in the
argument, so that all underling one to many objects will also be
recursively reverted.

And that's about it.

The code is here in bitbucket:

http://bitbucket.org/faassen/vdm-pending/

(this also contains my MySQL modifications, plus the module cleanup)

Regards,

Martijn