eXist collections

Module to deal with collection creation.

The library is available on CXAN, with the ID: exist-collections.

This module provides 3 main entry points:

• c:ensure
• c:create
• c:fixup

Each of them take as parameter a "c:collection" element, representing collections and some of their properties: owner, group and permissions (called "rights" in this module). A c:collections element looks like:

     <collections xmlns="http://h2oconsulting.be/ns/exist/collections">
        <root>/db</root>
        <collection>
           <name>company/project</name>
           <rights>rwxr-x---</rights>
           <user>foo</user>
           <group>bar</group>
           <collection>
              <name>sub-coll1</name>
              <rights>rwx------</rights>
           </collection>
           <collection>
              <name>sub-coll2</name>
              <group>zab</group>
           </collection>
        </collection>
     </collections>

There can be several c:collection in c:collections. There can be c:user, c:group and c:rights in c:collections, as default values. The c:root is assumed to always exist, and the user, group and permissions are never checked against it.

The above example shows how properties are "inherited" from ancestor collections to descendant collections. For instance the collection sub-coll1 inherits the user and group from its parent. Collection paths are composed as well. One collection "name" can contain several steps at once, if they all share the same properties. The above example corresponds to the following collections:

       /db
         - not checked
   
       /db/company
         - owner: foo/bar
         - perms: rwxr-x---
   
       /db/company/project
         - owner: foo/bar
         - perms: rwxr-x---
   
       /db/company/project/sub-coll1
         - owner: foo/bar
         - perms: rwx------
   
       /db/company/project/sub-coll2
         - owner: foo/zab
         - perms: rwxr-x---

The differences between the 3 functions are as follow:

• c:ensure: ensure the collections exist, with the correct properties, if a collection exists with a different value for a property, that is an error, if a collection does not exist, it is created with the corresponding properties
• c:create: the collections must be created, meaning they cannot exist, if any collection already exists (except the root), it is an error
• c:fixup: like c:ensure, except that when an existing collection as a different value for a property, it tries to change that value

Implementation notes.

The only difference between the 3 main entry points is when a collection already exists. For c:ensure, it throw an error if a property is not as expected, for c:create, it is always an error, and for c:fixup, it changes the properties with a different value.

A single set of functions walk through the collections and create them as required. When a collection already exists, they call a function item passed all the way down from the main entry point (a different function item exist for each entry point, implementing the needed bahaviour).