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 }