dmitri 02/04/27 21:37:01 Modified: jxpath/xdocs users-guide.xml index.xml jxpath/src/test/org/apache/commons/jxpath JXPathTestCase.java jxpath/src/java/org/apache/commons/jxpath/ri JXPathContextReferenceImpl.java jxpath/src/java/org/apache/commons/jxpath JXPathContext.java JXPath.java Added: jxpath/src/java/org/apache/commons/jxpath/ri JXPathCompiledExpression.java jxpath/src/java/org/apache/commons/jxpath CompiledExpression.java Log: Added CompiledExpressions Revision Changes Path 1.4 +34 -5 jakarta-commons/jxpath/xdocs/users-guide.xml Index: users-guide.xml =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/xdocs/users-guide.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- users-guide.xml 21 Apr 2002 21:59:40 -0000 1.3 +++ users-guide.xml 28 Apr 2002 04:37:01 -0000 1.4 @@ -154,7 +154,7 @@ <subsection name="Retrieving Multiple Results"> <p> JXPath can retrieve multiple objects from a graph. Note that the method - called in this case is not <code>getValue</code>, but <code>eval</code>. + called in this case is not <code>getValue</code>, but <code>iterate</code>. </p> <source>   @@ -168,7 +168,7 @@ ... JXPathContext context = JXPathContext.newContext(auth); - List threeBooks = (List)context.eval("books[position() < 4]"); + Iterator threeBooks = context.iterate("books[position() < 4]"); </source> <p> This returns a list of at most three books from the array of all books @@ -543,7 +543,7 @@ </p> <source>   -Pointer ptr = context.locateValue("employees[$i]/addresses[$j]") +Pointer ptr = context.getPointer("employees[$i]/addresses[$j]") </source> <p> Let's say the value of the variable i is 1 and j = 3. @@ -820,11 +820,40 @@ JXPathContext context = JXPathContext.newContext(sharedContext, auth); - List javaBooks = (List)context. - eval("books[preprocessTitle(title) = $title]"); + Iterator javaBooks = + context.iterate("books[preprocessTitle(title) = $title]"); </source> </section> + +<section name="Compiled Expressions"> +<p> +When JXPath is asked to evaluate an expression for the first time, +it compiles it and caches its compiled representation. This mechanism +reduces the overhead caused by compilation. In some cases though, +JXPath's own caching may not be sufficient - JXPath caches have +limited size and they are cleared once in a while. +</p> +<p> +Here's how you can precompile an XPath expression: +</p> +<source> +   + CompiledExpression expr = context.compile(xpath); + ... + Object value = expr.getValue(context); +</source> +<p> +The following requirements can be addressed with compiled expressions: +</p> +<ul> + <li>There is a relatively small number of XPaths your application + works with, and it needs to evaluate those XPaths multiple times.</li> + <li>Some XPaths need to be precompiled at initialization time</li> + <li>The syntax of some XPaths needs to be checked before they are + used for the first time</li> +</ul> +</section> <section name="Customizing JXPath"> <p> 1.2 +8 -8 jakarta-commons/jxpath/xdocs/index.xml Index: index.xml =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/xdocs/index.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- index.xml 10 Apr 2002 03:40:21 -0000 1.1 +++ index.xml 28 Apr 2002 04:37:01 -0000 1.2 @@ -3,8 +3,8 @@ <properties> <title>Home</title> <author email="[EMAIL PROTECTED]">Commons Documentation Team</author> - <author email="[EMAIL PROTECTED]">Dmitri Plotnikov</author> - <revision>$Id: index.xml,v 1.1 2002/04/10 03:40:21 dmitri Exp $</revision> + <author email="[EMAIL PROTECTED]">Dmitri Plotnikov</author> + <revision>$Id: index.xml,v 1.2 2002/04/28 04:37:01 dmitri Exp $</revision> </properties> <body> @@ -18,10 +18,10 @@ <p> Consider this example: </p> - <blockquote><pre> -Address address = (Address)JXPath.getValue(vendor, - "locations[address/zipCode='90210']/address"); - </pre></blockquote> +<blockquote><pre> +Address address = (Address)JXPathContext.newContext(vendor). + getValue("locations[address/zipCode='90210']/address"); +</pre></blockquote> <p> This XPath expression is equvalent to the following Java code: </p> @@ -42,7 +42,7 @@ XPath was standardized by W3C and is used in both XSLT and XPointer. </p> <p> - If you want to find out more about XPath, a good place to start is + If you want to find out more about XPath, a good place to start is an excellent XPath Tutorial by <a href="http://www.w3schools.com/xpath">W3Schools</a> </p> <p> @@ -51,7 +51,7 @@ </p> <p> Primary applications of JXPath are in scripting: JSP and similar template/script based technologies. - However, programmers who like a more XML-flavored APIs, should consider JXPath as + However, programmers who prefer XML-flavored APIs, should consider JXPath as an alternative to other expression languages as well. JXPath is a must-have tool for those who work with mixtures of Java objects and XML and need to frequently traverse through graphs of those. 1.15 +39 -14 jakarta-commons/jxpath/src/test/org/apache/commons/jxpath/JXPathTestCase.java Index: JXPathTestCase.java =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/src/test/org/apache/commons/jxpath/JXPathTestCase.java,v retrieving revision 1.14 retrieving revision 1.15 diff -u -r1.14 -r1.15 --- JXPathTestCase.java 26 Apr 2002 03:28:37 -0000 1.14 +++ JXPathTestCase.java 28 Apr 2002 04:37:01 -0000 1.15 @@ -1,7 +1,7 @@ /* - * $Header: /home/cvs/jakarta-commons/jxpath/src/test/org/apache/commons/jxpath/JXPathTestCase.java,v 1.14 2002/04/26 03:28:37 dmitri Exp $ - * $Revision: 1.14 $ - * $Date: 2002/04/26 03:28:37 $ + * $Header: /home/cvs/jakarta-commons/jxpath/src/test/org/apache/commons/jxpath/JXPathTestCase.java,v 1.15 2002/04/28 04:37:01 dmitri Exp $ + * $Revision: 1.15 $ + * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 @@ -99,7 +99,7 @@ * </p> * * @author Dmitri Plotnikov - * @version $Revision: 1.14 $ $Date: 2002/04/26 03:28:37 $ + * @version $Revision: 1.15 $ $Date: 2002/04/28 04:37:01 $ */ public class JXPathTestCase extends TestCase @@ -330,12 +330,20 @@ private void testGetValue(JXPathContext context, String xpath, Object expected) { Object actual = context.getValue(xpath); assertEquals("Evaluating <" + xpath + ">", expected, actual); + + CompiledExpression expr = context.compile(xpath); + actual = expr.getValue(context); + assertEquals("Evaluating CE <" + xpath + ">", expected, actual); } private void testGetValue(JXPathContext context, String xpath, Object expected, Class requiredType) { Object actual = context.getValue(xpath, requiredType); assertEquals("Evaluating <" + xpath + ">", expected, actual); - } + + CompiledExpression expr = context.compile(xpath); + actual = expr.getValue(context, requiredType); + assertEquals("Evaluating CE <" + xpath + ">", expected, actual); + } /** * Test JXPath.eval() with various arguments @@ -349,8 +357,20 @@ } private void testEval(JXPathContext context, String xpath, Object expected) { - Object actual = context.eval(xpath); + Iterator it = context.iterate(xpath); + ArrayList actual = new ArrayList(); + while (it.hasNext()){ + actual.add(it.next()); + } assertEquals("Evaluating <" + xpath + ">", expected, actual); + + CompiledExpression expr = context.compile(xpath); + it = expr.iterate(context); + actual = new ArrayList(); + while (it.hasNext()){ + actual.add(it.next()); + } + assertEquals("Evaluating CE <" + xpath + ">", expected, actual); } public void testContextDependency(){ @@ -392,8 +412,8 @@ } private void testDocumentOrder(JXPathContext context, String path1, String path2, int expected){ - NodePointer np1 = (NodePointer)context.locateValue(path1); - NodePointer np2 = (NodePointer)context.locateValue(path2); + NodePointer np1 = (NodePointer)context.getPointer(path1); + NodePointer np2 = (NodePointer)context.getPointer(path2); int res = np1.compareTo(np2); if (res < 0){ res = -1; @@ -678,21 +698,26 @@ } else { if (xpath_tests[i].eval){ - List list = ctx.locate(xpath_tests[i].xpath); + Iterator it = ctx.iteratePointers(xpath_tests[i].xpath); List paths = new ArrayList(); - for (Iterator it = list.iterator(); it.hasNext();){ + while (it.hasNext()){ paths.add(((Pointer)it.next()).asPath()); } actual = paths; } else { - actual = ctx.locateValue(xpath_tests[i].xpath).asPath(); + actual = ctx.getPointer(xpath_tests[i].xpath).asPath(); } } } else { if (xpath_tests[i].eval){ - actual = ctx.eval(xpath_tests[i].xpath); + ArrayList list = new ArrayList(); + Iterator it = ctx.iterate(xpath_tests[i].xpath); + while (it.hasNext()){ + list.add(it.next()); + } + actual = list; } else { ctx.setLenient(xpath_tests[i].lenient); @@ -716,8 +741,8 @@ for (int i=0; i < xpath_tests.length; i++) { try { if (!xpath_tests[i].path && !xpath_tests[i].eval){ - Pointer ptr = ctx.locateValue(xpath_tests[i].xpath); - Pointer test = ctx.locateValue(ptr.asPath()); + Pointer ptr = ctx.getPointer(xpath_tests[i].xpath); + Pointer test = ctx.getPointer(ptr.asPath()); assertEquals("Testing pointer for <" + xpath_tests[i].xpath + ">", ptr.asPath(), test.asPath()); } } 1.14 +59 -66 jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathContextReferenceImpl.java Index: JXPathContextReferenceImpl.java =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathContextReferenceImpl.java,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- JXPathContextReferenceImpl.java 26 Apr 2002 03:28:37 -0000 1.13 +++ JXPathContextReferenceImpl.java 28 Apr 2002 04:37:01 -0000 1.14 @@ -1,7 +1,7 @@ /* - * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathContextReferenceImpl.java,v 1.13 2002/04/26 03:28:37 dmitri Exp $ - * $Revision: 1.13 $ - * $Date: 2002/04/26 03:28:37 $ + * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathContextReferenceImpl.java,v 1.14 2002/04/28 04:37:01 dmitri Exp $ + * $Revision: 1.14 $ + * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 @@ -84,7 +84,7 @@ * The reference implementation of JXPathContext. * * @author Dmitri Plotnikov - * @version $Revision: 1.13 $ $Date: 2002/04/26 03:28:37 $ + * @version $Revision: 1.14 $ $Date: 2002/04/28 04:37:01 $ */ public class JXPathContextReferenceImpl extends JXPathContext { @@ -146,8 +146,12 @@ public static NodePointerFactory[] getNodePointerFactories(){ return nodeFactoryArray; } + + public CompiledExpression compile(String xpath){ + return new JXPathCompiledExpression(xpath, compileExpression(xpath)); + } - private static Expression compile(String xpath){ + private static Expression compileExpression(String xpath){ Expression expr; if (useSoftCache){ expr = null; @@ -172,12 +176,10 @@ compiled.put(xpath, expr); } } -// } return expr; } private static void cleanupCache(){ -// System.gc(); Iterator it = compiled.entrySet().iterator(); while (it.hasNext()){ Map.Entry me = (Map.Entry)it.next(); @@ -193,8 +195,11 @@ * types are wrapped into objects. */ public Object getValue(String xpath){ -// System.err.println("XPATH: " + xpath); - Object result = eval(xpath, true); + return getValue(xpath, compileExpression(xpath)); + } + + public Object getValue(String xpath, Expression expr){ + Object result = getRootContext().eval(expr); if (result == null && !lenient){ throw new JXPathException("No value for xpath: " + xpath); } @@ -214,7 +219,12 @@ * and returns the result of the conversion. */ public Object getValue(String xpath, Class requiredType){ - Object value = getValue(xpath); + Expression expr = compileExpression(xpath); + return getValue(xpath, expr, requiredType); + } + + public Object getValue(String xpath, Expression expr, Class requiredType){ + Object value = getValue(xpath, expr); if (value != null && requiredType != null){ if (!TypeUtils.canConvert(value, requiredType)){ throw new JXPathException("Invalid expression type. '" + xpath + @@ -227,28 +237,24 @@ } /** - * Traverses the xpath and returns a List of objects. Even if - * there is only one object that matches the xpath, it will be returned - * as a collection with one element. If the xpath matches no properties - * in the graph, the List will be empty. + * Traverses the xpath and returns a Iterator of all results found + * for the path. If the xpath matches no properties + * in the graph, the Iterator will not be null. */ - public List eval(String xpath){ -// System.err.println("XPATH: " + xpath); - Object result = eval(xpath, false); - if (result instanceof EvalContext){ - return ((EvalContext)result).getValueList(); - } - else if (result instanceof Pointer){ - return Collections.singletonList(((Pointer)result).getValue()); - } - else { - return Collections.singletonList(result); - } + public Iterator iterate(String xpath){ + return iterate(xpath, compileExpression(xpath)); + } + + public Iterator iterate(String xpath, Expression expr){ + return getRootContext().iterate(expr); } - public Pointer locateValue(String xpath){ -// System.err.println("XPATH: " + xpath); - Object result = eval(xpath, true); + public Pointer getPointer(String xpath){ + return getPointer(xpath, compileExpression(xpath)); + } + + public Pointer getPointer(String xpath, Expression expr){ + Object result = getRootContext().eval(expr); if (result instanceof EvalContext){ result = ((EvalContext)result).getSingleNodePointer(); } @@ -260,11 +266,14 @@ } } - /** - */ public void setValue(String xpath, Object value){ + setValue(xpath, compileExpression(xpath), value); + } + + + public void setValue(String xpath, Expression expr, Object value){ try { - setValue(xpath, value, false); + setValue(xpath, expr, value, false); } catch (Throwable ex){ throw new JXPathException( @@ -272,12 +281,13 @@ } } - /** - */ public void createPath(String xpath, Object value){ -// System.err.println("CREATING XPATH: " + xpath); + createPath(xpath, compileExpression(xpath), value); + } + + public void createPath(String xpath, Expression expr, Object value){ try { - setValue(xpath, value, true); + setValue(xpath, expr, value, true); } catch (Throwable ex){ throw new JXPathException( @@ -285,8 +295,8 @@ } } - private void setValue(String xpath, Object value, boolean create){ - Object result = eval(xpath, true); + private void setValue(String xpath, Expression expr, Object value, boolean create){ + Object result = getRootContext().eval(expr); // System.err.println("RESULT: " + result); Pointer pointer = null; @@ -309,25 +319,20 @@ } } - public List locate(String xpath){ - Object result = eval(xpath, false); - if (result instanceof EvalContext){ - return ((EvalContext)result).getPointerList(); - } - else if (result instanceof Pointer){ - return Collections.singletonList((Pointer)result); - } - else { - return Collections.singletonList( - NodePointer.newNodePointer(null, result, getLocale())); - } + /** + * Traverses the xpath and returns an Iterator of Pointers. + * A Pointer provides easy access to a property. + * If the xpath matches no properties + * in the graph, the Iterator be empty, but not null. + */ + public Iterator iteratePointers(String xpath){ + return iteratePointers(xpath, compileExpression(xpath)); } - private Object eval(String xpath, boolean firstMatchLookup) { - Expression expr = compile(xpath); - return getRootContext().eval(expr, firstMatchLookup); + public Iterator iteratePointers(String xpath, Expression expr){ + return getRootContext().iteratePointers(expr); } - + private void printPointer(NodePointer pointer){ Pointer p = pointer; while (p != null){ @@ -349,18 +354,6 @@ private EvalContext getRootContext(){ return new RootContext(this, getRootPointer()); - } - - private List resolveNodeSet(List list){ - List result = new ArrayList(); - for (int i = 0; i < list.size(); i++){ - Object element = list.get(i); - if (element instanceof NodePointer){ - element = ((NodePointer)element).getNodeValue(); - } - result.add(element); - } - return result; } public NodePointer getVariablePointer(QName name){ 1.1 jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathCompiledExpression.java Index: JXPathCompiledExpression.java =================================================================== /* * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/ri/JXPathCompiledExpression.java,v 1.1 2002/04/28 04:37:01 dmitri Exp $ * $Revision: 1.1 $ * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 * * * Copyright (c) 1999-2001 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. The end-user documentation included with the redistribution, if * any, must include the following acknowlegement: * "This product includes software developed by the * Apache Software Foundation (http://www.apache.org/)." * Alternately, this acknowlegement may appear in the software itself, * if and wherever such third-party acknowlegements normally appear. * * 4. The names "The Jakarta Project", "Commons", and "Apache Software * Foundation" must not be used to endorse or promote products derived * from this software without prior written permission. For written * permission, please contact [EMAIL PROTECTED] * * 5. Products derived from this software may not be called "Apache" * nor may "Apache" appear in their names without prior written * permission of the Apache Group. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Apache Software Foundation. * For more information on the Apache Software Foundation, please see * <http://www.apache.org/>. */ package org.apache.commons.jxpath.ri; import java.util.Iterator; import org.apache.commons.jxpath.ri.compiler.Expression; import org.apache.commons.jxpath.CompiledExpression; import org.apache.commons.jxpath.JXPathContext; import org.apache.commons.jxpath.Pointer; /** * * * @author Dmitri Plotnikov * @version $Revision: 1.1 $ $Date: 2002/04/28 04:37:01 $ */ public class JXPathCompiledExpression implements CompiledExpression { private String xpath; private Expression expression; public JXPathCompiledExpression(String xpath, Expression expression){ this.xpath = xpath; this.expression = expression; } /** * @see CompiledExpression#getValue(JXPathContext) */ public Object getValue(JXPathContext context) { return ((JXPathContextReferenceImpl)context). getValue(xpath, expression); } /** * @see CompiledExpression#getValue(JXPathContext, Class) */ public Object getValue(JXPathContext context, Class requiredType) { return ((JXPathContextReferenceImpl)context). getValue(xpath, expression, requiredType); } /** * @see CompiledExpression#setValue(JXPathContext, Object) */ public void setValue(JXPathContext context, Object value) { ((JXPathContextReferenceImpl)context). setValue(xpath, expression, value); } /** * @see CompiledExpression#createPath(JXPathContext, Object) */ public void createPath(JXPathContext context, Object value) { ((JXPathContextReferenceImpl)context). createPath(xpath, expression, value); } /** * @see CompiledExpression#iterate(JXPathContext) */ public Iterator iterate(JXPathContext context) { return ((JXPathContextReferenceImpl)context). iterate(xpath, expression); } /** * @see CompiledExpression#getPointer(JXPathContext, String) */ public Pointer getPointer(JXPathContext context, String xpath) { return ((JXPathContextReferenceImpl)context). getPointer(xpath, expression); } /** * @see CompiledExpression#iteratePointers(JXPathContext) */ public Iterator iteratePointers(JXPathContext context) { return ((JXPathContextReferenceImpl)context). iteratePointers(xpath, expression); } } 1.7 +55 -16 jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPathContext.java Index: JXPathContext.java =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPathContext.java,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- JXPathContext.java 12 Apr 2002 02:28:06 -0000 1.6 +++ JXPathContext.java 28 Apr 2002 04:37:01 -0000 1.7 @@ -1,7 +1,7 @@ /* - * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPathContext.java,v 1.6 2002/04/12 02:28:06 dmitri Exp $ - * $Revision: 1.6 $ - * $Date: 2002/04/12 02:28:06 $ + * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPathContext.java,v 1.7 2002/04/28 04:37:01 dmitri Exp $ + * $Revision: 1.7 $ + * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 @@ -61,8 +61,7 @@ */ package org.apache.commons.jxpath; -import java.util.List; -import java.util.Locale; +import java.util.*; /** * JXPathContext provides APIs for the traversal of graphs of JavaBeans using @@ -405,7 +404,7 @@ * Also see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0 </a> * * @author Dmitri Plotnikov - * @version $Revision: 1.6 $ $Date: 2002/04/12 02:28:06 $ + * @version $Revision: 1.7 $ $Date: 2002/04/28 04:37:01 $ */ public abstract class JXPathContext { protected JXPathContext parentContext; @@ -538,6 +537,15 @@ } /** + * Compiles the supplied XPath and returns an internal representation + * of the path that can then be evaluated. Use CompiledExpressions + * when you need to evaluate the same expression multiple times + * and there is a convenient place to cache CompiledExpression + * between invocations. + */ + public abstract CompiledExpression compile(String xpath); + + /** * Evaluates the xpath and returns the resulting object. Primitive * types are wrapped into objects. */ @@ -576,26 +584,57 @@ public abstract void createPath(String xpath, Object value); /** - * Traverses the xpath and returns a List of objects. Even if - * there is only one object that matches the xpath, it will be returned - * as a collection with one element. If the xpath matches no properties - * in the graph, the List will be empty. + * @deprecated Please use iterate + */ + public List eval(String xpath){ + ArrayList list = new ArrayList(); + Iterator it = iterate(xpath); + while (it.hasNext()){ + list.add(it.next()); + } + return list; + } + + /** + * Traverses the xpath and returns a Iterator of all results found + * for the path. If the xpath matches no properties + * in the graph, the Iterator will not be null. + */ + public abstract Iterator iterate(String xpath); + + + /** + * @deprecated Please use getPointer(String xpath) */ - public abstract List eval(String xpath); + public Pointer locateValue(String xpath){ + return getPointer(xpath); + } /** * Traverses the xpath and returns a Pointer. * A Pointer provides easy access to a property. * If the xpath matches no properties - * in the graph, the List will be empty. + * in the graph, the pointer will be null. */ - public abstract Pointer locateValue(String xpath); + public abstract Pointer getPointer(String xpath); + + /** + * @deprecated Please use iteratePointers + */ + public List locate(String xpath){ + ArrayList list = new ArrayList(); + Iterator it = iteratePointers(xpath); + while (it.hasNext()){ + list.add(it.next()); + } + return list; + } /** - * Traverses the xpath and returns a List of Pointers. + * Traverses the xpath and returns an Iterator of Pointers. * A Pointer provides easy access to a property. * If the xpath matches no properties - * in the graph, the List will be empty. + * in the graph, the Iterator be empty, but not null. */ - public abstract List locate(String xpath); + public abstract Iterator iteratePointers(String xpath); } 1.4 +12 -4 jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPath.java Index: JXPath.java =================================================================== RCS file: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPath.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- JXPath.java 12 Apr 2002 02:28:06 -0000 1.3 +++ JXPath.java 28 Apr 2002 04:37:01 -0000 1.4 @@ -1,7 +1,7 @@ /* - * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPath.java,v 1.3 2002/04/12 02:28:06 dmitri Exp $ - * $Revision: 1.3 $ - * $Date: 2002/04/12 02:28:06 $ + * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/JXPath.java,v 1.4 2002/04/28 04:37:01 dmitri Exp $ + * $Revision: 1.4 $ + * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 @@ -77,15 +77,19 @@ * <li>There is a need to use an AbstractFactory, which can create new objects. * <li>There is a need to use a hierarchy of evaluation contexts. * </ul> + * + * @deprecated This class will soon be removed - use JXPathContext.newInstance() * * @author Dmitri Plotnikov - * @version $Revision: 1.3 $ $Date: 2002/04/12 02:28:06 $ + * @version $Revision: 1.4 $ $Date: 2002/04/28 04:37:01 $ */ public final class JXPath { /** * Traverses the xpath and returns the resulting object. Primitive * types are wrapped into objects. + * + * @deprecated This class is going away */ public static Object getValue(Object bean, String xpath){ return JXPathContext.newContext(bean).getValue(xpath); @@ -98,6 +102,8 @@ * <li>The xpath does not in fact describe an existing property * <li>The property is not writable (no public, non-static set method) * </ul> + * + * @deprecated This class is going away */ public static void setValue(Object bean, String xpath, Object value){ JXPathContext.newContext(bean).setValue(xpath, value); @@ -108,6 +114,8 @@ * there is only one object that matches the xpath, it will be returned * as a collection with one element. If the xpath matches no properties * in the graph, the List will be empty. + * + * @deprecated This class is going away */ public static List eval(Object bean, String xpath){ return JXPathContext.newContext(bean).eval(xpath); 1.1 jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/CompiledExpression.java Index: CompiledExpression.java =================================================================== /* * $Header: /home/cvs/jakarta-commons/jxpath/src/java/org/apache/commons/jxpath/CompiledExpression.java,v 1.1 2002/04/28 04:37:01 dmitri Exp $ * $Revision: 1.1 $ * $Date: 2002/04/28 04:37:01 $ * * ==================================================================== * The Apache Software License, Version 1.1 * * * Copyright (c) 1999-2001 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. The end-user documentation included with the redistribution, if * any, must include the following acknowlegement: * "This product includes software developed by the * Apache Software Foundation (http://www.apache.org/)." * Alternately, this acknowlegement may appear in the software itself, * if and wherever such third-party acknowlegements normally appear. * * 4. The names "The Jakarta Project", "Commons", and "Apache Software * Foundation" must not be used to endorse or promote products derived * from this software without prior written permission. For written * permission, please contact [EMAIL PROTECTED] * * 5. Products derived from this software may not be called "Apache" * nor may "Apache" appear in their names without prior written * permission of the Apache Group. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Apache Software Foundation. * For more information on the Apache Software Foundation, please see * <http://www.apache.org/>. */ package org.apache.commons.jxpath; import java.util.Iterator; /** * Represents a compiled XPath. The interpretation of compiled XPaths * may be faster, because it bypasses the compilation step. The reference * implementation of JXPathContext also globally caches some of the * results of compilation, so the direct use of JXPathContext is not * always less efficient than the use of CompiledExpression. * <p> * Use CompiledExpression only when there is a need to evaluate the * same expression multiple times and the CompiledExpression can be * conveniently cached. * <p> * To acqure a CompiledExpression, call {@link JXPathContext#compile * JXPathContext.compile} * * @author Dmitri Plotnikov * @version $Revision: 1.1 $ $Date: 2002/04/28 04:37:01 $ */ public interface CompiledExpression { /** * Evaluates the xpath and returns the resulting object. Primitive * types are wrapped into objects. */ Object getValue(JXPathContext context); /** * Evaluates the xpath, converts the result to the specified class and * returns the resulting object. */ Object getValue(JXPathContext context, Class requiredType); /** * Modifies the value of the property described by the supplied xpath. * Will throw an exception if one of the following conditions occurs: * <ul> * <li>The xpath does not in fact describe an existing property * <li>The property is not writable (no public, non-static set method) * </ul> */ void setValue(JXPathContext context, Object value); /** * The same as setValue, except it creates intermediate elements of * the path by invoking an AbstractFactory, which should first be * installed on the context by calling "setFactory". * <p> * Will throw an exception if one of the following conditions occurs: * <ul> * <li>Elements of the xpath aleady exist, by the path does not in * fact describe an existing property * <li>The AbstractFactory fails to create an instance for an intermediate * element. * <li>The property is not writable (no public, non-static set method) * </ul> */ void createPath(JXPathContext context, Object value); /** * Traverses the xpath and returns a Iterator of all results found * for the path. If the xpath matches no properties * in the graph, the Iterator will not be null. */ Iterator iterate(JXPathContext context); /** * Traverses the xpath and returns a Pointer. * A Pointer provides easy access to a property. * If the xpath matches no properties * in the graph, the pointer will be null. */ Pointer getPointer(JXPathContext context, String xpath); /** * Traverses the xpath and returns an Iterator of Pointers. * A Pointer provides easy access to a property. * If the xpath matches no properties * in the graph, the Iterator be empty, but not null. */ Iterator iteratePointers(JXPathContext context); }
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>