Configuration

The segmenting function is not enabled by default for a repository, meaning that ModeShape will store all children nodes under the same parent. To enable it, you need to add it to the repository configuration:

"storage" : {
  "documentOptimization" : 
      "childCountTarget" : 1000,
      "childCountTolerance" : 10,
      "threadPool" : "modeshape-opt",
      "initialTime" : "00:00",
      "intervalInHours" : 24
   }
}

or in JBoss AS:

            
   <repository name="sample" 
      document-optimization-child-count-target="1000" 
      document-optimization-child-count-tolerance="10"
      document-optimization-initial-time="02:00"
      document-optimization-interval="24"
      document-optimization-thread-pool="modeshape-opt"
/>

where the first 2 attributes control the desired number of children per segment and the variance tolerance, while the last 3 control the details of the thread-pool that spawns the actual threads performing the optimization process.

Accessing by path

Navigating to a node by using its path is perhaps one of the most common access patterns in JCR. This uses the 'Node.getNode(String)' method that takes a relative path, and essentially boils down to finding a particular child node with the supplied name and same-name-sibling index. ModeShape internally indexes the children in each block by both name, so finding nodes by name (and SNS) are as fast as possible, even if multiple blocks need to be accessed.

Iterating

Another common access pattern is to iterate over some or all of a parent node's children, using the 'Node.getNodes()' and 'Node.getNodes(String)' methods. The resulting NodeIterator will transparently access the children in one block at a time, and will continue with all blocks until the last child reference is found or until the caller halts the iteration.

Accessing by identifier

Another common access pattern is to find a node by identifier, using the 'Session.getNodeByIdentifier(String)' method. ModeShape handles this request by directly finding the node by its identifier, and only needs to access the parent's (or ancestors') child references only when the node's name or path is requested by the caller (via the 'Node.getName()' or 'Node.getPath()' methods).

Usage

The 4 predefined mixins are:

and they don't define any additional JCR properties or child nodes. You can choose only one, and once there are children you cannot add or remove these mixins. How do you know which mixin to use? The biggest factor will be the upper limit on the average number of child nodes stored in each bucket, which you can estimate by dividing the total number of expected child nodes by the number of buckets. Don't make this average too small, though, since that will increase the overhead for storing all the child references. Think carefully, because the only way to change the number of buckets is to manually copy or move the nodes to a new parent. We recommend prototyping your choice so you can measure performance with your own data and client application.

The mixins can be used either via the node type definitions:

[test:smallCollection] > mode:unorderedSmallCollection
  - * (undefined) multiple 
  - * (undefined) 
  + * (nt:base) = nt:unstructured 

or via regular JCR API like:

node.addMixin("mode:unorderedLargeCollection").

In this last case, such mixins can only be added & removed at runtime if the node on which they are added or removed does not have any children. Also, multiple unordered mixins cannot be added on the same node. Only the first one counts.

Limitations

These special mixins, although they provide really fast access by name or path, come at a cost in the form of various JCR operations & features that are not supported:

All other JCR operations & features are supported just like for regular nodes.

Accessing by path

Navigating to a node using its path for these types of collections offers the best performance improvement (in terms of latency and memory consumption) out of all the JCR operations and is far superior to the same operations performed on a regular node.

Iterating

Has better memory consumption but equal to or possibly worse latency than regular nodes because buckets are lazily loaded into memory. That means that the more children are iterated - i.e. the longer the iteration takes - the higher the chance of extra buckets needed to be loaded into memory.

Accessing by identifier

Using the 'Session.getNodeByIdentifier(String)' method offers the same performance as regular nodes since ModeShape will do the lookup directly, without using the child references in any way. However, operations like 'Node.getName()' or 'Node.getPath()' might perform worse because in those cases ModeShape has to find the name of a node starting from its ID, which means looking and possibly loading each bucket until a reference is found.

Adding nodes

Adding nodes will also be improved, especially when compared to regular nodes that maintain order of the children or that allow children with the same names.