← Back to branch summary

~svn/ubuntu/oneiric/subversion/ppa

« back to all changes in this revision

Viewing changes to neon/doc/xml.xml

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2006-12-13 17:57:16 UTC
  • mfrom: (1.1.6 upstream) (0.1.3 etch)
  • Revision ID: james.westby@ubuntu.com-20061213175716-2ysv6z4w5dpa2r2f
Tags: 1.4.2dfsg1-2ubuntu1
* Merge with Debian unstable; remaining changes:
  - Create pot file on build.

Show diffs side-by-side

added added

removed removed

Lines of Context:
neon/doc/xml.xml
1
 
<!-- neon XML interface -*- text -*- -->
2
 
 
3
 
<sect1 id="xml">
4
 
 
5
 
  <title>Parsing XML</title>
6
 
 
7
 
  <para>The &neon; XML interface is exposed by the
8
 
  <filename>ne_xml.h</filename> header file.  This interface gives a
9
 
  wrapper around the standard <ulink
10
 
  url="http://www.saxproject.org/">SAX</ulink> API used by XML
11
 
  parsers, with an additional abstraction, <firstterm>stacked SAX
12
 
  handlers</firstterm>, and also giving consistent <ulink
13
 
  url="http://www.w3.org/TR/REC-xml-names">XML Namespace</ulink> support.</para>
14
 
 
15
 
<sect2 id="xml-sax">
16
 
  <title>Introduction to SAX</title>
17
 
 
18
 
  <para>A SAX-based parser works by emitting a sequence of
19
 
  <firstterm>events</firstterm> to reflect the tokens being parsed
20
 
  from the XML document.  For example, parsing the following document
21
 
  fragment:
22
 
 
23
 
<programlisting><![CDATA[
24
 
<hello>world</hello>
25
 
]]></programlisting>
26
 
 
27
 
  results in the following events:
28
 
 
29
 
  <orderedlist>
30
 
    <listitem>
31
 
      <simpara>&startelm; "hello"</simpara>
32
 
    </listitem>
33
 
    <listitem>
34
 
      <simpara>&cdata; "world"</simpara>
35
 
    </listitem>
36
 
    <listitem>
37
 
      <simpara>&endelm; "hello"</simpara>
38
 
    </listitem>
39
 
  </orderedlist>
40
 
 
41
 
  This example demonstrates the three event types used used in the
42
 
  subset of SAX exposed by the &neon; XML interface: &startelm;,
43
 
  &cdata; and &endelm;.  In a C API, an <quote>event</quote> is
44
 
  implemented as a function callback; three callback types are used in
45
 
  &neon;, one for each type of event.</para>
46
 
 
47
 
</sect2>
48
 
 
49
 
<sect2 id="xml-stacked">
50
 
  <title>Stacked SAX handlers</title>
51
 
 
52
 
  <para>WebDAV property values are represented as fragments of XML,
53
 
  transmitted as parts of larger XML documents over HTTP (notably in
54
 
  the body of the response to a <literal>PROPFIND</literal> request).
55
 
  When &neon; parses such documents, the SAX events generated for
56
 
  these property value fragments may need to be handled by the
57
 
  application, since &neon; has no knowledge of the structure of
58
 
  properties used by the application.</para>
59
 
 
60
 
  <para>To solve this problem<footnote><para>This
61
 
  <quote>problem</quote> only needs solving because the SAX interface
62
 
  is so inflexible when implemented as C function callbacks; a better
63
 
  approach would be to use an XML parser interface which is not based
64
 
  on callbacks.</para></footnote> the &neon; XML interface introduces
65
 
  the concept of a <firstterm>SAX handler</firstterm>.  A SAX handler
66
 
  comprises a &startelm;, &cdata; and &endelm; callback; the
67
 
  &startelm; callback being defined such that each handler may
68
 
  <emphasis>accept</emphasis> or <emphasis>decline</emphasis> the
69
 
  &startelm; event.  Handlers are composed into a <firstterm>handler
70
 
  stack</firstterm> before parsing a document.  When a new &startelm;
71
 
  event is generated by the XML parser, &neon; invokes each &startelm;
72
 
  callback in the handler stack in turn until one accepts the event.
73
 
  The handler which accepts the event will then be subsequently be
74
 
  passed &cdata; events if the element contains character data,
75
 
  followed by an &endelm; event when the element is closed.  If no
76
 
  handler in the stack accepts a &startelm; event, the branch of the
77
 
  tree is ignored.</para>
78
 
 
79
 
  <para>To illustrate, given a handler A, which accepts the
80
 
  <literal>cat</literal> and <literal>age</literal> elements, and a
81
 
  handler B, which accepts the <literal>name</literal> element, the
82
 
  following document:
83
 
 
84
 
<example id="xml-example">
85
 
<title>An example XML document</title>
86
 
<programlisting><![CDATA[
87
 
<cat>
88
 
  <age>3</age>    
89
 
  <name>Bob</name>
90
 
</cat>
91
 
]]></programlisting></example>
92
 
 
93
 
  would be parsed as follows:
94
 
  
95
 
  <orderedlist>
96
 
    <listitem>
97
 
      <simpara>A &startelm; "cat" &rarr; <emphasis>accept</emphasis></simpara>
98
 
    </listitem>
99
 
    <listitem>
100
 
      <simpara>A &startelm; "age" &rarr; <emphasis>accept</emphasis></simpara>
101
 
    </listitem>
102
 
    <listitem>
103
 
      <simpara>A &cdata; "3"</simpara>
104
 
    </listitem>
105
 
    <listitem>
106
 
      <simpara>A &endelm; "age"</simpara>
107
 
    </listitem>
108
 
    <listitem>
109
 
      <simpara>A &startelm; "name" &rarr; <emphasis>decline</emphasis></simpara>
110
 
    </listitem>
111
 
    <listitem>
112
 
      <simpara>B &startelm; "name" &rarr; <emphasis>accept</emphasis></simpara>
113
 
    </listitem>
114
 
    <listitem>
115
 
      <simpara>B &cdata; "Bob"</simpara>
116
 
    </listitem>
117
 
    <listitem>
118
 
      <simpara>B &endelm; "name"</simpara>
119
 
    </listitem>
120
 
    <listitem>
121
 
      <simpara>A &endelm; "cat"</simpara>
122
 
    </listitem>
123
 
  </orderedlist></para>
124
 
 
125
 
  <para>The search for a handler which will accept a &startelm; event
126
 
  begins at the handler of the parent element and continues toward the
127
 
  top of the stack.  For the root element, it begins at the base of
128
 
  the stack.  In the above example, handler A is at the base, and
129
 
  handler B at the top; if the <literal>name</literal> element had any
130
 
  children, only B's &startelm; would be invoked to accept
131
 
  them.</para>
132
 
 
133
 
</sect2>
134
 
 
135
 
<sect2 id="xml-state">
136
 
  <title>Maintaining state</title>
137
 
 
138
 
  <para>To facilitate communication between independent handlers, a
139
 
  <firstterm>state integer</firstterm> is associated with each element
140
 
  being parsed.  This integer is returned by &startelm; callback and
141
 
  is passed to the subsequent &cdata; and &endelm; callbacks
142
 
  associated with the element.  The state integer of the parent
143
 
  element is also passed to each &startelm; callback, the value zero
144
 
  used for the root element (which by definition has no
145
 
  parent).</para>
146
 
 
147
 
  <para>To further extend <xref linkend="xml-example"/>: if handler A
148
 
  defines that the state of the root element <sgmltag>cat</sgmltag>
149
 
  will be <literal>42</literal>, the event trace would be as
150
 
  follows:
151
 
 
152
 
  <orderedlist>
153
 
    <listitem>
154
 
      <simpara>A &startelm; (parent = 0, "cat") &rarr;
155
 
      <emphasis>accept</emphasis>, state = 42
156
 
      </simpara>
157
 
    </listitem>
158
 
    <listitem>
159
 
      <simpara>A &startelm; (parent = 42, "age") &rarr; 
160
 
      <emphasis>accept</emphasis>, state = 50
161
 
      </simpara>
162
 
    </listitem>
163
 
    <listitem>
164
 
      <simpara>A &cdata; (state = 50, "3")</simpara>
165
 
    </listitem>
166
 
    <listitem>
167
 
      <simpara>A &endelm; (state = 50, "age")</simpara>
168
 
    </listitem>
169
 
    <listitem>
170
 
      <simpara>A &startelm; (parent = 42, "name") &rarr; 
171
 
      <emphasis>decline</emphasis></simpara>
172
 
    </listitem>
173
 
    <listitem>
174
 
      <simpara>B &startelm; (parent = 42, "name") &rarr;
175
 
      <emphasis>accept</emphasis>, state = 99</simpara>
176
 
    </listitem>
177
 
    <listitem>
178
 
      <simpara>B &cdata; (state = 99, "Bob")</simpara>
179
 
    </listitem>
180
 
    <listitem>
181
 
      <simpara>B &endelm; (state = 99, "name")</simpara>
182
 
    </listitem>
183
 
    <listitem>
184
 
      <simpara>A &endelm; (state = 42, "cat")</simpara>
185
 
    </listitem>
186
 
  </orderedlist></para>
187
 
 
188
 
  <para>To avoid collisions between state integers used by different
189
 
  handlers, the interface definition of any handler includes the range
190
 
  of integers it will use.</para>
191
 
 
192
 
</sect2>
193
 
 
194
 
<sect2 id="xml-ns">
195
 
  <title>XML namespaces</title>
196
 
 
197
 
  <para>To support XML namespaces, every element name is represented
198
 
  as a <emphasis>(namespace, name)</emphasis> pair.  The &startelm;
199
 
  and &endelm; callbacks are passed namespace and name strings
200
 
  accordingly.  If an element in the XML document has no declared
201
 
  namespace, the namespace given will be the empty string,
202
 
  <literal>""</literal>.</para>
203
 
 
204
 
</sect2>
205
 
 
206
 
</sect1>