[Zope-CVS] CVS: Products/Ape/doc - apexml.txt:1.2 outline.txt:1.2
Shane Hathaway
shane@zope.com
Wed, 30 Jul 2003 17:33:28 -0400
Update of /cvs-repository/Products/Ape/doc
In directory cvs.zope.org:/tmp/cvs-serv5368/doc
Modified Files:
outline.txt
Added Files:
apexml.txt
Log Message:
Merged ape-scan-branch, sneaking in interface updates and minor reformatting.
Ape now watches the filesystem for changes to objects that Zope has in its
cache.
=== Products/Ape/doc/apexml.txt 1.1 => 1.2 ===
--- /dev/null Wed Jul 30 17:33:27 2003
+++ Products/Ape/doc/apexml.txt Wed Jul 30 17:32:53 2003
@@ -0,0 +1,351 @@
+
+
+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 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 '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.2 ===
--- Products/Ape/doc/outline.txt:1.1 Thu Mar 27 09:28:31 2003
+++ Products/Ape/doc/outline.txt Wed Jul 30 17:32:53 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