[Zope-CVS] CVS: Products/Ape/doc - apexml.txt:1.5 outline.txt:1.4

Shane Hathaway shane at zope.com
Sat Jul 24 23:53:12 EDT 2004


Update of /cvs-repository/Products/Ape/doc
In directory cvs.zope.org:/tmp/cvs-serv17621/doc

Modified Files:
	apexml.txt outline.txt 
Log Message:
Updated the mapper configuration documentation.

The load and store directives are the most significant changes.


=== Products/Ape/doc/apexml.txt 1.4 => 1.5 ===
--- Products/Ape/doc/apexml.txt:1.4	Mon Mar 15 23:57:53 2004
+++ Products/Ape/doc/apexml.txt	Sat Jul 24 23:52:41 2004
@@ -5,8 +5,8 @@
 
 Ape configures mappers using configuration files.  The standard Zope 2
 mapper configuration is in the file 'apeconf.xml' in the
-'apelib.zope2' package.  Look over the standard configuration file to
-get a feel for what the file does.  Refer to it as an example.
+'apelib.zope2' package.  Refer to the standard configuration file as
+an example.
 
 Ape lets you mix configurations from any number of configuration
 files, as long as none of the files contain conflicting directives.
@@ -17,10 +17,9 @@
 configuration.
 
 The Ape configuration schema is fairly simple.  The root
-'configuration' tag contains component declarations.  Component
-declarations contain component-specific configurations and
-registrations.  Variation tags are intermingled with the other
-configuration directives, allowing a configuration file to define
+'configuration' tag contains component definitions and registrations.
+Variation tags are intermingled with the other configuration
+directives, allowing a configuration file to define multiple
 variations of the standard configuration.
 
 The schema uses two conventions that differ from XML norms.  First,
@@ -87,15 +86,13 @@
   </mapper>
 
     Declares a mapper component.  The 'name' attribute is required and
-    usually specifies a fully-qualified class name.  The rest of the
+    usually specifies a fully-qualified class name.  The other
     attributes are optional.  A mapper element should be a direct
     child of either a 'variation' or a 'configuration' element.  A
     mapper element may contain the following optional child elements:
 
       serializer
       gateway
-      use-for
-      option
       variation
 
     Ape mixes mapper configurations based on the mapper name.  One
@@ -104,55 +101,30 @@
     conflict.
 
     The 'class' attribute specifies the class the mapper is to be used
-    for.  If no 'class' attribute is associated with a mapper, Ape
-    defaults to using the mapper name as the class name.  Since most
-    mappers are used for exactly one class and are named according to
-    that class, you can generally omit the 'class' attribute.
-
-    There are a few situations where you should specify a 'class'
-    attribute.  Ape recognizes two special values for the 'class'
-    attribute, 'none' and 'any'.  Use 'none' for abstract mappers,
-    which are designed to be extended but never used directly.  Use
-    'any' to create a generic mapper.  Generic mappers can serialize
-    instances of many classes.  See the 'anyfile' and 'anyfolder' Zope
-    2 mappers for an example.  Also, if you have a complex mapper
-    tree, you may need to apply a class to different mappers depending
-    on the context.  To do this, set the class attributes for both
-    mappers to the fully-qualified class name, then use different
-    mapper names.  When you specify a class attribute, the mapper name
-    does not need to specify a class.
+    for.  If no 'class' attribute is associated with a mapper, the
+    mapper is abstract.
 
     The 'extends' attribute tells the mapper to inherit components
     from a base mapper.  The sub-mapper will inherit gateways and
-    serializers, but no options or 'use-for' registrations.  The
-    derived mapper can override or disable inherited subcomponents by
-    using the same name that inherited subcomponents use.
-
-    Internally, Ape interprets a mapper element as several directives.
-    The directives get stored in small indexed tables.  When an
-    application such as Zope requests a configured mapper, a
-    MapperAssembler iterates over the tables to configure mappers and
-    returns the root mapper.
+    serializers.  The derived mapper can override or disable inherited
+    serializers and gateways using a directive with a matched name.
+
+    Note that existence of a mapper does not imply to the system that
+    objects should be stored using that mapper.  Use the 'store' and
+    'load' directives to tell the system when to use which mappers.
 
 
 
   <serializer
-      factory="..." | use="..."
+      factory="..." | enabled="..."
       [ name="..." ]
-      [ enabled="..." ]
       [ order="..." ] />
 
