[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