The New dbXML Indexing System
=============================

Old Format:

   <indexManager class="com.dbxml.core.SimpleIndexManager">
      <indexer class="com.dbxml.core.FlatIndexer"
               name="testIndex" location="./db/test/ocs.idx">
          <indexEntry matchingPattern="indexEntry"
                      addDescendency="true"/>
      </indexer>
   </indexManager>

The old system had an abstracted IndexManager layer where the
IndexManager implementation was responsible for managing the
Indexes, and so the format for its entries were up to the actual
implementation.  SimpleIndexerManager could only manage one
Indexer instance, so you couldn't attach both a FlatIndexer
and some other type of indexing system to a collection.  This
also introduced the problem of that Indexer instance having to
maintain multiple indexing chains all in the same file, which
made managing the underlying file structures a nightmare as you
added and removed entries.

New Format:

   <indexes>
      <index class="org.dbxml.core.indexer.NodeIndexer"
             name="test" pattern="test"/>
   </indexes>
   
The new indexing system does away with the old system, by allowing
more than one Indexer type per Collection, by solidifying the XML
configuration format for Indexes, and by mapping Index entries to
Indexer instances for easier maintainability.

The concrete IndexManager now does the job of maintaining Indexes
as well as multicasting indexer events to the Indexers responsible
for the pattern that is currently being processed.


There are 3 required parameters for any Indexer, these are:

   Name    Type   Description
   ======= ====== =================================================
   class   String The classname of the Indexer
   name    String The name of the Indexer instance (must be unique)
   pattern String The element pattern that the Indexer recognizes

org.dbxml.core.indexer.NodeIndexer is the standard dbXML indexer.  It
provides the ability to index the value of elements or attributes.
NodeIndexer has four additional, but optional, attributes:

   Name       Type   Description
   ========== ====== ==============================================
   trim       bool   Whether or not to trim extra whitespace
   unique     bool   Whether this index only stores unique values*
   pagesize   int    The page size for Index pages (default: 4096)
   maxkeysize int    The max key size for values (default: 0=none)

* = Not implemented


Element Patterns:

Element Patterns are used by the Indexing system to determine
best-fit and match-based Indexers for queries and index updating.
You don't use XPaths to specify indexes anymore.  The pattern used
MUST resemble this scheme.  The IndexManager will determine the best
indexes to use for specific sub-expressions of any given XPath.

   Pattern     Description
   =========== ====================================================
   elem        The value of the named element
   elem@attr   The value of the attribute for the named element
   *           The value for all elements
   *@attr      The value of the named attribute for all elements
   elem@*      The value of all attributes for the named element
   *@*         The value of all attributes for all elements

Example:

Because the patterns recognize either an element or an attribute,
and not both, in order to index all element and attribute values
in a collection, you'd have to create two index entries:

   <index class="org.dbxml.core.indexer.NodeIndexer"
          name="allElems" pattern="*"/>
   <index class="org.dbxml.core.indexer.NodeIndexer"
          name="allAttrs" pattern="*@*"/>

Important:

Depending on the Indexer class, wildcard patterns may slow down
query processing.  In the case of NodeIndexer, if a wildcard index
is determined to be the best match for a specific element query
sub-expression, the query will be issued to the NodeIndexer,
which will then query on the specified value and have to weed out
all matches that don't fit the actual element requested.
Non-wildcard indexes do not suffer from this problem.

   <doc>
      <value1>Test</value1>
      <value2>Test</value2>
      <value3>Test</value3>
   </doc>
   
In this case, if there is a wildcard element Indexer defined,
the value of "Test" is going to be associated with all three value?
elements, and each will be returned from the Index, if you're
only looking for a value2 element with a value of "Test", the
Indexer will have to reduce the match set down to the element
you've specified before returning it to the query resolver.

Best practice would be to use specific element or attribute
indexes whenever possible, and only define wildcard indexes
when it is absolutely necessary.
      
