1 package org.apache.anakia;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23
24 import org.jdom.Document;
25 import org.jdom.Element;
26
27 /**
28 * This class adds an entrypoint into XPath functionality,
29 * for Anakia.
30 * <p>
31 * All methods take a string XPath specification, along with
32 * a context, and produces a resulting java.util.List.
33 * <p>
34 * The W3C XPath Specification (http://www.w3.org/TR/xpath) refers
35 * to NodeSets repeatedly, but this implementation simply uses
36 * java.util.List to hold all Nodes. A 'Node' is any object in
37 * a JDOM object tree, such as an org.jdom.Element, org.jdom.Document,
38 * or org.jdom.Attribute.
39 * <p>
40 * To use it in Velocity, do this:
41 * <p>
42 * <pre>
43 * #set $authors = $xpath.applyTo("document/author", $root)
44 * #foreach ($author in $authors)
45 * $author.getValue()
46 * #end
47 * #set $chapterTitles = $xpath.applyTo("document/chapter/@title", $root)
48 * #foreach ($title in $chapterTitles)
49 * $title.getValue()
50 * #end
51 * </pre>
52 * <p>
53 * In newer Anakia builds, this class is obsoleted in favor of calling
54 * <code>selectNodes()</code> on the element directly:
55 * <pre>
56 * #set $authors = $root.selectNodes("document/author")
57 * #foreach ($author in $authors)
58 * $author.getValue()
59 * #end
60 * #set $chapterTitles = $root.selectNodes("document/chapter/@title")
61 * #foreach ($title in $chapterTitles)
62 * $title.getValue()
63 * #end
64 * </pre>
65 * <p>
66 *
67 * @author <a href="mailto:bob@werken.com">bob mcwhirter</a>
68 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
69 * @author <a href="mailto:szegedia@freemail.hu">Attila Szegedi</a>
70 * @version $Id: XPathTool.java 524478 2007-03-31 20:51:49Z wglass $
71 */
72 public class XPathTool
73 {
74 /**
75 * Constructor does nothing, as this is mostly
76 * just objectified static methods
77 */
78 public XPathTool()
79 {
80 // RuntimeSingleton.info("XPathTool::XPathTool()");
81 // intentionally left blank
82 }
83
84 /**
85 * Apply an XPath to a JDOM Document
86 *
87 * @param xpathSpec The XPath to apply
88 * @param doc The Document context
89 *
90 * @return A list of selected nodes
91 */
92 public NodeList applyTo(String xpathSpec,
93 Document doc)
94 {
95 //RuntimeSingleton.info("XPathTool::applyTo(String, Document)");
96 return new NodeList(XPathCache.getXPath(xpathSpec).applyTo( doc ), false);
97 }
98
99 /**
100 * Apply an XPath to a JDOM Element
101 *
102 * @param xpathSpec The XPath to apply
103 * @param elem The Element context
104 *
105 * @return A list of selected nodes
106 */
107 public NodeList applyTo(String xpathSpec,
108 Element elem)
109 {
110 //RuntimeSingleton.info("XPathTool::applyTo(String, Element)");
111 return new NodeList(XPathCache.getXPath(xpathSpec).applyTo( elem ), false);
112 }
113
114 /**
115 * Apply an XPath to a nodeset
116 *
117 * @param xpathSpec The XPath to apply
118 * @param nodeSet The nodeset context
119 *
120 * @return A list of selected nodes
121 */
122 public NodeList applyTo(String xpathSpec,
123 List nodeSet)
124 {
125 //RuntimeSingleton.info("XPathTool::applyTo(String, List)");
126 return new NodeList(XPathCache.getXPath(xpathSpec).applyTo( nodeSet ), false);
127 }
128 }
129
130
131