View Javadoc

1   package org.apache.velocity.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 463298 2006-10-12 16:10:32Z henning $
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