Created
January 15, 2020 18:48
-
-
Save crised/cc5333e1380e44c110261d45adf2b168 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. 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. | |
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 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, | |
'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="..." ] | |
[ extends="..." ] > | |
... | |
</mapper> | |
Declares a mapper component. The 'name' attribute is required and | |
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 | |
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, 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. 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="..." | enabled="..." | |
[ name="..." ] | |
[ order="..." ] /> | |
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 | |
fully-qualified class name, such as "mypackage.mymodule.myclass". | |
If your class constructor requires parameters, you may add them to | |
the end of the 'factory' attribute in parentheses. (Only | |
positional arguments are supported.) | |
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 | |
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'. | |
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 | |
factory="..." | enabled="..." | |
[ name="..." ] /> | |
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 | |
class name, such as "mypackage.mymodule.myclass". If your class | |
constructor requires parameters, you may add them to the end of | |
the 'factory' attribute in parentheses. (Only positional | |
arguments are supported.) | |
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. | |
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 | |
factory="..." /> | |
<oid-generator | |
factory="..." /> | |
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. | |
Specify a fully-qualified class name. If your class constructor | |
requires parameters, you may add them to the end of the 'factory' | |
attribute in parentheses. (Only positional arguments are | |
supported.) | |
<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. | |
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. | |
<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 'extensions' attribute specifies filename extensions that | |
trigger this rule. Separate the extensions with a space. | |
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. | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment