    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.io.Serializable;
    021
    022/**
    023 * Pointers represent locations of objects and their properties in Java object graphs. JXPathContext has methods
    024 * ({@link JXPathContext#getPointer(java.lang.String) getPointer()} and ({@link JXPathContext#iteratePointers(java.lang.String) iteratePointers()}, which, given
    025 * an XPath, produce Pointers for the objects or properties described the path. For example, {@code ctx.getPointer
    026 * ("foo/bar")} will produce a Pointer that can get and set the property "bar" of the object which is the value of the property "foo" of the root object. The
    027 * value of {@code ctx.getPointer("aMap/aKey[3]")} will be a pointer to the 3'rd element of the array, which is the value for the key "aKey" of the map, which
    028 * is the value of the property "aMap" of the root object.
    029 */
    030public interface Pointer extends Cloneable, Comparable, Serializable {
    031
    032    /**
    033     * Returns a string that is a proper "canonical" XPath that corresponds to this pointer. Consider this example:
    034     * <p>
    035     * {@code Pointer  ptr = ctx.getPointer("//employees[firstName = 'John']")
    036     * }
    037     * </p>
    038     * <p>
    039     * The value of {@code ptr.asPath()} will look something like {@code "/departments[2]/employees[3]"}, so, basically, it represents the concrete location(s)
    040     * of the result of a search performed by JXPath. If an object in the pointer's path is a Dynamic Property object (like a Map), the asPath method generates
    041     * an XPath that looks like this: {@code "
    042     * /departments[@name = 'HR']/employees[3]"}.
    043     *
    044     * @return String path
    045     */
    046    String asPath();
    047
    048    /**
    049     * Pointers are cloneable.
    050     *
    051     * @return cloned Object
    052     */
    053    Object clone();
    054
    055    /**
    056     * Returns the raw value of the object, property or collection element this pointer represents. Never converts the object to a canonical type: returns it as
    057     * is.
    058     * <p>
    059     * For example, for an XML element, getNode() will return the element itself rather than the text it contains.
    060     * </p>
    061     *
    062     * @return Object node
    063     */
    064    Object getNode();
    065
    066    /**
    067     * Returns the node this pointer is based on.
    068     *
    069     * @return Object
    070     */
    071    Object getRootNode();
    072
    073    /**
    074     * Returns the value of the object, property or collection element this pointer represents. May convert the value to one of the canonical InfoSet types:
    075     * String, Number, Boolean, Set.
    076     * <p>
    077     * For example, in the case of an XML element, getValue() will return the text contained by the element rather than the element itself.
    078     * </p>
    079     *
    080     * @return Object value
    081     */
    082    Object getValue();
    083
    084    /**
    085     * Modifies the value of the object, property or collection element this pointer represents.
    086     *
    087     * @param value value to set
    088     */
    089    void setValue(Object value);
    090}