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  package org.apache.commons.jxpath;
18  
19  import java.io.Serializable;
20  
21  /**
22   * Pointers represent locations of objects and their properties
23   * in Java object graphs. JXPathContext has methods
24   * ({@link JXPathContext#getPointer(java.lang.String) getPointer()}
25   * and  ({@link JXPathContext#iteratePointers(java.lang.String)
26   * iteratePointers()}, which, given an XPath, produce Pointers for the objects
27   * or properties described the the path. For example, <code>ctx.getPointer
28   * ("foo/bar")</code> will produce a Pointer that can get and set the property
29   * "bar" of the object which is the value of the property "foo" of the root
30   * object. The value of <code>ctx.getPointer("aMap/aKey[3]")</code> will be a
31   * pointer to the 3'rd element of the array, which is the value for the key
32   * "aKey" of the map, which is the value of the property "aMap" of the root
33   * object.
34   *
35   * @author Dmitri Plotnikov
36   * @version $Revision: 652845 $ $Date: 2008-05-02 13:46:46 -0400 (Fri, 02 May 2008) $
37   */
38  public interface Pointer extends Cloneable, Comparable, Serializable {
39  
40      /**
41       * Returns the value of the object, property or collection element
42       * this pointer represents. May convert the value to one of the
43       * canonical InfoSet types: String, Number, Boolean, Set.
44       *
45       * For example, in the case of an XML element, getValue() will
46       * return the text contained by the element rather than
47       * the element itself.
48       * @return Object value
49       */
50      Object getValue();
51  
52      /**
53       * Returns the raw value of the object, property or collection element
54       * this pointer represents.  Never converts the object to a
55       * canonical type: returns it as is.
56       *
57       * For example, for an XML element, getNode() will
58       * return the element itself rather than the text it contains.
59       * @return Object node
60       */
61      Object getNode();
62  
63      /**
64       * Modifies the value of the object, property or collection element
65       * this pointer represents.
66       * @param value value to set
67       */
68      void setValue(Object value);
69  
70      /**
71       * Returns the node this pointer is based on.
72       * @return Object
73       */
74      Object getRootNode();
75  
76      /**
77       * Returns a string that is a proper "canonical" XPath that corresponds to
78       * this pointer.  Consider this example:
79       * <p><code>Pointer  ptr = ctx.getPointer("//employees[firstName = 'John']")
80       * </code>
81       * <p>The  value of <code>ptr.asPath()</code> will look something like
82       * <code>"/departments[2]/employees[3]"</code>, so, basically, it represents
83       * the concrete location(s) of the result of a search performed by JXPath.
84       * If an object in the pointer's path is a Dynamic Property object (like a
85       * Map), the asPath method generates an XPath that looks like this: <code>"
86       * /departments[@name = 'HR']/employees[3]"</code>.
87       * @return String path
88       */
89      String asPath();
90  
91      /**
92       * Pointers are cloneable.
93       * @return cloned Object
94       */
95      Object clone();
96  }