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