001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.jxpath;
019
020import java.util.Iterator;
021
022/**
023 * Represents a compiled XPath. The interpretation of compiled XPaths may be faster, because it bypasses the compilation step. The reference implementation of
024 * {@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
025 * of CompiledExpression.
026 * <p>
027 * Use CompiledExpression only when there is a need to evaluate the same expression multiple times and the CompiledExpression can be conveniently cached.
028 * <p>
029 * To acquire a CompiledExpression, call {@link JXPathContext#compile JXPathContext.compile}
030 */
031public interface CompiledExpression {
032
033    /**
034     * Creates intermediate elements of the path by invoking an {@link AbstractFactory}, which should first be installed on the context by calling
035     * {@link JXPathContext#setFactory}.
036     *
037     * @param context base
038     * @return Pointer created
039     */
040    Pointer createPath(JXPathContext context);
041
042    /**
043     * The same as setValue, except it creates intermediate elements of the path by invoking an {@link AbstractFactory}, which should first be installed on the
044     * context by calling {@link JXPathContext#setFactory}.
045     * <p>
046     * Will throw an exception if one of the following conditions occurs:
047     * <ul>
048     * <li>Elements of the XPath aleady exist, by the path does not in fact describe an existing property
049     * <li>The AbstractFactory fails to create an instance for an intermediate element.
050     * <li>The property is not writable (no public, non-static set method)
051     * </ul>
052     *
053     * @param context base
054     * @param value   to set
055     * @return Pointer created
056     */
057    Pointer createPathAndSetValue(JXPathContext context, Object value);
058
059    /**
060     * 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
061     * will be null.
062     *
063     * @param context base
064     * @param xpath   string
065     * @return Pointer found
066     */
067    Pointer getPointer(JXPathContext context, String xpath);
068
069    /**
070     * Evaluates the XPath and returns the resulting object. Primitive types are wrapped into objects.
071     *
072     * @param context to evaluate
073     * @return Object
074     */
075    Object getValue(JXPathContext context);
076
077    /**
078     * Evaluates the xpath, converts the result to the specified class and returns the resulting object.
079     *
080     * @param context      to evaluate
081     * @param requiredType return type
082     * @return Object
083     */
084    Object getValue(JXPathContext context, Class requiredType);
085
086    /**
087     * 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
088     * null.
089     *
090     * @param context base
091     * @return Iterator
092     */
093    Iterator iterate(JXPathContext context);
094
095    /**
096     * 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,
097     * the Iterator be empty, but not null.
098     *
099     * @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}