/
faq.xml
220 lines (176 loc) · 9.12 KB
/
faq.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
<?xml version="1.0"?>
<document url="https://www.cafeconleche.org/jaxen/faq.xml">
<properties>
<author email="bob.mcwhirter@redhat.com">bob mcwhirter</author>
<title>FAQ</title>
</properties>
<body>
<title>Frequently Asked Questions</title>
<section name="What is jaxen?">
<p>
The <code>jaxen</code> project is a Java XPath 1.0 Engine.
<code>jaxen</code> is a universal object model walker, capable of evaluating
XPath expressions across multiple models. Currently supported
are <a href="https://dom4j.github.io/">dom4j</a>, <a href="http://jdom.org">JDOM</a>, and DOM.
</p>
</section>
<section name="What is the jaxen license?">
<p>We use the <a nref='https://opensource.org/licenses/BSD-2-Clause'>BSD 2-clause license</a>, also known as the simplified BSD license. This is one of the least
restrictive licenses. You can use <code>jaxen</code> to create new products
without them having to be open source.
</p>
</section>
<section name="Why is jaxen useful?">
<p>
After implementing an XPath engine for both <a href="http://dom4j.org">dom4j</a> and
<a href="http://jdom.org">JDOM</a>, and attempting to keep them both in sync, it was
decided that factoring out the commonality would be a Good Thing. Thus, <code>jaxen</code>
provides a single point for XPath expression evaluation, regardless of the target
object model, whether its <strong>dom4j</strong>, <strong>JDOM</strong>, <strong>DOM</strong>,
<strong>XOM</strong>, <strong>JavaBeans</strong>,
or what not.
</p>
</section>
<section name="Why is jaxen better than [some other XPath technology]">
<p>
<code>jaxen</code> is better than <code>werken.xpath</code> specifically because it better
handles XPath expressions, and syntax error reporting. Additionally, since
jaxen is a unified code-base, developer effort isn't split between maintaining
the <strong>dom4j</strong> version and the <strong>JDOM</strong> version. More hands working on
the same project reduces bug count.
</p>
<p>
<code>jaxen</code> may be perceived to be better than other XPath technologies since it
provides a single cohesive API for evaluating XPaths against multiple object
models. Learn the <code>jaxen</code> API, and apply it to <strong>dom4j</strong>, <strong>JDOM</strong>,
<strong>XOM</strong> or <strong>DOM</strong> trees in exactly the same way.
</p>
<p>
Also, since <code>jaxen</code> works against an adaptor which provides InfoSet access
to arbitrary object models, it should be possible to build even larger
tools in terms of <code>jaxen</code>, to work with multiple models. For example, an
<strong>XQL</strong> engine could be developed, which would automagically work with
all models already supported by <code>jaxen</code>.
</p>
</section>
<section name="What are some related technologies?">
<p>
<code>jaxen</code> itself is based upon SAXPath, which is
an event-based model for parsing XPath expressions.
</p>
</section>
<section name="Which version of XPath does jaxen support? Does jaxen support XPath 2?">
<p>
<code>jaxen</code> supports XPath 1.0. It does not support XPath 2.0.
XPath 2.0 is a very different spec with many things to recommend it and a
few things not to like as well. However XPath 2.0 is not compatible with XPath 1.0.
It is far from a simple upgrade from XPath 1.0. It has a very different data model,
that might well require significant revisions to <code>jaxen</code>'s internal data structures,
and possibly a very different API as well.
</p>
<p>
The current release plan focuses exclusively on XPath 1.0 compatibility.
Perhaps one day someone will make a branch or fork of <code>jaxen</code>
that supports XPath 2. However, this would be a significant undertaking,
and so far little interest in this has been shown.
</p>
</section>
<section name="How do I support a different object model?">
<p>
The only thing required is an implementation of the interface
<code>org.jaxen.Navigator</code>. Not all of the interface is required,
and a default implementation, in the form of <code>org.jaxen.DefaultNavigator</code>
is also provided.
</p>
<p>
Since many of the XPath axes can be defined in terms of each other (for example,
the <code>ancestor</code> axis is merely a the <code>parent</code> recursively
applied), only a few low-level axis iterators are required to initially get
started. Of course, you may implement them directly, instead of relying upon
<code>jaxen</code>'s composition ability.
</p>
</section>
<section name="Is jaxen only good for XPath evaluation?">
<p>
No.
</p>
<p>
The <code>DocumentNavigators</code> provided with <code>jaxen</code> can be used
by themselves, without the XPath evaluation engine, to provide univeral
access to many object models for other technologies.
</p>
</section>
<section name="Who uses jaxen?">
<p>
<code>jaxen</code> has been embedded directly into <strong>dom4j</strong> and
<strong><a href="https://xom.nu/">XOM</a></strong> to provide
easy XPath evaluation directly from your documents. Additionally, it's
being integrated into David Megginson's
<a href="https://newsml-toolkit.sourceforge.net/">NewsML Framework</a>.
Tom Copeland's <a href="https://pmd.github.io/">PMD</a> static code analyzer uses jaxen to query Java code structures using XPath.
</p>
</section>
<section name="How do I write a query for namespace qualified elements/attributes in Jaxen?">
<p>
The XPath expression that selects elements or attributes in a namespace
looks exactly the same as it does in any other XPath context; that is, use prefixed names where the
prefixes are bound to the namespace URIs. For example,
</p>
<p><code>/pre:bar/@xlink:href</code></p>
<p>
However, because a Java program is not an XML document, it is also necessary to
bind the prefixes to the appropriate namespace URIs through a <code>NamespaceContext</code> object.
For example, this code sets up and then executes the above query:
</p>
<pre> XPath xpath = new DOMXPath("/foo:bar/@xlink:href", nav);
SimpleNamespaceContext nsContext = new SimpleNamespaceContext();
nsContext.addNamespace("pre", "http://www.foo.org/");
nsContext.addNamespace("xlink", "http://www.w3.org/1999/xlink");
xpath.setNamespaceContext(nsContext);
List result = contextpath.selectNodes(document);</pre>
<p>
As a shortcut, you can simply add a namespace binding
to the XPath expression's current context using the
<code>addNamespace</code> method:
</p>
<pre> XPath xpath = new DOMXPath("/pre:root");
xpath.addNamespace("pre", "http://www.example.org/");
List result = xpath.selectNodes(root);</pre>
<p>
If the namespace context does not contain a binding for a prefix that is used in
the XPath expression, an <code>UnresolvableException</code>
(a subclass of <code>JaxenException</code>
is thrown when you attempt
to evaluate it.
</p>
</section>
<section name="How do I write a query for namespace qualified elements/attributes in the default namespace?">
<p>
The same way you do for elements and attributes that
are in prefixed namespaces. That is, you use a prefix in the XPath expression and bind
the prefix to the namespace URI. You do this even if the document you're querying
uses unprefixed namespaced qualified names. In XPath 1.0, all unprefixed names are unqualified.
There is no requirement that the prefixes used in the XPath expression are the same as the prefixes used in the
document being queried. Only the namespace URIs need to match, not the prefixes.
</p>
<p>For example, this code fragment queries the document
<code><![CDATA[[<root xmlns="http://www.example.org/"/>]]></code> using the XPath expression
<code>/pre:root</code>:
</p>
<pre> Element root = doc.createElementNS("http://www.example.org/", "root");
doc.appendChild(root);
XPath xpath = new DOMXPath("/pre:root");
SimpleNamespaceContext context = new SimpleNamespaceContext();
context.addNamespace("pre", "http://www.example.org/");
xpath.setNamespaceContext(context);
List result = xpath.selectNodes(root);</pre>
<p>Alternately, using the shortcut:
</p>
<pre> Element root = doc.createElementNS("http://www.example.org/", "root");
doc.appendChild(root);
XPath xpath = new DOMXPath("/pre:root");
xpath.addNamespace("pre", "http://www.example.org/");
List result = xpath.selectNodes(root);</pre>
</section>
</body>
</document>