[Zope-CVS] CVS: Products/Ape/doc - apexml.txt:1.1.2.1 outline.txt:1.1.6.1 ape.txt:NONE

[Shane Hathaway]

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

Modified Files:
      Tag: ape-scan-branch
	outline.txt 
Added Files:
      Tag: ape-scan-branch
	apexml.txt 
Removed Files:
      Tag: ape-scan-branch
	ape.txt 
Log Message:
Finished describing all elements of apeconf.xml

=== Added File Products/Ape/doc/apexml.txt ===


Ape Configuration XML Files


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.

Ape lets you mix configurations from any number of configuration
files, as long as none of the files contain conflicting directives.
To add support for a new class to Ape, write your own 'apeconf.xml'
rather than modify the standard configuration.  If you're writing a
Zope product, place your 'apeconf.xml' in your product directory.  Ape
will look for it and mix your configuration with the standard
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
variations of the standard configuration.

The schema uses two conventions that differ from XML norms.  First,
'variation' elements may appear anywhere child elements are allowed;
see the description of the 'variation' element.  Second, most
attributes and child elements are optional, allowing minimal
declarations.


Elements


  <configuration>
    ...
  </configuration>

    The root element of an Ape configuration file.  Uses no
    attributes.



  <variation name="...">
    ...
  </variation>

    The variation tag signifies that all contained directives belong
    to a variation rather than the standard configuration.  A
    variation element may appear anywhere child elements are allowed.

    Variation tags let you specify multiple configuration variations
    in a single file, keeping independent configurations together in a
    logical way.  Ape uses variations to keep 'apeconf.xml' clear
    while providing alternative configurations.

    The 'name' attribute is required.  It specifies which variation
    the child directives belong to.  Placing many directives in a
    single variation tag is equivalent to splitting those directives
    into several variation tags of the same name.

    Directives within a variation tag become part of a varied
    configuration rather than the standard configuration.  A
    configuration file can modify any number of variations.
    Directives outside any variation tag become part of the standard
    configuration.  When Ape loads a mapper, it specifies which
    variation it needs, then the configuration machinery combines
    directives from the variation with the standard directives.

    Ape uses variations to configure both a SQL and filesystem mapper
    in the same file.  Before Ape used XML, it used three Python
    modules to configure mappers: a base mapper, a filesystem
    variation, and a SQL variation.  The three separate files made it
    difficult to understand how to configure a mapper, and in fact
    introduced minor errors that went unnoticed for a long time.  A
    single XML file containing multiple variations turned out clearer
    and shorter than equivalent Python code.



  <mapper
      name="..."
      [ class="..." ]
      [ parent="..." ]
      [ extends="..." ] >
    ...
  </mapper>

    Declares a mapper component.  The 'name' attribute is required and
    usually specifies a fully-qualified class name.  The rest of the
    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
      classifier
      keygen
      use-for
      option
      variation

    Ape mixes mapper configurations based on the mapper name.  One
    configuration file can define a mapper while another adds an extra
    serializer, for example, as long as the two configurations do not
    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.

    The 'extends' attribute tells the mapper to inherit components
    from a base mapper.  The mapper will inherit gateways,
    serializers, a classifier, and a keychain, but no options,
    attributes, or 'use-for' registrations.  The derived mapper can
    override or disable inherited subcomponents by using the same name
    that inherited subcomponents use.

    The 'parent' attribute makes the mapper a child of another mapper.
    It should contain the name of a mapper.  Ape ignores mappers that
    are not part of a mapper tree, so most mappers need a 'parent'
    attribute.
    
    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.



  <serializer
      name="..."
      factory="..." | use="..."
      [ enabled="..." ]
      [ param="..." ]
      [ order="..." ] />

    Declares a serializer.  The 'name' attribute is required.  Either
    'factory' or 'use' is required.  The 'enabled', 'param', and
    'order' attributes are optional.  The 'param' attribute is valid
    only when a 'factory' is provided.  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.

    Use a Python class to implement a serializer, then use the
    'factory' attribute to link your class into Ape.  Specify a
    fully-qualified class name, such as "mypackage.mymodule.myclass".
    If your class constructor requires a parameter, you may pass one
    string parameter using the 'param' attribute.

    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.

    Mappers can have any number of serializers, but keep the number
    small for speed.  Sometimes the order in which the serializers get
    invoked matters.  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'.

    The 'enabled' attribute lets you disable an unwanted inherited
    serializer.  To do this, set the 'enabled' attribute to 'false'
    and match the name of the inherited serializer.



  <gateway
      name="..."
      factory="..." | use="..."
      [ enabled="..." ]
      [ param="..." ] />

    Declares a gateway.  The 'name' attribute is required.  Either
    'factory' or 'use' is required.  The 'enabled' and 'param'
    attributes are optional.  The 'param' attribute is valid only when
    a 'factory' is provided.  This element accepts no child elements.

    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.

    Use a Python class to implement a gateway, then use the 'factory'
    attribute to link your class into Ape.  Specify a fully-qualified
    class name, such as "mypackage.mymodule.myclass".  If your class
    constructor requires a parameter, you may pass one string
    parameter using the 'param' attribute.

    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.

    Mappers can have any number of gateways, but keep the number small
    for speed.  The order in which gateways are used should not
    matter.

    The 'enabled' attribute lets you disable an unwanted inherited
    gateway.  To do this, set the 'enabled' attribute to 'false' and
    match the name of the inherited gateway.



  <classifier
      [name="..."]
      factory="..." | use="..."
      [ enabled="..." ]
      [ param="..." ] />

  <keygen
      [name="..."]
      factory="..." | use="..."
      [ enabled="..." ]
      [ param="..." ] />

    Declares a classifier or keychain generator component.  The 'name'
    attribute is required for reusable components but should not be
    present otherwise.  Either 'factory' or 'use' is required.  The
    'enabled' and 'param' attributes are optional.  The 'param'
    attribute is valid only when a 'factory' is provided.  This
    element accepts no child elements.

    Most mappers have neither a classifier nor a keychain generator.
    Those that have either kind of component are called domain
    mappers, meaning that the mapper marks the root object of an
    application domain.  The root mapper is always a domain mapper.

    You can use a 'classifier' or 'keygen' element to declare either a
    reusable component, by placing it outside any mapper element, or a
    non-reusable component, by placing it inside a mapper element.
    Reusable components get added to a global but type-specific
    namespace.  Non-reusable classifiers and keychain generators do
    not have a name.

    Use a Python class to implement a new classifier or keychain
    generator, then use the 'factory' attribute to link your class
    into Ape.  Specify a fully-qualified class name.  If your class
    constructor requires a parameter, you may pass one string
    parameter using the 'param' attribute.

    To import a reusable component into a mapper, add a component
    declaration to a 'mapper' element, specifying the name of the
    component to import in the 'use' attribute of the component
    declaration.  The 'factory' and 'use' attributes can not be used
    together.

    The 'enabled' attribute lets you disable an unwanted inherited
    component.  To do this, set the 'enabled' attribute to 'false'.



  <use-for
    [ class="..." ]
    [ extensions="..." ]
    [ fallback="..." ]
    [ key="..." ] />

    The 'use-for' directive registers a mapper with the parent's
    classifier.  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 'fallback' attribute tells the classifier to use this mapper
    for objects or filesystem nodes with no other classification.  The
    allowable values for the 'fallback' 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.

    Again, the 'fallback' registrations only apply when no other
    classification is available.

    The 'key' attribute tells the classifier to use this mapper when
    the last key of the keychain matches the attribute value.  This is
    useful for Zope's site-wide Application object, since it always
    has a particular keychain.

    Registrations made by 'use-for' get applied to the parent mapper's
    classifier.  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.



  <option name="..." value="..." />

    The 'option' directive registers an mapper-specific option with
    the parent's 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 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'.



