====================
MetaDirectory Design
====================

:Revision: $Id: metadirectory.txt 31620 2006-01-13 17:01:30Z gracinet $

.. sectnum::    :depth: 4
.. contents::   :depth: 4


Introduction
============

A meta-directory is a directory whose purpose is to link and
redirect access to parts of an entry to other directories, doing
some conversions in the process.

Reading, writing, creating, deleting and searches are all
dispatched appropriately to the backing directories.

A meta-directory is typically used to provide a synthesized
user's directory for the CPSUserFolder, using several backing
directories for different user properties, and also optionally
separate directories for the groups and roles.


Features
========

Multiple backing directories for one entry
------------------------------------------

An entry of a meta-directory is built from the corresponding
entries of several other directories, called the backing
directories.

For each backing directory, the following must be specified:

- what fields from the backing directory are be ignored,

- what fields from the backing directory are renamed,

- what entry is used if it is missing from the backing directory.

Ignoring a field is useful if the backing directory's schema
contains too much information and some of it has to be ignored
when constructing the meta-directory.

Renaming means that the same field can be present in the
meta-directory and in the backing directory, but under a different
name. A field cannot be renamed several times; there must be a
one-to-one mapping (bijection) of field names between the backing
directory and the meta-directory.

The notion of missing entries is used when an entry is assembled
from several backing directories, but may be missing in some of
them. Without missing entries, all backing directories must
contain information about exactly the same entries. Missing
entries allow some backing directories (but not all) to have a
default available when the entry is missing in them.

A typical use case for missing entries is that of an LDAP backing
directory containing all authoritative entries, and a ZODB
directory containing additional information like
"last_login_time". This ZODB directory cannot be kept in sync with
LDAP because LDAP is an external source, so it's not possible to
have exactly the same entries in both backing directories at all
times. Specifying an empty missing entry (``python:{}``) for the
ZODB directory will allow the meta-directory to function, and
generate an adequate default. When writing, though, the entry will
be fully written in all backing directories, and further reads
will retrieve those values.

There is also an important constraint to all the backing
directories: they must have the same ID field as the
meta-directory (StackingDirectory is a directory that can do id
conversion from the backing directory, use that one if you need
it).

Substring search behaviour is completely handled by the backings
and applies to the missing entry as well. 
Therefore a meta-directory has no property search_substring_fields

Cross-references
----------------

(NOT IMPLEMENTED)

Some fields of the meta-directory that are lists can be computed
as cross-references to other directories. When these fields read,
they are computed from a search in cross-referenced directory;
when they are written to, it's actually several entries of the
cross-referenced directory that may be modified.

For each cross-referenced field must be specified:

- to what target directory and field is the cross-reference.

Cross-references are one-way, to get coherent directories the
target field in the target directory must be cross-referenced in
the opposite way.
