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

[Jason S. <js...@in...>]

I am glad for now to know this is coming.  Once I get a little further along on my current project, I'll check back in on the state of versioning.  I may even know enough by then to have intelligent comments...

Thanks for the great response! 

________________________________________
From: Wolfgang [wol...@ex...]
Sent: Friday, May 29, 2009 4:16 PM
To: Adam Retter
Cc: Jason Smith; exi...@li...
Subject: Versioning extension (WAS: Re: Is eXist the right tool for me?)

> 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