[Exist-open] Versioning extension (WAS: Re: Is eXist the right tool for me?)

[Wolfgang <wol...@ex...>]

> Yes this is a fairly recent addition, I am not sure it is well
> documented yet. If you would like to try it out though I am sure we
> could help you get going with it...

Yes, the versioning extension has no documentation yet. But it is easy 
to set up:

* edit conf.xml and enable the VersioningFilter by removing the comment 
around the line:

<custom-filter class="org.exist.versioning.VersioningFilter"/>

* the core component of the extension is a trigger, which has to be 
configured for a collection in its collection.xconf. There's a sample 
collection.xconf in extensions/versioning. For testing, just store this 
into the collection /db/system/config/db. This will activate versioning 
for the entire db.

* browse to the admin web application 
(http://localhost:8080/exist/admin/). Once logged in, select "Browse 
Collections" from the menu and navigate into an arbitrary collection. 
You should see a (still empty) column "Revision" to the right of each 
XML document.

If the triggers are set up properly and you modify one of the documents 
(e.g. via the Java client), a revision number should appear in the 
"Revision" column. You can click on the number to see all revisions of 
the document. Within the revisions page, you can view the diff (as 
stored in the /db/system/versions collection) listing the changes 
between the revision and the version before it. You can restore an 
arbitrary revision by clicking on "Restore".

The main purpose of the versioning extension is to keep track of changes 
and enable users to view arbitrary versions. The extension should 
support "real" users who are working on XML documents via an editor or 
other clients. I think the extension does handle this job quite well. It 
is fairly efficient for reasonable-sized documents (i.e. documents you 
would still edit by hand, up to several megabytes). The additional 
overhead for the versioning is basically limited to the generation of 
the diff, and the trigger uses a few tricks to avoid copying documents. 
You can even query old revisions by using the special v:doc($doc, 
$revision) function.

However, the versioning does not work for node-level updates via XUpdate 
or XQuery update yet. It also doesn't handle binary documents (an 
important feature for me, so I will implement it soon I hope).

The extension can also detect conflicts and it can throw an exception if 
someone tries to overwrite changes which have been made since the 
document was checked out. For this, VersioningFilter adds some special 
attributes to the root element of a document when it is checked out 
(i.e. serialized).

What's still missing right now is a mechanism to resolve a conflict 
(either manual or automatically). The main problem is that eXist has no 
control over the client and thus no way to directly communicate with the 
user. All we can do is to save a copy of the conflicting data which was 
passed in by the user and raise a warning which then has to be handled 
by the client in a useful way.

The versioning extension, including a basic way to handle conflicts and 
proper documentation, will be part of the 1.3/1.4 release.

Wolfgang