=== Products/Ape/doc/outline.txt 1.1 => 1.1.6.1 ===
--- Products/Ape/doc/outline.txt:1.1	Thu Mar 27 09:28:31 2003
+++ Products/Ape/doc/outline.txt	Wed Jul 30 16:54:37 2003
@@ -362,10 +362,9 @@
 III. Example: Mapping Zope 2
 
   ApeLib provides two default Zope 2 mappers.  One maps to the
-  filesystem and the other maps to a PostgreSQL database.  Because
-  there is a lot in common between the two mappers, the createMapper()
-  function in the basemapper module sets up the mappers and
-  serializers, while two derivative functions set up the gateways.
+  filesystem and the other maps to a PostgreSQL database.  Both are
+  configured through apeconf.xml files.  See apexml.txt for more
+  details on the configuration files.
 
   The PostgreSQL mapper uses the Psycopg module to connect to the
   database.  It uses integers as keys and puts information about
@@ -380,16 +379,22 @@
   without filename extensions.
 
   Normally, ZODB caches objects indefinitely.  This leads to excellent
-  performance, but prevents the object system from having the most
-  current data all the time.  One workaround is to set the ZODB cache
-  size to zero, forcing ZODB to clear its cache after every
-  transaction.  But that solution eliminates the ZODB performance
-  advantage, so ApeLib needs a better solution.  Nothing specific is
-  planned yet.
-
-  To extend the Zope 2 mappers with your own mappers, you can write a
-  function that first calls the standard mapper factory and then
-  adds to the generated mapper tree.
+  performance, but in the case of Ape, it prevents the object system
+  from having the most current data all the time.  One workaround is
+  to set the ZODB cache size to zero, forcing ZODB to clear its cache
+  after every transaction, but that solution eliminates the ZODB
+  performance advantage.
+
+  Ape has a new solution to the cache invalidation problem.  Ape keeps
+  a record of which OIDs are in use and correlates them with
+  filesystem paths and last-modified times.  Then it periodically
+  scans those paths, invalidating OIDs if it sees changes.  The
+  solution could potentially work even better with RDBMSs, since the
+  periodic scan could be implemented using only a single query.
+
+  To extend the Zope 2 mappers with your own mappers, write an
+  apeconf.xml file and place it in your Zope 2 product.  See
+  apexml.txt for more information.
 
 
 IV. Multiple domains
@@ -459,7 +464,7 @@
   ZEO: ApeLib 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.
+  large object cache.  Ape has been successfully tested with ZEO 3.2.
 
   Zope 3: ApeLib 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

=== Removed File Products/Ape/doc/ape.txt ===