-    Declares a serializer.  Either 'factory' or 'use' is required.
-    The 'name', 'enabled', and 'order' attributes are optional.  The
-    'order' attribute is valid only when the element descends from a
-    mapper element.  This element accepts no child elements.
-
-    You can use this element to declare either a reusable serializer,
-    by placing it outside any mapper element, or a non-reusable
-    serializer, by placing it inside a mapper element.  Reusable
-    serializers get added to a global namespace of serializers.
-    Non-reusable serializers get added to a namespace local to the
-    mapper.
+    Declares a serializer.  Either 'factory' 'enabled' is required.
+    The 'name' and 'order' attributes are optional.  The 'order'
+    attribute is valid only when the element descends from a mapper
+    element.  This element accepts no child elements.  Use this
+    element as a child of a mapper element.
 
     Use a Python class to implement a serializer, then use the
     'factory' attribute to link your class into Ape.  Specify a
@@ -161,17 +133,13 @@
     the end of the 'factory' attribute in parentheses.  (Only
     positional arguments are supported.)
 
-    To import a reusable serializer into a mapper, add a serializer
-    declaration to a 'mapper' element, specifying the name of the
-    serializer to import in the 'use' attribute of the serializer
-    declaration.  The 'factory' and 'use' attributes can not be used
-    together.  If you don't specify a 'name' attribute, the serializer
-    will be used as the main serializer for the mapper.  If you
-    specify a 'name' attribute, the serializer will be added to the
-    mapper's composite serializer.
+    If you don't specify a 'name' attribute, the serializer will be
+    used as the main serializer for the mapper.  If you specify a
+    'name' attribute, the serializer will be added to the mapper's
+    composite serializer.
 
-    Mappers can have any number of serializers.  Sometimes the order
-    in which the serializers get called matters.  In those rare cases,
+    Mappers can have any number of serializers.  Sometimes the
+    ordering of the serializers is important.  In those rare cases,
     use the 'order' attribute to specify a sort key.  Use 'a' to make
     it run first and 'z' to make it run last.  The default sort key is
     'middle'.
@@ -183,19 +151,12 @@
 
 
   <gateway
-      factory="..." | use="..."
-      [ name="..." ]
-      [ enabled="..." ] />
-
-    Declares a gateway.  Either 'factory' or 'use' is required.  The
-    'name' and 'enabled' attributes are optional.  This element
-    accepts no child elements.
+      factory="..." | enabled="..."
+      [ name="..." ] />
 
-    You can use this element to declare either a reusable gateway, by
-    placing it outside any mapper element, or a non-reusable gateway,
-    by placing it inside a mapper element.  Reusable gateways get
-    added to a global namespace of gateways.  Non-reusable gateways
-    get added to a namespace local to the mapper.
+    Declares a gateway.  Either 'factory' or 'enabled' is required.
+    The 'name' attribute is optional.  This element accepts no child
+    elements.  Use this element as a child of a mapper element.
 
     Use a Python class to implement a gateway, then use the 'factory'
     attribute to link your class into Ape.  Specify a fully-qualified
@@ -204,11 +165,10 @@
     the 'factory' attribute in parentheses.  (Only positional
     arguments are supported.)
 
-    To import a reusable gateway into a mapper, add a gateway
-    declaration to a 'mapper' element, specifying the name of the
-    gateway to import in the 'use' attribute of the gateway
-    declaration.  The 'factory' and 'use' attributes can not be used
-    together.
+    If you don't specify a 'name' attribute, the gateway will be used
+    as the main gateway for the mapper.  If you specify a 'name'
+    attribute, the gateway will be added to the mapper's composite
+    gateway.
 
     Mappers can have any number of gateways.  The order in which
     gateways are used should not matter.
@@ -220,14 +180,16 @@
 
 
   <classifier
-      factory="..." | use="..." />
+      factory="..." />
 
   <oid-generator
-      factory="..." | use="..." />
+      factory="..." />
 
-    Declares the classifier or OID generator component.  Either
-    'factory' or 'use' is required.  This element accepts no child
-    elements.
+    Declares the classifier or OID generator component.  The 'factory'
+    attribute is required.  The oid-generator element accepts no child
+    elements, but the classifier element accepts a gateway element,
+    since classifiers usually need a gateway for loading and storing
+    classification data.
 
     Use a Python class to implement a new classifier or OID generator,
     then use the 'factory' attribute to link your class into Ape.
@@ -237,76 +199,71 @@
     supported.)
 
 
