1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.jxpath;
18
19 import java.util.Iterator;
20
21 /**
22 * Represents a compiled XPath. The interpretation of compiled XPaths
23 * may be faster, because it bypasses the compilation step. The reference
24 * implementation of {@link JXPathContext} also globally caches some of the
25 * results of compilation, so the direct use of JXPathContext is not
26 * always less efficient than the use of CompiledExpression.
27 * <p>
28 * Use CompiledExpression only when there is a need to evaluate the
29 * same expression multiple times and the CompiledExpression can be
30 * conveniently cached.
31 * <p>
32 * To acquire a CompiledExpression, call {@link JXPathContext#compile
33 * JXPathContext.compile}
34 *
35 * @author Dmitri Plotnikov
36 * @version $Revision: 652845 $ $Date: 2008-05-02 19:46:46 +0200 (Fr, 02 Mai 2008) $
37 */
38 public interface CompiledExpression {
39
40 /**
41 * Evaluates the xpath and returns the resulting object. Primitive
42 * types are wrapped into objects.
43 * @param context to evaluate
44 * @return Object
45 */
46 Object getValue(JXPathContext context);
47
48 /**
49 * Evaluates the xpath, converts the result to the specified class and
50 * returns the resulting object.
51 * @param context to evaluate
52 * @param requiredType return type
53 * @return Object
54 */
55 Object getValue(JXPathContext context, Class requiredType);
56
57 /**
58 * Modifies the value of the property described by the supplied xpath.
59 * Will throw an exception if one of the following conditions occurs:
60 * <ul>
61 * <li>The xpath does not in fact describe an existing property
62 * <li>The property is not writable (no public, non-static set method)
63 * </ul>
64 * @param context base
65 * @param value to set
66 */
67 void setValue(JXPathContext context, Object value);
68
69 /**
70 * Creates intermediate elements of
71 * the path by invoking an {@link AbstractFactory}, which should first be
72 * installed on the context by calling {@link JXPathContext#setFactory}.
73 * @param context base
74 * @return Pointer created
75 */
76 Pointer createPath(JXPathContext context);
77
78 /**
79 * The same as setValue, except it creates intermediate elements of
80 * the path by invoking an {@link AbstractFactory}, which should first be
81 * installed on the context by calling {@link JXPathContext#setFactory}.
82 * <p>
83 * Will throw an exception if one of the following conditions occurs:
84 * <ul>
85 * <li>Elements of the xpath aleady exist, by the path does not in
86 * fact describe an existing property
87 * <li>The AbstractFactory fails to create an instance for an intermediate
88 * element.
89 * <li>The property is not writable (no public, non-static set method)
90 * </ul>
91 * @param context base
92 * @param value to set
93 * @return Pointer created
94 */
95 Pointer createPathAndSetValue(JXPathContext context, Object value);
96
97 /**
98 * Traverses the xpath and returns a Iterator of all results found
99 * for the path. If the xpath matches no properties
100 * in the graph, the Iterator will not be null.
101 * @param context base
102 * @return Iterator
103 */
104 Iterator iterate(JXPathContext context);
105
106 /**
107 * Traverses the xpath and returns a Pointer.
108 * A Pointer provides easy access to a property.
109 * If the xpath matches no properties
110 * in the graph, the pointer will be null.
111 * @param context base
112 * @param xpath string
113 * @return Pointer found
114 */
115 Pointer getPointer(JXPathContext context, String xpath);
116
117 /**
118 * Traverses the xpath and returns an Iterator of Pointers.
119 * A Pointer provides easy access to a property.
120 * If the xpath matches no properties
121 * in the graph, the Iterator be empty, but not null.
122 * @param context to iterate
123 * @return Iterator<Pointer>
124 */
125 Iterator iteratePointers(JXPathContext context);
126
127 /**
128 * Remove the graph element described by this expression.
129 * @param context base
130 */
131 void removePath(JXPathContext context);
132
133 /**
134 * Remove all graph elements described by this expression.
135 * @param context base
136 */
137 void removeAll(JXPathContext context);
138 }