diff options
| author | arved <arved@unknown> | 2002-03-17 17:24:10 +0000 |
|---|---|---|
| committer | arved <arved@unknown> | 2002-03-17 17:24:10 +0000 |
| commit | e817266a9f7d1b0579839cc2383fe988ab5c3bc8 (patch) | |
| tree | 01977c8281b32489adbee64edf7125fbe47b0245 /docs/design/alt.design | |
| parent | 63636d3149af05ddc01e8ac38a5d794c36c7af53 (diff) | |
| download | xmlgraphics-fop-e817266a9f7d1b0579839cc2383fe988ab5c3bc8.tar.gz xmlgraphics-fop-e817266a9f7d1b0579839cc2383fe988ab5c3bc8.zip | |
Extra design commentary
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194703 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs/design/alt.design')
41 files changed, 1273 insertions, 0 deletions
diff --git a/docs/design/alt.design/AbsolutePosition.dia b/docs/design/alt.design/AbsolutePosition.dia Binary files differnew file mode 100644 index 000000000..a2d6421a3 --- /dev/null +++ b/docs/design/alt.design/AbsolutePosition.dia diff --git a/docs/design/alt.design/AbsolutePosition.png b/docs/design/alt.design/AbsolutePosition.png Binary files differnew file mode 100644 index 000000000..ed8a3691b --- /dev/null +++ b/docs/design/alt.design/AbsolutePosition.png diff --git a/docs/design/alt.design/AbsolutePosition.png.xml b/docs/design/alt.design/AbsolutePosition.png.xml new file mode 100644 index 000000000..7b2cde0bc --- /dev/null +++ b/docs/design/alt.design/AbsolutePosition.png.xml @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id: AbsolutePosition.png.xml,v 1.1 2002-01-05 14:46:32+10 pbw +Exp pbw $ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> +<document> + <header> + <title>AbsolutePosition diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Properties$AbsolutePosition"> + <figure src="AbsolutePosition.png" alt="AbsolutePosition diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/BorderCommonStyle.png b/docs/design/alt.design/BorderCommonStyle.png Binary files differnew file mode 100644 index 000000000..67cc9f8ee --- /dev/null +++ b/docs/design/alt.design/BorderCommonStyle.png diff --git a/docs/design/alt.design/BorderCommonStyle.png.xml b/docs/design/alt.design/BorderCommonStyle.png.xml new file mode 100644 index 000000000..f57865bc2 --- /dev/null +++ b/docs/design/alt.design/BorderCommonStyle.png.xml @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> +<document> + <header> + <title>BorderCommonStyle diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Properties$BorderCommonStyle"> + <figure src="BorderCommonStyle.png" alt="BorderCommonStyle diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/PropNames.dia b/docs/design/alt.design/PropNames.dia Binary files differnew file mode 100644 index 000000000..81db6a0c9 --- /dev/null +++ b/docs/design/alt.design/PropNames.dia diff --git a/docs/design/alt.design/PropNames.png b/docs/design/alt.design/PropNames.png Binary files differnew file mode 100644 index 000000000..8287e0875 --- /dev/null +++ b/docs/design/alt.design/PropNames.png diff --git a/docs/design/alt.design/PropNames.png.xml b/docs/design/alt.design/PropNames.png.xml new file mode 100644 index 000000000..829509d8b --- /dev/null +++ b/docs/design/alt.design/PropNames.png.xml @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>..fo.PropNames diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="PropNames.class"> + <figure src="PropNames.png" alt="PropNames.class diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/Properties.dia b/docs/design/alt.design/Properties.dia Binary files differnew file mode 100644 index 000000000..25d482d5d --- /dev/null +++ b/docs/design/alt.design/Properties.dia diff --git a/docs/design/alt.design/Properties.png b/docs/design/alt.design/Properties.png Binary files differnew file mode 100644 index 000000000..10da5f23c --- /dev/null +++ b/docs/design/alt.design/Properties.png diff --git a/docs/design/alt.design/Properties.png.xml b/docs/design/alt.design/Properties.png.xml new file mode 100644 index 000000000..f2a53578c --- /dev/null +++ b/docs/design/alt.design/Properties.png.xml @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>..fo.Properties diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Properties.class"> + <figure src="Properties.png" alt="Properties.class diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/PropertyClasses.dia b/docs/design/alt.design/PropertyClasses.dia Binary files differnew file mode 100644 index 000000000..5a02f6780 --- /dev/null +++ b/docs/design/alt.design/PropertyClasses.dia diff --git a/docs/design/alt.design/PropertyClasses.png b/docs/design/alt.design/PropertyClasses.png Binary files differnew file mode 100644 index 000000000..e58ca94bf --- /dev/null +++ b/docs/design/alt.design/PropertyClasses.png diff --git a/docs/design/alt.design/PropertyConsts.dia b/docs/design/alt.design/PropertyConsts.dia Binary files differnew file mode 100644 index 000000000..ed30cc6bc --- /dev/null +++ b/docs/design/alt.design/PropertyConsts.dia diff --git a/docs/design/alt.design/PropertyConsts.png b/docs/design/alt.design/PropertyConsts.png Binary files differnew file mode 100644 index 000000000..b6df72f84 --- /dev/null +++ b/docs/design/alt.design/PropertyConsts.png diff --git a/docs/design/alt.design/PropertyConsts.png.xml b/docs/design/alt.design/PropertyConsts.png.xml new file mode 100644 index 000000000..73d509cae --- /dev/null +++ b/docs/design/alt.design/PropertyConsts.png.xml @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> +<document> + <header> + <title>..fo.PropertyConsts diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="PropertyConsts.class"> + <figure src="PropertyConsts.png" alt="PropertyConsts.class diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/PropertyStaticsOverview.dia b/docs/design/alt.design/PropertyStaticsOverview.dia Binary files differnew file mode 100644 index 000000000..2ef800725 --- /dev/null +++ b/docs/design/alt.design/PropertyStaticsOverview.dia diff --git a/docs/design/alt.design/PropertyStaticsOverview.png b/docs/design/alt.design/PropertyStaticsOverview.png Binary files differnew file mode 100644 index 000000000..fdda19e74 --- /dev/null +++ b/docs/design/alt.design/PropertyStaticsOverview.png diff --git a/docs/design/alt.design/SAXParsing.dia b/docs/design/alt.design/SAXParsing.dia Binary files differnew file mode 100644 index 000000000..74a525ecf --- /dev/null +++ b/docs/design/alt.design/SAXParsing.dia diff --git a/docs/design/alt.design/SAXParsing.png b/docs/design/alt.design/SAXParsing.png Binary files differnew file mode 100644 index 000000000..f2652e1f7 --- /dev/null +++ b/docs/design/alt.design/SAXParsing.png diff --git a/docs/design/alt.design/VerticalAlign.dia b/docs/design/alt.design/VerticalAlign.dia Binary files differnew file mode 100644 index 000000000..519715a1a --- /dev/null +++ b/docs/design/alt.design/VerticalAlign.dia diff --git a/docs/design/alt.design/VerticalAlign.png b/docs/design/alt.design/VerticalAlign.png Binary files differnew file mode 100644 index 000000000..860d5bdff --- /dev/null +++ b/docs/design/alt.design/VerticalAlign.png diff --git a/docs/design/alt.design/VerticalAlign.png.xml b/docs/design/alt.design/VerticalAlign.png.xml new file mode 100644 index 000000000..6ff21bb00 --- /dev/null +++ b/docs/design/alt.design/VerticalAlign.png.xml @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>VerticalAlign diagram</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Properties$VerticalAlign"> + <figure src="VerticalAlign.png" alt="VerticalAlign diagram"/> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/XML-event-buffer.dia b/docs/design/alt.design/XML-event-buffer.dia Binary files differnew file mode 100644 index 000000000..ec8b131f6 --- /dev/null +++ b/docs/design/alt.design/XML-event-buffer.dia diff --git a/docs/design/alt.design/XML-event-buffer.png b/docs/design/alt.design/XML-event-buffer.png Binary files differnew file mode 100644 index 000000000..4ee16e913 --- /dev/null +++ b/docs/design/alt.design/XML-event-buffer.png diff --git a/docs/design/alt.design/XMLEventQueue.dia b/docs/design/alt.design/XMLEventQueue.dia Binary files differnew file mode 100644 index 000000000..6a39a3734 --- /dev/null +++ b/docs/design/alt.design/XMLEventQueue.dia diff --git a/docs/design/alt.design/XMLEventQueue.png b/docs/design/alt.design/XMLEventQueue.png Binary files differnew file mode 100644 index 000000000..477abd79a --- /dev/null +++ b/docs/design/alt.design/XMLEventQueue.png diff --git a/docs/design/alt.design/alt.properties.xml b/docs/design/alt.design/alt.properties.xml new file mode 100644 index 000000000..a0bb5ef6c --- /dev/null +++ b/docs/design/alt.design/alt.properties.xml @@ -0,0 +1,167 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> +<document> + <header> + <title>Implementing Properties</title> + <authors> + <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="An alternative properties implementation"> + <note> + The following discussion focusses on the relationship between + Flow Objects in the Flow Object tree, and properties. There + is no (or only passing) discussion of the relationship between + properties and traits, and by extension, between properties + and the Area tree. The discussion is illustrated with some + pseudo-UML diagrams. + </note> + <p> + Property handling is complex and expensive. Varying numbers of + properties apply to individual Flow Objects + <strong>(FOs)</strong> in the <strong>FO + tree </strong> but any property may effectively be + assigned a value on any element of the tree. If that property + is inheritable, its defined value will then be available to + any children of the defining FO. + </p> + <note> + <em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong> + ...The inheritable properties can be placed on any formatting + object. + </note> + <p> + Even if the value is not inheritable, it may be accessed by + its children through the <code>inherit</code> keyword or the + <code>from-parent()</code> core function, and potentially by + any of its descendents through the + <code>from-nearest-specified-value()</code> core function. + </p> + <p> + In addition to the assigned values of properties, almost every + property has an <strong>initial value</strong> which is used + when no value has been assigned. + </p> + <s2 title="The history problem"> + </s2> + <p> + The difficulty and expense of handling properties comes from + this univeral inheritance possibility. The list of properties + which are assigned values on any particular <em>FO</em> + element will not generally be large, but a current value is + required for each property which applies to the <em>FO</em> + being processed. + </p> + <p> + The environment from which these values may be selected + includes, for each <em>FO</em>, for each applicable property, + the value assigned on this <em>FO</em>, the value which + applied to the parent of this <em>FO</em>, the nearest value + specified on an ancestor of this element, and the initial + value of the property. + </p> + <s2 title="Data requirement and structure"> + <p> + This determines the minimum set of properties and associated + property value assignments that is necessary for the + processing of any individual <em>FO</em>. Implicit in this + set is the set of properties and associated values, + effective on the current <em>FO</em>, that were assigned on + that <em>FO</em>. + </p> + <p> + This minimum requirement - the initial value, the + nearest ancestor specified value, the parent computed value + and the value assigned to the current element - + suggests a stack implementation. + </p> + </s2> + <s2 title="Stack considerations"> + <p> + One possibility is to push to the stack only a minimal set + of required elements. When a value is assigned, the + relevant form or forms of that value (specified, computed, + actual) are pushed onto the stack. As long as each + <em>FO</em> maintains a list of the properties which were + assigned from it, the value can be popped when the focus of + FO processing retreats back up the <em>FO</em> tree. + </p> + <p> + The complication is that, for elements which are not + automatically inherited, when an <em>FO</em> is encountered + which does <strong>not</strong> assign a value to the + property, the initial value must either be already at the + top of the stack or be pushed onto the stack. + </p> + <p> + As a first approach, the simplest procedure may be to push a + current value onto the stack for every element - initial + values for non-inherited properties and the parental value + otherwise. Then perform any processing of assigned values. + This simplifies program logic at what is hopefully a small + cost in memory and processing time. It may be tuned in a + later iteration. + </p> + <s3 title="Stack implementation"> + <p> + Initial attempts at this implementation have used + <code>LinkedList</code>s as the stacks, on the assumption + that + </p> + <sl> + <!-- one of (dl sl ul ol li) --> + <li>random access would not be required</li> + <li> + pushing and popping of list elements requires nearly + constant (low) time + </li> + <li> no penalty for first addition to an empty list</li> + <li>efficient access to both bottom and top of stack</li> + </sl> + <p> + However, it may be required to perform stack access + operations from an arbitrary place on the stack, in which + case it would probably be more efficient to use + <code>ArrayList</code>s instead. + </p> + </s3> + </s2> + <s2 title="Class vs instance"> + <p> + An individual stack would contain values for a particular + property, and the context of the stack is the property class + as a whole. The property instances would be represented by + the individual values on the stack. If properties are to be + represented as instantiations of the class, the stack + entries would presumably be references to, or at least + referenced from, individual property objects. However, the + most important information about individual property + instances is the value assigned, and the relationship of + this property object to its ancestors and its descendents. + Other information would include the ownership of a property + instance by a particular <em>FO</em>, and, in the other + direction, the membership of the property in the set of + properties for which an <em>FO</em> has defined values. + </p> + <p> + In the presence of a stack, however, none of this required + information mandates the instantiation of properties. All + of the information mentioned so far can be effectively + represented by a stack position and a link to an + <em>FO</em>. If the property stack is maintained in + parallel with a stack of <em>FOs</em>, even that link is + implicit in the stack position. + </p> + </s2> + <p> + <strong>Next:</strong> <link href= "classes-overview.html" + >property classes overview.</link> + </p> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/book.xml b/docs/design/alt.design/book.xml new file mode 100644 index 000000000..5ae28c1f9 --- /dev/null +++ b/docs/design/alt.design/book.xml @@ -0,0 +1,21 @@ +<?xml version="1.0"?> + +<book title="FOP New Design Notes" copyright="2001-2002 The Apache Software Foundation"> + <external href="http://xml.apache.org/fop/" label="About FOP"/> + <separator/> + <external href="../index.html" label="NEW DESIGN" /> + <separator/> + <page id="index" label="alt.properties" source="alt.properties.xml"/> + <page id="classes-overview" label="Classes overview" source="classes-overview.xml"/> + <page id="properties-classes" label="Properties classes" source="properties-classes.xml"/> + <page id="Properties" label="Properties" source="Properties.png.xml"/> + <page id="PropertyConsts" label="PropertyConsts" source="PropertyConsts.png.xml"/> + <page id="PropNames" label="PropNames" source="PropNames.png.xml"/> + <page id="AbsolutePosition" label="AbsolutePosition" source="AbsolutePosition.png.xml"/> + <page id="VerticalAlign" label="VerticalAlign" source="VerticalAlign.png.xml"/> + <page id="BorderCommonStyle" label="BorderCommonStyle" source="BorderCommonStyle.png.xml"/> + <separator/> + <page id="xml-parsing" label="XML parsing" source="xml-parsing.xml"/> + <separator/> + <page id="property-parsing" label="Property parsing" source="propertyExpressions.xml"/> +</book> diff --git a/docs/design/alt.design/classes-overview.xml b/docs/design/alt.design/classes-overview.xml new file mode 100644 index 000000000..fab8e921d --- /dev/null +++ b/docs/design/alt.design/classes-overview.xml @@ -0,0 +1,201 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>Property classes overview</title> + <authors> + <person id="pbw" name="Peter B. West" + email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Classes overview"> + <s2 title="The class of all properties"> + <p> + If individual properties can have a "virtual reality" on the + stack, where is the stack itself to be instantiated? One + possibility is to have the stacks as <code>static</code> + data structures within the individual property classes. + However, the reduction of individual property instances to + stack entries allows the possibility of further + virtualization of property classes. If the individual + properties can be represented by an integer, i.e. a + <code>static final int</code>, the set of individual + property stacks can be collected together into one array. + Where to put such an overall collection? Creating an + über-class to accommodate everything that applies to + property classes as a whole allows this array to be defined + as a <em><code>static final</code> something[]</em>. + </p> + </s2> + <s2 title="The overall property classes"> + <p> + This approach has been taken for the experimental code. + Rather than simply creating a overall class containing + common elements of properties and acting as a superclass, + advantage has been taken of the facility for nesting of + top-level classes. All of the individual property classes + are nested within the <code>Properties</code> class. + This has advantages and disadvantages. + </p> + <dl> + <dt>Disadvantages</dt> + <dd> + The file becomes extremely cumbersome. This can cause + problems with "intelligent" editors. E.g. + <em>XEmacs</em> syntax highlighting virtually grinds to a + halt with the current version of this file.<br/> <br/> + + Possible problems with IDEs. There may be speed problems + or even overflow problems with various IDEs. The current + version of this and related files had only been tried with + the <em>[X]Emacs JDE</em> environment, without difficulties + apart from the editor speed problems mentioned + above.<br/> <br/> + + Retro look and feel. Not the done Java thing.<br/> <br/> + </dd> + <dt>Advantages</dt> + <dd> + Everything to do with properties in the one place (more or + less.)<br/> <br/> + + Eliminates the need for a large part of the (sometimes) + necessary evil of code generation. The One Big File of + <code>foproperties.xml</code>, with its ancillary xsl, is + absorbed into the One Bigger File of + <code>Properties.java</code>. The huge advantage of this + is that it <strong>is</strong> Java. + </dd> + </dl> + </s2> + <s2 title="The property information classes"> + <p> + In fact, in order to keep the size of the file down to more + a more manageable level, the property information classes of + static data and methods have been split tentatively into + three: + </p> + <figure src="PropertyStaticsOverview.png" alt="Top level + property classes"/> + <dl> + <dt><link href="PropNames.html">PropNames</link></dt> + <dd> + Contains an array, <code>propertyNames</code>, of the names of + all properties, and a set of enumeration constants, one + for each property name in the <code>PropertyNames</code> + array. These constants index the name of the properties + in <code>propertyNames</code>, and must be manually kept in + sync with the entries in the array. (This was the last of + the classes split off from the original single class; + hence the naming tiredness.) + <br/> <br/> + </dd> + <dt><link href="PropertyConsts.html">PropertyConsts</link></dt> + <dd> + Contains two basic sets of data:<br/> + Property-indexed arrays and property set + definitions.<br/> <br/> + + <strong>Property-indexed arrays</strong> are elaborations + of the property indexing idea discussed in relation to the + arrays of property stacks. One of the arrays is<br/> <br/> + + <code>public static final LinkedList[] + propertyStacks</code><br/> <br/> + + This is an array of stacks, implemented as + <code>LinkedList</code>s, one for each property.<br/> <br/> + + The other arrays provide indexed access to fields which + are, in most cases, common to all of the properties. An + exception is<br/> <br/> + + <code>public static final Method[] + complexMethods</code><br/> <br/> + + which contains a reference to the method + <code>complex()</code> which is only defined for + properties which have complex value parsing requirements. + It is likely that a similar array will be defined for + properties which allow a value of <em>auto</em>.<br/> <br/> + + The property-indexed arrays are initialized by + <code>static</code> initializers in this class. The + <code>PropNames</code> class and + <code>Properties</code> + nested classes are scanned in order to obtain or derive + the data necessary for initialization.<br/> <br/> + + <strong>Property set definitions</strong> are + <code>HashSet</code>s of properties (represented by + integer constants) which belong to each of the categories + of properties defined. They are used to simplify the + assignment of property sets to individual FOs. + Representative <code>HashSet</code>s include + <em>backgroundProps</em> and + <em>tableProps</em>.<br/> <br/> + </dd> + <dt><link href="Properties.html">Properties</link></dt> + <dd> + <br/> + This class contains only sets of constants for use by the + individual property classes, but it also importantly + serves as a container for all of the property classes, and + some convenience pseudo-property classes.<br/> <br/> + + <strong>Constants sets</strong> include:<br/> <br/> + + <em>Datatype constants</em>. A bitmap set of + integer constants over a possible range of 2^0 to 2^31 + (represented as -2147483648). E.g.<br/> + INTEGER = 1<br/> + ENUM = 524288<br/> <br/> + Some of the definitions are bit-ORed + combinations of the basic values. Used to set the + <em>dataTypes</em> field of the property + classes.<br/> <br/> + + <em>Trait mapping constants</em>. A bitmap set of + integer constants over a possible range of 2^0 to 2^31 + (represented as -2147483648), representing the manner in + which a property maps into a <em>trait</em>. Used to set + the <code>traitMapping</code> field of the property + classes.<br/> <br/> + + <em>Initial value constants</em>. A sequence of + integer constants representing the datatype of the initial + value of a property. Used to set the + <code>initialValueType</code> field of the property + classes.<br/> <br/> + + <em>Inheritance value constants</em>. A sequence + of integer constants representing the way in which the + property is normally inherited. Used to set the + <code>inherited</code> field of the property + classes.<br/> <br/> + + <strong>Nested property classes</strong>. The + <em>Properties</em> class serves as the holding pen for + all of the individual property classes, and for property + pseudo-classes which contain data common to a number of + actual properties, e.g. <em>ColorCommon</em>. + </dd> + </dl> + </s2> + <p> + <strong>Previous:</strong> <link href= + "alt.properties.html" >alt.properties</link> + </p> + <p> + <strong>Next:</strong> <link href= + "properties-classes.html" >Properties classes</link> + </p> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/dirlist.html b/docs/design/alt.design/dirlist.html new file mode 100644 index 000000000..6a4cf9ddd --- /dev/null +++ b/docs/design/alt.design/dirlist.html @@ -0,0 +1,55 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> + <head> + <title>alt.design</title> + </head> + <body> + <h3>Directory listing of alt.design</h3> + <hr> + <pre><code> +drwxrwxr-x 2 pbw pbw 4096 Jan 31 17:58 . +drwxrwxr-x 5 pbw pbw 4096 Jan 31 17:57 <a href="../dirlist.html">..</a> +-rw-rw-r-- 1 pbw pbw 949 Jan 25 17:31 <a href="AbsolutePosition.dia">AbsolutePosition.dia</a> +-rw-rw-r-- 1 pbw pbw 4890 Jan 25 17:31 <a href="AbsolutePosition.png">AbsolutePosition.png</a> +-rw-r--r-- 1 pbw pbw 579 Jan 25 23:47 <a href="AbsolutePosition.png.xml">AbsolutePosition.png.xml</a> +-rw-rw-r-- 1 pbw pbw 4140 Jan 25 17:31 <a href="BorderCommonStyle.png">BorderCommonStyle.png</a> +-rw-r--r-- 1 pbw pbw 584 Jan 26 12:29 <a href="BorderCommonStyle.png.xml">BorderCommonStyle.png.xml</a> +-rw-rw-r-- 1 pbw pbw 807 Jan 25 17:31 <a href="PropNames.dia">PropNames.dia</a> +-rw-rw-r-- 1 pbw pbw 3428 Jan 25 17:31 <a href="PropNames.png">PropNames.png</a> +-rw-r--r-- 1 pbw pbw 551 Jan 25 23:48 <a href="PropNames.png.xml">PropNames.png.xml</a> +-rw-rw-r-- 1 pbw pbw 1900 Jan 25 17:31 <a href="Properties.dia">Properties.dia</a> +-rw-rw-r-- 1 pbw pbw 32437 Jan 25 17:31 <a href="Properties.png">Properties.png</a> +-rw-r--r-- 1 pbw pbw 556 Jan 25 23:48 <a href="Properties.png.xml">Properties.png.xml</a> +-rw-rw-r-- 1 pbw pbw 2180 Jan 25 17:31 <a href="PropertyClasses.dia">PropertyClasses.dia</a> +-rw-rw-r-- 1 pbw pbw 17581 Jan 25 17:31 <a href="PropertyClasses.png">PropertyClasses.png</a> +-rw-rw-r-- 1 pbw pbw 1573 Jan 25 17:31 <a href="PropertyConsts.dia">PropertyConsts.dia</a> +-rw-rw-r-- 1 pbw pbw 20379 Jan 25 17:31 <a href="PropertyConsts.png">PropertyConsts.png</a> +-rw-r--r-- 1 pbw pbw 575 Jan 25 23:47 <a href="PropertyConsts.png.xml">PropertyConsts.png.xml</a> +-rw-rw-r-- 1 pbw pbw 1333 Jan 25 17:31 <a href="PropertyStaticsOverview.dia">PropertyStaticsOverview.dia</a> +-rw-rw-r-- 1 pbw pbw 7503 Jan 25 17:31 <a href="PropertyStaticsOverview.png">PropertyStaticsOverview.png</a> +-rw-rw-r-- 1 pbw pbw 3068 Jan 25 17:31 <a href="SAXParsing.dia">SAXParsing.dia</a> +-rw-rw-r-- 1 pbw pbw 24482 Jan 25 17:31 <a href="SAXParsing.png">SAXParsing.png</a> +-rw-rw-r-- 1 pbw pbw 964 Jan 25 17:31 <a href="VerticalAlign.dia">VerticalAlign.dia</a> +-rw-rw-r-- 1 pbw pbw 7091 Jan 25 17:31 <a href="VerticalAlign.png">VerticalAlign.png</a> +-rw-r--r-- 1 pbw pbw 565 Jan 25 23:48 <a href="VerticalAlign.png.xml">VerticalAlign.png.xml</a> +-rw-rw-r-- 1 pbw pbw 2004 Jan 25 17:31 <a href="XML-event-buffer.dia">XML-event-buffer.dia</a> +-rw-rw-r-- 1 pbw pbw 20415 Jan 25 17:31 <a href="XML-event-buffer.png">XML-event-buffer.png</a> +-rw-rw-r-- 1 pbw pbw 2322 Jan 25 17:31 <a href="XMLEventQueue.dia">XMLEventQueue.dia</a> +-rw-rw-r-- 1 pbw pbw 11643 Jan 25 17:31 <a href="XMLEventQueue.png">XMLEventQueue.png</a> +-rw-r--r-- 1 pbw pbw 6584 Jan 26 11:56 <a href="alt.properties.xml">alt.properties.xml</a> +-rw-rw-r-- 1 pbw pbw 1152 Jan 25 17:31 <a href="book.xml">book.xml</a> +-rw-r--r-- 1 pbw pbw 7834 Jan 26 13:07 <a href="classes-overview.xml">classes-overview.xml</a> +-rw-rw-r-- 1 pbw pbw 8330 Jan 25 17:31 <a href="parserPersistence.png">parserPersistence.png</a> +-rw-rw-r-- 1 pbw pbw 1974 Jan 25 17:31 <a href="processPlumbing.dia">processPlumbing.dia</a> +-rw-rw-r-- 1 pbw pbw 8689 Jan 25 17:31 <a href="processPlumbing.png">processPlumbing.png</a> +-rw-r--r-- 1 pbw pbw 5123 Jan 26 11:58 <a href="properties-classes.xml">properties-classes.xml</a> +-rw-rw-r-- 1 pbw pbw 3115 Jan 25 17:31 <a href="property-super-classes-full.dia">property-super-classes-full.dia</a> +-rw-rw-r-- 1 pbw pbw 89360 Jan 25 17:31 <a href="property-super-classes-full.png">property-super-classes-full.png</a> +-rw-r--r-- 1 pbw pbw 10221 Jan 25 23:49 <a href="propertyExpressions.xml">propertyExpressions.xml</a> +-rw-r--r-- 1 pbw pbw 9361 Jan 26 11:59 <a href="xml-parsing.xml">xml-parsing.xml</a> +-rw-rw-r-- 1 pbw pbw 2655 Jan 25 17:31 <a href="xmlevent-queue.dia">xmlevent-queue.dia</a> +-rw-rw-r-- 1 pbw pbw 12326 Jan 25 17:31 <a href="xmlevent-queue.png">xmlevent-queue.png</a> + </code></pre> + <hr> + </body> +</html> diff --git a/docs/design/alt.design/parserPersistence.png b/docs/design/alt.design/parserPersistence.png Binary files differnew file mode 100644 index 000000000..342a933b4 --- /dev/null +++ b/docs/design/alt.design/parserPersistence.png diff --git a/docs/design/alt.design/processPlumbing.dia b/docs/design/alt.design/processPlumbing.dia Binary files differnew file mode 100644 index 000000000..184e51524 --- /dev/null +++ b/docs/design/alt.design/processPlumbing.dia diff --git a/docs/design/alt.design/processPlumbing.png b/docs/design/alt.design/processPlumbing.png Binary files differnew file mode 100644 index 000000000..182d3c68e --- /dev/null +++ b/docs/design/alt.design/processPlumbing.png diff --git a/docs/design/alt.design/properties-classes.xml b/docs/design/alt.design/properties-classes.xml new file mode 100644 index 000000000..216f2b9e0 --- /dev/null +++ b/docs/design/alt.design/properties-classes.xml @@ -0,0 +1,140 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>Properties$classes</title> + <authors> + <person name="Peter B. West" email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="fo.Properties and the nested properties classes"> + <figure src="PropertyClasses.png" alt="Nested property and + top-level classes"/> + <s2 title="Nested property classes"> + <p> + Given the intention that individual properties have only a + <em>virtual</em> instantiation in the arrays of + <code>PropertyConsts</code>, these classes are intended to + remain as repositories of static data and methods. The name + of each property is entered in the + <code>PropNames.propertyNames</code> array of + <code>String</code>s, and each has a unique integer constant + defined, corresponding to the offset of the property name in + that array. + </p> + <s3 title="Fields common to all classes"> + <dl> + <dt><code>final int dataTypes</code></dt> + <dd> + This field defines the allowable data types which may be + assigned to the property. The value is chosen from the + data type constants defined in <code>Properties</code>, and + may consist of more than one of those constants, + bit-ORed together. + </dd> + <dt><code>final int traitMapping</code></dt> + <dd> + This field defines the mapping of properties to traits + in the <code>Area tree</code>. The value is chosen from the + trait mapping constants defined in <code>Properties</code>, + and may consist of more than one of those constants, + bit-ORed together. + </dd> + <dt><code>final int initialValueType</code></dt> + <dd> + This field defines the data type of the initial value + assigned to the property. The value is chosen from the + initial value type constants defined in + <code>Properties</code>. + </dd> + <dt><code>final int inherited</code></dt> + <dd> + This field defines the kind of inheritance applicable to + the property. The value is chosen from the inheritance + constants defined in <code>Properties</code>. + </dd> + </dl> + </s3> + <s3 title="Datatype dependent fields"> + <dl> + <dt>Enumeration types</dt> + <dd> + <strong><code>final String[] enums</code></strong><br/> + This array contains the <code>NCName</code> text + values of the enumeration. In the current + implementation, it always contains a null value at + <code>enum[0]</code>.<br/> <br/> + + <strong><code>final String[] + enumValues</code></strong><br/> When the number of + enumeration values is small, + <code>enumValues</code> is a reference to the + <code>enums</code> array.<br/> <br/> + + <strong><code>final HashMap + enumValues</code></strong><br/> When the number of + enumeration values is larger, + <code>enumValues</code> is a + <code>HashMap</code> statically initialized to + contain the integer constant values corresponding to + each text value, indexed by the text + value.<br/> <br/> + + <strong><code>final int</code></strong> + <em><code>enumeration-constants</code></em><br/> A + unique integer constant is defined for each of the + possible enumeration values.<br/> <br/> + </dd> + <dt>Many types: + <code>final</code> <em>datatype</em> + <code>initialValue</code></dt> + <dd> + When the initial datatype does not have an implicit + initial value (as, for example, does type + <code>AUTO</code>) the initial value for the property is + assigned to this field. The type of this field will + vary according to the <code>initialValueType</code> + field. + </dd> + <dt>AUTO: <code>PropertyValueList auto(property, + list)></code></dt> + <dd> + When <em>AUTO</em> is a legal value type, the + <code>auto()</code> method must be defined in the property + class.<br/> + <em>NOT YET IMPLEMENTED.</em> + </dd> + <dt>COMPLEX: <code>PropertyValueList complex(property, + list)></code></dt> + <dd> + <em>COMPLEX</em> is specified as a value type when complex + conditions apply to the selection of a value type, or + when lists of values are acceptable. To process and + validate such a property value assignment, the + <code>complex()</code> method must be defined in the + property class. + </dd> + </dl> + </s3> + </s2> + <s2 title="Nested property pseudo-classes"> + <p> + The property pseudo-classes are classes, like + <code>ColorCommon</code> which contain values, particularly + <em>enums</em>, which are common to a number of actual + properties. + </p> + </s2> + <p> + <strong>Previous:</strong> <link href= "classes-overview.html" + >property classes overview.</link> + </p> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/property-super-classes-full.dia b/docs/design/alt.design/property-super-classes-full.dia Binary files differnew file mode 100644 index 000000000..4fe8f750a --- /dev/null +++ b/docs/design/alt.design/property-super-classes-full.dia diff --git a/docs/design/alt.design/property-super-classes-full.png b/docs/design/alt.design/property-super-classes-full.png Binary files differnew file mode 100644 index 000000000..dea871d3c --- /dev/null +++ b/docs/design/alt.design/property-super-classes-full.png diff --git a/docs/design/alt.design/propertyExpressions.xml b/docs/design/alt.design/propertyExpressions.xml new file mode 100644 index 000000000..0900a323a --- /dev/null +++ b/docs/design/alt.design/propertyExpressions.xml @@ -0,0 +1,341 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>Property Expression Parsing</title> + <authors> + <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="Property expression parsing"> + <note> + The following discussion of the experiments with alternate + property expression parsing is very much a work in progress, + and subject to sudden changes. + </note> + <p> + The parsing of property value expressions is handled by two + closely related classes: <code>PropertyTokenizer</code> and its + subclass, <code>PropertyParser</code>. + <code>PropertyTokenizer</code>, as the name suggests, handles + the tokenizing of the expression, handing <em>tokens</em> + back to its subclass, + <code>PropertyParser</code>. <code>PropertyParser</code>, in + turn, returns a <code>PropertyValueList</code>, a list of + <code>PropertyValue</code>s. + </p> + <p> + The tokenizer and parser rely in turn on the datatype + definition from the <code>org.apache.fop.datatypes</code> + package and the datatype <code>static final int</code> + constants from <code>PropertyConsts</code>. + </p> + <s2 title="Data types"> + <p> + The data types currently defined in + <code>org.apache.fop.datatypes</code> include: + </p> + <table> + <tr><th colspan="2">Numbers and lengths</th></tr> + <tr> + <th>Numeric</th> + <td colspan="3"> + The fundamental numeric data type. <em>Numerics</em> of + various types are constructed by the classes listed + below. + </td> + </tr> + <tr> + <td/> + <th colspan="3">Constructor classes for <em>Numeric</em></th> + </tr> + <tr> + <td/><td>Angle</td> + <td colspan="2">In degrees(deg), gradients(grad) or + radians(rad)</td> + </tr> + <tr> + <td/><td>Ems</td> + <td colspan="2">Relative length in <em>ems</em></td> + </tr> + <tr> + <td/><td>Frequency</td> + <td colspan="2">In hertz(Hz) or kilohertz(kHz)</td> + </tr> + <tr> + <td/><td>IntegerType</td><td/> + </tr> + <tr> + <td/><td>Length</td> + <td colspan="2">In centimetres(cm), millimetres(mm), + inches(in), points(pt), picas(pc) or pixels(px)</td> + </tr> + <tr> + <td/><td>Percentage</td><td/> + </tr> + <tr> + <td/><td>Time</td> + <td>In seconds(s) or milliseconds(ms)</td> + </tr> + <tr><th colspan="2">Strings</th></tr> + <tr> + <th>StringType</th> + <td colspan="3"> + Base class for data types which result in a <em>String</em>. + </td> + </tr> + <tr> + <td/><th>Literal</th> + <td colspan="2"> + A subclass of <em>StringType</em> for literals which + exceed the constraints of an <em>NCName</em>. + </td> + </tr> + <tr> + <td/><th>MimeType</th> + <td colspan="2"> + A subclass of <em>StringType</em> for literals which + represent a mime type. + </td> + </tr> + <tr> + <td/><th>UriType</th> + <td colspan="2"> + A subclass of <em>StringType</em> for literals which + represent a URI, as specified by the argument to + <em>url()</em>. + </td> + </tr> + <tr> + <td/><th>NCName</th> + <td colspan="2"> + A subclass of <em>StringType</em> for literals which + meet the constraints of an <em>NCName</em>. + </td> + </tr> + <tr> + <td/><td/><th>Country</th> + <td>An RFC 3066/ISO 3166 country code.</td> + </tr> + <tr> + <td/><td/><th>Language</th> + <td>An RFC 3066/ISO 639 language code.</td> + </tr> + <tr> + <td/><td/><th>Script</th> + <td>An ISO 15924 script code.</td> + </tr> + <tr><th colspan="2">Enumerated types</th></tr> + <tr> + <th>EnumType</th> + <td colspan="3"> + An integer representing one of the tokens in a set of + enumeration values. + </td> + </tr> + <tr> + <td/><th>MappedEnumType</th> + <td colspan="2"> + A subclass of <em>EnumType</em>. Maintains a + <em>String</em> with the value to which the associated + "raw" enumeration token maps. E.g., the + <em>font-size</em> enumeration value "medium" maps to + the <em>String</em> "12pt". + </td> + </tr> + <tr><th colspan="2">Colors</th></tr> + <tr> + <th>ColorType</th> + <td colspan="3"> + Maintains a four-element array of float, derived from + the name of a standard colour, the name returned by a + call to <em>system-color()</em>, or an RGB + specification. + </td> + </tr> + <tr><th colspan="2">Fonts</th></tr> + <tr> + <th>FontFamilySet</th> + <td colspan="3"> + Maintains an array of <em>String</em>s containing a + prioritized list of possibly generic font family names. + </td> + </tr> + <tr><th colspan="2">Pseudo-types</th></tr> + <tr> + <td colspan="4"> + A variety of pseudo-types have been defined as + convenience types for frequently appearing enumeration + token values, or for other special purposes. + </td> + </tr> + <tr> + <th>Inherit</th> + <td colspan="3"> + For values of <em>inherit</em>. + </td> + </tr> + <tr> + <th>Auto</th> + <td colspan="3"> + For values of <em>auto</em>. + </td> + </tr> + <tr> + <th>None</th> + <td colspan="3"> + For values of <em>none</em>. + </td> + </tr> + <tr> + <th>Bool</th> + <td colspan="3"> + For values of <em>true/false</em>. + </td> + </tr> + <tr> + <th>FromNearestSpecified</th> + <td colspan="3"> + Created to ensure that, when associated with + a shorthand, the <em>from-nearest-specified-value()</em> + core function is the sole component of the expression. + </td> + </tr> + <tr> + <th>FromParent</th> + <td colspan="3"> + Created to ensure that, when associated with + a shorthand, the <em>from-parent()</em> + core function is the sole component of the expression. + </td> + </tr> + </table> + </s2> + <s2 title="Tokenizer"> + <p> + The tokenizer returns one of the following token + values: + </p> + <source> + static final int + EOF = 0 + ,NCNAME = 1 + ,MULTIPLY = 2 + ,LPAR = 3 + ,RPAR = 4 + ,LITERAL = 5 + ,FUNCTION_LPAR = 6 + ,PLUS = 7 + ,MINUS = 8 + ,MOD = 9 + ,DIV = 10 + ,COMMA = 11 + ,PERCENT = 12 + ,COLORSPEC = 13 + ,FLOAT = 14 + ,INTEGER = 15 + ,ABSOLUTE_LENGTH = 16 + ,RELATIVE_LENGTH = 17 + ,TIME = 18 + ,FREQ = 19 + ,ANGLE = 20 + ,INHERIT = 21 + ,AUTO = 22 + ,NONE = 23 + ,BOOL = 24 + ,URI = 25 + ,MIMETYPE = 26 + // NO_UNIT is a transient token for internal use only. It is + // never set as the end result of parsing a token. + ,NO_UNIT = 27 + ; + </source> + <p> + Most of these tokens are self-explanatory, but a few need + further comment. + </p> + <dl> + <dt>AUTO</dt> + <dd> + Because of its frequency of occurrence, and the fact that + it is always the <em>initial value</em> for any property + which supports it, AUTO has been promoted into a + pseudo-type with its on datatype class. Therefore, it is + also reported as a token. + </dd> + <dt>NONE</dt> + <dd> + Similarly to AUTO, NONE has been promoted to a pseudo-type + because of its frequency. + </dd> + <dt>BOOL</dt> + <dd> + There is a <em>de facto</em> boolean type buried in the + enumeration types for many of the properties. It had been + specified as a type in its own right in this code. + </dd> + <dt>MIMETYPE</dt> + <dd> + The property <code>content-type</code> introduces this + complication. It can have two values of the form + <strong>content-type:</strong><em>mime-type</em> + (e.g. <code>content-type="content-type:xml/svg"</code>) or + <strong>namespace-prefix:</strong><em>prefix</em> + (e.g. <code>content-type="namespace-prefix:svg"</code>). The + experimental code reduces these options to the payload + in each case: an <code>NCName</code> in the case of a + namespace prefix, and a MIMETYPE in the case of a + content-type specification. <code>NCName</code>s cannot + contain a "/". + </dd> + </dl> + </s2> + <s2 title="Parser"> + <p> + The parser retuns a <code>PropertyValueList</code>, + necessary because of the possibility that a list of + <code>PropertyValue</code> elements may be returned from the + expressions of soem properties. + </p> + <p> + <code>PropertyValueList</code>s may contain + <code>PropertyValue</code>s or other + <code>PropertyValueList</code>s. This latter provision is + necessitated for the peculiar case of of + <em>text-shadow</em>, which may contain whitespace separated + sublists of either two or three elements, separated from one + another by commas. To accommodate this peculiarity, comma + separated elements are added to the top-level list, while + whitespace separated values are always collected into + sublists to be added to the top-level list. + </p> + <p> + Other special cases include the processing of the core + functions <code>from-parent()</code> and + <code>from-nearest-specified-value()</code> when these + function calls are assigned to a shorthand property, or used + with a shorthand property name as an argument. In these + cases, the function call must be the sole component of the + expression. The pseudo-element classes + <code>FromParent</code> and + <code>FromNearestSpecified</code> are generated in these + circumstances so that an exception will be thrown if they + are involved in expression evaluation with other + components. (See Rec. Section 5.10.4 Property Value + Functions.) + </p> + <p> + The experimental code is a simple extension of the existing + parser code, which itself borrowed heavily from James + Clark's XT processor. + </p> + </s2> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/xml-parsing.xml b/docs/design/alt.design/xml-parsing.xml new file mode 100644 index 000000000..3d83802ef --- /dev/null +++ b/docs/design/alt.design/xml-parsing.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- $Id$ --> +<!-- +<!DOCTYPE document SYSTEM "../xml-docs/dtd/document-v10.dtd"> +--> + +<document> + <header> + <title>Integrating XML Parsing</title> + <authors> + <person name="Peter B. West" email="pbwest@powerup.com.au"/> + </authors> + </header> + <body> + <!-- one of (anchor s1) --> + <s1 title="An alternative parser integration"> + <p> + This note proposes an alternative method of integrating the + output of the SAX parsing of the Flow Object (FO) tree into + FOP processing. The pupose of the proposed changes is to + provide for better decomposition of the process of analysing + and rendering an fo tree such as is represented in the output + from initial (XSLT) processing of an XML source document. + </p> + <s2 title="Structure of SAX parsing"> + <p> + Figure 1 is a schematic representation of the process of SAX + parsing of an input source. SAX parsing involves the + registration, with an object implementing the + <code>XMLReader</code> interface, of a + <code>ContentHandler</code> which contains a callback + routine for each of the event types encountered by the + parser, e.g., <code>startDocument()</code>, + <code>startElement()</code>, <code>characters()</code>, + <code>endElement()</code> and <code>endDocument()</code>. + Parsing is initiated by a call to the <code>parser()</code> + method of the <code>XMLReader</code>. Note that the call to + <code>parser()</code> and the calls to individual callback + methods are synchronous: <code>parser()</code> will only + return when the last callback method returns, and each + callback must complete before the next is called.<br/><br/> + <strong>Figure 1</strong> + </p> + <figure src="SAXParsing.png" alt="SAX parsing schematic"/> + <p> + In the process of parsing, the heirarchical structure of the + original FO tree is flattened into a number of streams of + events of the same type which are reported in the sequence + in which they are encountered. Apart from that, the API + imposes no structure or constraint which expresses the + relationship between, e.g., a startElement event and the + endElement event for the same element. To the extent that + such relationship information is required, it must be + managed by the callback routines. + </p> + <p> + The most direct approach here is to build the tree + "invisibly"; to bury within the callback routines the + necessary code to construct the tree. In the simplest case, + the whole of the FO tree is built within the call to + <code>parser()</code>, and that in-memory tree is subsequently + processed to (a) validate the FO structure, and (b) + construct the Area tree. The problem with this approach is + the potential size of the FO tree in memory. FOP has + suffered from this problem in the past. + </p> + </s2> + <s2 title="Cluttered callbacks"> + <p> + On the other hand, the callback code may become increasingly + complex as tree validation and the triggering of the Area + tree processing and subsequent rendering is moved into the + callbacks, typically the <code>endElement()</code> method. + In order to overcome acute memory problems, the FOP code was + recently modified in this way, to trigger Area tree building + and rendering in the <code>endElement()</code> method, when + the end of a page-sequence was detected. + </p> + <p> + The drawback with such a method is that it becomes difficult + to detemine the order of events and the circumstances in + which any particular processing events are triggered. When + the processing events are inherently self-contained, this is + irrelevant. But the more complex and context-dependent the + relationships are among the processing elements, the more + obscurity is engendered in the code by such "side-effect" + processing. + </p> + </s2> + <s2 title="From passive to active parsing"> + <p> + In order to solve the simultaneous problems of exposing the + structure of the processing and minimising in-memory + requirements, the experimental code separates the parsing of + the input source from the building of the FO tree and all + downstream processing. The callback routines become + minimal, consisting of the creation and buffering of + <code>XMLEvent</code> objects as a <em>producer</em>. All + of these objects are effectively merged into a single event + stream, in strict event order, for subsequent access by the + FO tree building process, acting as a + <em>consumer</em>. In itself, this does not reduce the + footprint. This occurs when the approach is generalised to + modularise FOP processing.<br/><br/> <strong>Figure 2</strong> + </p> + <figure src="XML-event-buffer.png" alt="XML event buffer"/> + <p> + The most useful change that this brings about is the switch + from <em>passive</em> to <em>active</em> XML element + processing. The process of parsing now becomes visible to + the controlling process. All local validation requirements, + all object and data structure building, is initiated by the + process(es) <em>get</em>ting from the queue - in the case + above, the FO tree builder. + </p> + </s2> + <s2 title="XMLEvent methods"> + <anchor id="XMLEvent-methods"/> + <p> + The experimental code uses a class <strong>XMLEvent</strong> + to provide the objects which are placed in the queue. + <em>XMLEvent</em> includes a variety of methods to access + elements in the queue. Namespace URIs encountered in + parsing are maintined in a <code>static</code> + <code>HashMap</code> where they are associated with a unique + integer index. This integer value is used in the signature + of some of the access methods. + </p> + <dl> + <dt>XMLEvent getEvent(SyncedCircularBuffer events)</dt> + <dd> + This is the basis of all of the queue access methods. It + returns the next element from the queue, which may be a + pushback element. + </dd> + <dt>XMLEvent getEndDocument(events)</dt> + <dd> + <em>get</em> and discard elements from the queue + until an ENDDOCUMENT element is found and returned. + </dd> + <dt> XMLEvent expectEndDocument(events)</dt> + <dd> + If the next element on the queue is an ENDDOCUMENT event, + return it. Otherwise, push the element back and throw an + exception. Each of the <em>get</em> methods (except + <em>getEvent()</em> itself) has a corresponding + <em>expect</em> method. + </dd> + <dt>XMLEvent get/expectStartElement(events)</dt> + <dd> Return the next STARTELEMENT event from the queue.</dd> + <dt>XMLEvent get/expectStartElement(events, String + qName)</dt> + <dd> + Return the next STARTELEMENT with a QName matching + <em>qName</em>. + </dd> + <dt> + XMLEvent get/expectStartElement(events, int uriIndex, + String localName) + </dt> + <dd> + Return the next STARTELEMENT with a URI indicated by the + <em>uriIndex</em> and a local name matching <em>localName</em>. + </dd> + <dt> + XMLEvent get/expectStartElement(events, LinkedList list) + </dt> + <dd> + <em>list</em> contains instances of the nested class + <code>UriLocalName</code>, which hold a + <em>uriIndex</em> and a <em>localName</em>. Return + the next STARTELEMENT with a URI indicated by the + <em>uriIndex</em> and a local name matching + <em>localName</em> from any element of + <em>list</em>. + </dd> + <dt>XMLEvent get/expectEndElement(events)</dt> + <dd>Return the next ENDELEMENT.</dd> + <dt>XMLEvent get/expectEndElement(events, qName)</dt> + <dd>Return the next ENDELEMENT with QName + <em>qname</em>.</dd> + <dt>XMLEvent get/expectEndElement(events, uriIndex, localName)</dt> + <dd> + Return the next ENDELEMENT with a URI indicated by the + <em>uriIndex</em> and a local name matching + <em>localName</em>. + </dd> + <dt> + XMLEvent get/expectEndElement(events, XMLEvent event) + </dt> + <dd> + Return the next ENDELEMENT with a URI matching the + <em>uriIndex</em> and <em>localName</em> + matching those in the <em>event</em> argument. This + is intended as a quick way to find the ENDELEMENT matching + a previously returned STARTELEMENT. + </dd> + <dt>XMLEvent get/expectCharacters(events)</dt> + <dd>Return the next CHARACTERS event.</dd> + </dl> + </s2> + <s2 title="FOP modularisation"> + <p> + This same principle can be extended to the other major + sub-systems of FOP processing. In each case, while it is + possible to hold a complete intermediate result in memory, + the memory costs of that approach are too high. The + sub-systems - xml parsing, FO tree construction, Area tree + construction and rendering - must run in parallel if the + footprint is to be kept manageable. By creating a series of + producer-consumer pairs linked by synchronized buffers, + logical isolation can be achieved while rates of processing + remain coupled. By introducing feedback loops conveying + information about the completion of processing of the + elements, sub-systems can dispose of or precis those + elements without having to be tightly coupled to downstream + processes.<br/><br/> + <strong>Figure 3</strong> + </p> + <figure src="processPlumbing.png" alt="FOP modularisation"/> + </s2> + </s1> + </body> +</document> diff --git a/docs/design/alt.design/xmlevent-queue.dia b/docs/design/alt.design/xmlevent-queue.dia Binary files differnew file mode 100644 index 000000000..91e752473 --- /dev/null +++ b/docs/design/alt.design/xmlevent-queue.dia diff --git a/docs/design/alt.design/xmlevent-queue.png b/docs/design/alt.design/xmlevent-queue.png Binary files differnew file mode 100644 index 000000000..0bb019c65 --- /dev/null +++ b/docs/design/alt.design/xmlevent-queue.png |
