Multiple-AMQP Version Support in Qpid
This page describes an effort to allow multiple AMQP versions to be supported in the broker. This implies:
- that a broker will be able to accept a connection from clients requesting a variety of versions of the AMQ protocol;
- The versions to be supported in this manner are determined at compile time;
- A code generator generates the framing classes directly from the XML specification file(s), allowing generated classes to support any of the supported versions.
- Each of these classes need only the major and minor version numbers at instantiation to represent a frame from that protocol version.
The thinking behind the following generator description is described in AMQPVersion.1. Option 3 (Intelligent Generation) was selected for this implementation.
1. Current Generator Status
The Java generator is more-or-less complete and has been checked into subversion under the gentools directory for initial review. It has not been integrated into the Qpid project as yet; I would like to complete the C++ generation first. However, while the C++ work is in progress, the Java generator is available for review and comment. For instructions on installing and running, see the README file in the gentools directory.
2. Generator Description
2.1. Overview
The generator first reads in all the listed specification files and constructs from them a memory model (structure) of the specifications "superimposed" on top of each other so that the differences between them are easy to determine. A domain map (which maps all domain names to their simple domain types) is also constructed.
The generator then uses the model to perform code generation. This is achieved by using templates which contain the static parts of the code (which are simply reproduced) and in which are embedded tokens. These tokens, when encounted in the template, are passed on to the generator class, which then uses the context and model to generate specific the version-dependent sections of the code.
Both of these are discussed in more detail below.
2.2. AMQP verion model
The memory model has two parts - the domain map and the model (specification structure) itself.
Domain Map
The domain map is a two-level map. The lowest level maps the simple domain types to the AMQP versions in which they are defined. The upper level maps the domain names to the simple domain type.
In the following hypothetical example, the class-id domain is changed from short in v.0.8 to long in v.0.9, then back to short in v.0.10. The queue-type domain was introduced in v.0.10, while the redirected was removed in v0.9.
access-ticket --- shortstr --- V[0.8, 0.9, 0.10]
class-id -+------ short ------ V[0.8, 0.10]
+------ long ------- V[0.9]
queue-type ------ shortstr --- V[0.10]
redirected ------ bit -------- V[0.8]
A simplified version of the object model is as follows:
Specification Model
The specification model consists of a series of embedded maps in the same logical structure as the XML specification elements themsleves: the model contains a map of class maps; class maps contain field and method maps; method maps contain field maps. At the lowest level, there is a map to a set of AMQP versions.
The following illustrates a small portion of a model.
The Access class has an index of 30 for versions 0.8 - 0.10. The request method has index 10 in v.0.8 and 0.9, but was changed to 20 in v.0.10. This method has a active field in ordinal 1 and a realm field in ordinal 0 for all versions. The realm field is of domain path for version 0.8, but was changed to domain shortstr in versions 0.9 ans 0.10. NOTE: The domains in this model are the domain names, not the domain types. The Domain Map above is used to look up the domain type.
C Access -+---- I 30 ---------- V[0.8, 0.9, 0.10]
+---- M request -+-+- I 10 -------- V[0.8, 0.9]
| +- I 20 -------- V[0.10]
+-+- F active --+- O 1 ---------- V[0.8, 0.9, 0.10]
| +- D bit -------- V[0.8, 0.9, 0.10]
+- F realm -+--- O 0 ---------- V[0.8, 0.9, 0.10]
+-+- D path ------- V[0.8]
+- D shortstr --- V[0.9, 0.10]
C = class; M = method; F = field; D = domain name; I = index; O = ordinal; V = version(s)
An ordinal is the index number of a field implied by its relative position in the XML specification file. The first field in a class or method has ordinal 0, the second ordinal 1, etc.
A simplified version of the object model is as follows:
Generation
The Generator itself consists of a template passer and large number of code-generating methods for handling the various tokens that are embedded in the templates.
Templates contain three types of tokens:
- Filename tokens, which determine the name of the file to be generated;
- Simple Class/Method/Field replacement tokens in which the name of these elements are used to replace the token (e.g. "${CLASS}${METHOD}Body" becomes "BasicConsumeBody");
- List tokens, in which a code snippet is generated once for each item in the list. A second token on the same line determines the code snippet that will be generated. The list tokens cannot be combined or embedded within each other. There are four list tokens:
- %{VLIST} which generates once per version;
- %{CLIST} which generates once per class;
- %{MLIST} which generates once per method;
- %{FLIST} which generates once per field.
3. Code Generation
3.1. Difference Modes
The following changes may take place between one version and the next:
- Addition of classes, methods, fields or domains;
- Deletion of classes, methods, fields or domains;
- Modification of field domains or domain types;
- Modification of the ordinal position of fields;
- Modification of the index of classes or methods;
3.2 Java Generation
3.2.1. MethodBody classes
MethodBody classes here.
3.2.2. PropertyContentHeader classes
PropertyContentHeader classes here.
3.2.3. Registry classes
Registry classes here.
3.3. C++ Generation
Watch this space...
