Changeset 4185 for waeup/branches/ulif-rewrite

Timestamp:

27 May 2009, 09:33:29 (16 years ago)

Author:

uli

Message:

Update docs.

File:

• waeup/branches/ulif-rewrite/src/waeup/datacenter.txt (modified) (1 diff)

waeup/branches/ulif-rewrite/src/waeup/datacenter.txt

@@ -209 +209 @@
 
     >>> os.unlink(filepath)
+
+
+Data center helpers
+===================
+
+Data centers provide several helper methods to make their usage more
+convenient.
+
+
+Receivers and receiver ids
+--------------------------
+
+As already mentioned above, imports are defined as triples containing
+
+* a file to import, 
+
+* an importer to do the import and 
+
+* an object, which should be updated by the data file.
+
+The latter normally is some kind of container, like a faculty
+container or similar. This is what we call a ``receiver`` as it
+receives the data from the file via the importer.
+
+The datacenter finds receivers by looking up its parents for a
+component, that implements `ICSVDataReceivers` and scanning that
+component for attributes, that can be adapted to `ICSVImporter`.
+
+I.e., once found an `ICSVDataReceiver` parent, the datacenter gets all
+importers that can be applied to attributes of this component. For
+each attribute there can be at most one importer.
+
+When building the importer list for a certain file, we also check,
+that the headers of the file comply with what the respective importers
+expect. So, if a file contains broken headers, the file won't be
+offered for import at all.
+
+The contexts of the found importers then build our list of available
+receivers. This means also, that for each receiver provided by the
+datacenter, there is also an importer available.
+
+If for a potential receiver no importer can be found, this receiver
+will be skipped.
+
+As one type of importer might be able to serve several receivers, we
+also have to provide a unique id for each receiver. This is, where
+``receiver ids`` come into play.
+
+Receiver ids of objects are determined as
+
+* the ZODB oid of the object if the object is persistent
+
+* the result of id(obj) otherwise.
+
+The value won this way is a long integer which we turn into a
+string. If the value was get from the ZODB oid, we also prepend it
+with a ``z`` to avoid any clash with non-ZODB objects (they might
+deliver the same id, although this is *very* unlikely).