-  <use-for
-    [ class="..." ]
-    [ extensions="..." ]
-    [ generic="..." ]
-    [ oid="..." ] />
-
-    The 'use-for' directive tells a classifier to use a particular
-    mapper when a condition is met.  The 'use-for' directive must
-    descend from a 'mapper' element and accepts no children.  All
-    attributes are optional.  A mapper element can contain any number
-    of 'use-for' directives.
-
-    The 'class' attribute tells the classifier to use this mapper for
-    an extra class.  This is especially useful when working with
-    generic mappers.  A generic mapper often has to make guesses about
-    the object it's serializing, and sometimes it doesn't make the
-    right guess.  The 'class' attribute can solve the situation by
-    mapping problematic objects to a different mapper.
-
-    The 'extensions' attribute specifies filename extensions that
-    should imply this mapper.  Separate the extensions with a space.
-    The first extension is the default.  If you create an object in
-    Zope with no extension and store it in a mounted Ape filesystem,
-    Ape will append the default extension automatically.
-
-    The 'generic' attribute tells the classifier to use this mapper
-    for objects or filesystem nodes with no other classification.  The
-    allowable values for the 'generic' attribute vary by classifier,
-    but the Zope 2 classifier recognizes the following values:
-
-      - 'directory': Use this mapper for filesystem directories.
-
-      - 'file': Use this mapper for filesystem files.
-
-      - 'folderish_object': Use this mapper for objects that extend
-        ObjectManager.
-
-      - 'fileish_object': Use this mapper for objects that do not
-        extend ObjectManager.
-
-      - 'basepath': Use this mapper for the Zope 2 Application object.
-
-    Again, the 'generic' registrations only apply when no other
-    classification is available.
-
-    The 'oid' attribute tells the classifier to use this mapper when
-    the OID of the object being loaded or stored matches the attribute
-    value.  This is useful for the ZODB root object, since it always
-    has a particular OID.
+  <store
+    class="..." | exact-class="..."
+    using="..."
+    [default-extension="..." | default-extension-source="..." ]
+ 
+    The 'store' directive creates a rule telling the classifier which
+    mapper to use when storing instances of a particular class.  It
+    accepts no child elements.
 
-    If two mappers make conflicting registrations (such as two mappers
-    trying to use the same filename extension), Ape will detect a
-    conflict.  If you need to override a registration made by another
-    mapper, you should use a variation.
+    The 'class' or 'exact-class' attribute specifies which class the
+    directive applies to.  Only one of the two attributes is allowed.
+    If 'class' is used, the directive also applies to subclasses; if
+    'exact-class' is used instead, the directive applies only to
+    instances of exactly the class specified.  The 'using' attribute
+    says which mapper to use for storing matched instances.
+
+    The optional 'default-extension' attribute provides a filename
+    extension to add automatically to objects stored on the filesystem
+    (if the object does not yet have an extension.)  The alternative
+    'default-extension-source' tells the classifier how to compute the
+    extension.  The only currently implemented value for
+    'default-extension-source' is 'content_type', which means that the
+    classifier should read the object's 'content_type' attribute,
+    interpret it as a mime type (i.e. 'text/plain'), and translate
+    that to a filename extension.  This strategy works well enough for
+    Zope's image and file objects.
 
 
 
-  <option name="..." value="..." />
+  <load
+    extensions="..." | generic="..." | mapper-name="..."
+    using="..." />
+
+    The 'load' directive creates a rule telling the classifier which
+    mapper to use when loading data that has not already been
+    classified with a mapper name.  It accepts no child elements.
+
+    Exactly one of 'extensions', 'generic', or 'mapper-name' is
+    required.  The required 'using' attribute says which mapper to use
+    for loading matched instances.
 
-    The 'option' directive registers an mapper-specific option with
-    the classifier.  The 'option' directive must descend from a
-    'mapper' element and accepts no children.  The 'name' and 'value'
-    attributes are both required.  A mapper element can contain any
-    number of 'use-for' directives.
+    The 'extensions' attribute specifies filename extensions that
+    trigger this rule.  Separate the extensions with a space.
 
-    The one option that is currently available is specific to the Zope
-    2 classifier.  The 'content_type_attr' tells the classifier that
-    when serializing, there will be an attribute on the object that
-    specifies the MIME type of the object's content.  The classifier
-    then translates the MIME type to a default filename extension.
-    The value of the option is the name of the attribute, usually
-    'content_type'.
+    The 'generic' attribute tells the classifier to use this mapper in
+    certain generic situations.  The allowable values for the
+    'generic' attribute vary by classifier, but the Zope 2 classifier
+    recognizes the following values:
+
+      - 'directory': Use this mapper for filesystem directories if no
+        other rule matches.
+
+      - 'file': Use this mapper for filesystem files if no other other
+        rule matches.
+
+      - 'basepath': Use this mapper when loading the object at the
+        base path on the filesystem.  The default configuration uses
+        this directive for the Zope 2 Application object.
+
+      - 'root': Use this mapper for the database root object, which
+        usually has OID "0".
+
+    The 'mapper-name' attribute sets up a mapper name alias.  Over
+    time, the names of mappers may change while object instances
+    continue to use the old names.  A mapper name alias alleviates
+    this problem by telling the classifier to load old instances using
+    a new mapper name.
 


