View Javadoc
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 }