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]>