=== Products/Ape/doc/outline.txt 1.3 => 1.4 ===
--- Products/Ape/doc/outline.txt:1.3	Mon Mar 15 23:56:40 2004
+++ Products/Ape/doc/outline.txt	Sat Jul 24 23:52:41 2004
@@ -1,5 +1,5 @@
 
-Ape Tutorial Outline
+Ape Documentation Outline
 
 
 I. Purpose of Ape
@@ -85,15 +85,13 @@
 
 II. Components
 
-  A portion of Martin Fowler's book "Patterns of Enterprise
-  Application Architecture" describes patterns used in mapping objects
-  to relational databases.  A lot of the names used in Ape come
-  from the book.
+  A lot of the names used in Ape are based on Martin Fowler's book
+  "Patterns of Enterprise Application Architecture".
 
-  There are many kinds of components in Ape, but to store new kinds
-  of objects or store in new formats, you generally only need to write
+  There are many kinds of components in Ape, but to store new kinds of
+  objects or store in new formats, you generally only need to write
   components that implement one of two interfaces: ISerializer and
-  IGateway.  This tutorial focuses on these two kinds of components.
+  IGateway.  This document focuses on these two kinds of components.
 
   A. Mappers
 
@@ -259,18 +257,18 @@
 
       ZODB makes an assumption that isn't always valid in Ape: ZODB
       assumes that objects that derive from the Persistent base class
-      are database record boundaries.  In Ape, sometimes it makes
-      sense to serialize several Persistent objects in a single
+      are database record boundaries.  In Ape, however, sometimes it
+      makes sense to serialize several Persistent objects in a single
       database record.
 
-      However, when you serialize more than one Persistent object in a
+      In Ape, when you serialize more than one Persistent object in a
       single record, you create what are called "unmanaged" persistent
-      objects or "UPOs".  If the serializer does tell Ape about the
-      UPOs, ZODB will not see changes made to them and transactions
-      involving changes to those objects may be incomplete.  So during
-      both serialization and deserialization, it is important for
-      ZODB-aware serializers to append to the event's 'upos'
-      attribute.
+      objects or "UPOs".  If the serializer forgets to tell Ape about
+      the UPOs, ZODB will not see changes made to them and
+      transactions involving changes to those objects may be
+      incomplete.  So during both serialization and deserialization,
+      it is important for ZODB-aware serializers to append to the
+      event's 'upos' attribute.
 
     Ape provides some useful standard serializers:
 
@@ -291,20 +289,11 @@
       method).  If the test fails, the optional serializer ignores the
       failure and falls back to a default.
 
-      - The "any class" serializer is a composite serializer which,
-      unlike the standard "known class" composite serializer, can
-      serialize and deserialize objects of any class.  During
-      deserialization, it defers the creation of a class instance
-      until the classification of the object is known.  The "any
-      class" serializer incurs performance penalties, but it allows
-      Ape to work with extremely heterogeneous object systems like
-      Zope.
-
     Serializers access the innards of objects, often breaking
     encapsulation because the serializers need to know exactly what
-    attributes the objects use.  To avoid breaking encapsulation,
-    objects might implement part of the serialization process
-    themselves.
+    attributes the objects use.  To avoid breaking encapsulation, you
+    can implement parts of the (de)serialization process in the
+    serializable objects.
 
   F. Classifiers
 
@@ -349,7 +338,7 @@
   a Zope 2 mapper configuration.  To extend the Zope 2 mappers with
   your own mappers, write an apeconf.xml file and place it in your
   Zope 2 product.  One maps to the filesystem and the other maps to a
-  SQL database.  See apexml.txt for more details on apeconf.xml.
+  SQL database.  See apexml.txt for details on apeconf.xml.
 
   The SQL mapper uses a Python DB-API 2.0 module to connect to the
   database.  It uses integers as keys and puts information about each
@@ -378,12 +367,12 @@
 
 
 
-IV. Ways to use the framework
+IV. Other ways to use the framework
 
   ZEO: Ape separates serialization from data storage, making it
   possible to perform serialization on a ZEO client while data storage
-  happens in a ZEO server.  ZEO also adds the ability to keep a very
-  large object cache.  Ape has been successfully tested with ZEO 3.2.
+  happens in a ZEO server.  Ape has been successfully tested with ZEO
+  3.2.
 
   Zope 3: Ape is currently designed with Zope 2 in mind, but meant
   to be reusable for Zope 3.  A new set of mappers will be needed, but



More information about the Zope-CVS mailing list