    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}