001: package org.apache.velocity.anakia;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.util.List;
023:
024: import org.jdom.Document;
025: import org.jdom.Element;
026:
027: /**
028: * This class adds an entrypoint into XPath functionality,
029: * for Anakia.
030: * <p>
031: * All methods take a string XPath specification, along with
032: * a context, and produces a resulting java.util.List.
033: * <p>
034: * The W3C XPath Specification (http://www.w3.org/TR/xpath) refers
035: * to NodeSets repeatedly, but this implementation simply uses
036: * java.util.List to hold all Nodes. A 'Node' is any object in
037: * a JDOM object tree, such as an org.jdom.Element, org.jdom.Document,
038: * or org.jdom.Attribute.
039: * <p>
040: * To use it in Velocity, do this:
041: * <p>
042: * <pre>
043: * #set $authors = $xpath.applyTo("document/author", $root)
044: * #foreach ($author in $authors)
045: * $author.getValue()
046: * #end
047: * #set $chapterTitles = $xpath.applyTo("document/chapter/@title", $root)
048: * #foreach ($title in $chapterTitles)
049: * $title.getValue()
050: * #end
051: * </pre>
052: * <p>
053: * In newer Anakia builds, this class is obsoleted in favor of calling
054: * <code>selectNodes()</code> on the element directly:
055: * <pre>
056: * #set $authors = $root.selectNodes("document/author")
057: * #foreach ($author in $authors)
058: * $author.getValue()
059: * #end
060: * #set $chapterTitles = $root.selectNodes("document/chapter/@title")
061: * #foreach ($title in $chapterTitles)
062: * $title.getValue()
063: * #end
064: * </pre>
065: * <p>
066: *
067: * @author <a href="mailto:bob@werken.com">bob mcwhirter</a>
068: * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
069: * @author <a href="mailto:szegedia@freemail.hu">Attila Szegedi</a>
070: * @version $Id: XPathTool.java 463298 2006-10-12 16:10:32Z henning $
071: */
072: public class XPathTool {
073: /**
074: * Constructor does nothing, as this is mostly
075: * just objectified static methods
076: */
077: public XPathTool() {
078: // RuntimeSingleton.info("XPathTool::XPathTool()");
079: // intentionally left blank
080: }
081:
082: /**
083: * Apply an XPath to a JDOM Document
084: *
085: * @param xpathSpec The XPath to apply
086: * @param doc The Document context
087: *
088: * @return A list of selected nodes
089: */
090: public NodeList applyTo(String xpathSpec, Document doc) {
091: //RuntimeSingleton.info("XPathTool::applyTo(String, Document)");
092: return new NodeList(
093: XPathCache.getXPath(xpathSpec).applyTo(doc), false);
094: }
095:
096: /**
097: * Apply an XPath to a JDOM Element
098: *
099: * @param xpathSpec The XPath to apply
100: * @param elem The Element context
101: *
102: * @return A list of selected nodes
103: */
104: public NodeList applyTo(String xpathSpec, Element elem) {
105: //RuntimeSingleton.info("XPathTool::applyTo(String, Element)");
106: return new NodeList(XPathCache.getXPath(xpathSpec)
107: .applyTo(elem), false);
108: }
109:
110: /**
111: * Apply an XPath to a nodeset
112: *
113: * @param xpathSpec The XPath to apply
114: * @param nodeSet The nodeset context
115: *
116: * @return A list of selected nodes
117: */
118: public NodeList applyTo(String xpathSpec, List nodeSet) {
119: //RuntimeSingleton.info("XPathTool::applyTo(String, List)");
120: return new NodeList(XPathCache.getXPath(xpathSpec).applyTo(
121: nodeSet), false);
122: }
123: }
|