1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.jxpath;
17
18 import java.util.Iterator;
19
20 /***
21 * Represents a compiled XPath. The interpretation of compiled XPaths
22 * may be faster, because it bypasses the compilation step. The reference
23 * implementation of JXPathContext also globally caches some of the
24 * results of compilation, so the direct use of JXPathContext is not
25 * always less efficient than the use of CompiledExpression.
26 * <p>
27 * Use CompiledExpression only when there is a need to evaluate the
28 * same expression multiple times and the CompiledExpression can be
29 * conveniently cached.
30 * <p>
31 * To acqure a CompiledExpression, call {@link JXPathContext#compile
32 * JXPathContext.compile}
33 *
34 * @author Dmitri Plotnikov
35 * @version $Revision: 1.6 $ $Date: 2004/02/29 14:17:42 $
36 */
37 public interface CompiledExpression {
38
39 /***
40 * Evaluates the xpath and returns the resulting object. Primitive
41 * types are wrapped into objects.
42 */
43 Object getValue(JXPathContext context);
44
45 /***
46 * Evaluates the xpath, converts the result to the specified class and
47 * returns the resulting object.
48 */
49 Object getValue(JXPathContext context, Class requiredType);
50
51 /***
52 * Modifies the value of the property described by the supplied xpath.
53 * Will throw an exception if one of the following conditions occurs:
54 * <ul>
55 * <li>The xpath does not in fact describe an existing property
56 * <li>The property is not writable (no public, non-static set method)
57 * </ul>
58 */
59 void setValue(JXPathContext context, Object value);
60
61 /***
62 * Creates intermediate elements of
63 * the path by invoking an AbstractFactory, which should first be
64 * installed on the context by calling "setFactory".
65 */
66 Pointer createPath(JXPathContext context);
67
68 /***
69 * The same as setValue, except it creates intermediate elements of
70 * the path by invoking an AbstractFactory, which should first be
71 * installed on the context by calling "setFactory".
72 * <p>
73 * Will throw an exception if one of the following conditions occurs:
74 * <ul>
75 * <li>Elements of the xpath aleady exist, by the path does not in
76 * fact describe an existing property
77 * <li>The AbstractFactory fails to create an instance for an intermediate
78 * element.
79 * <li>The property is not writable (no public, non-static set method)
80 * </ul>
81 */
82 Pointer createPathAndSetValue(JXPathContext context, Object value);
83
84 /***
85 * Traverses the xpath and returns a Iterator of all results found
86 * for the path. If the xpath matches no properties
87 * in the graph, the Iterator will not be null.
88 */
89 Iterator iterate(JXPathContext context);
90
91 /***
92 * Traverses the xpath and returns a Pointer.
93 * A Pointer provides easy access to a property.
94 * If the xpath matches no properties
95 * in the graph, the pointer will be null.
96 */
97 Pointer getPointer(JXPathContext context, String xpath);
98
99 /***
100 * Traverses the xpath and returns an Iterator of Pointers.
101 * A Pointer provides easy access to a property.
102 * If the xpath matches no properties
103 * in the graph, the Iterator be empty, but not null.
104 */
105 Iterator iteratePointers(JXPathContext context);
106
107 /***
108 * Remove the graph element described by this expression
109 */
110 void removePath(JXPathContext context);
111
112 /***
113 * Remove all graph elements described by this expression
114 */
115 void removeAll(JXPathContext context);
116 }