Pointer


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.jxpath;
17  
18  import java.io.Serializable  ;
19  
20  /**
21   * Pointers represent locations of objects and their properties
22   * in Java object graphs. JXPathContext has methods
23   * ({@link JXPathContext#getPointer(java.lang.String) getPointer()}
24   * and  ({@link JXPathContext#iteratePointers(java.lang.String)
25   * iteratePointers()}, which, given an XPath, produce Pointers for the objects
26   * or properties described the the path. For example, <code>ctx.getPointer
27   * ("foo/bar")</code> will produce a Pointer that can get and set the property
28   * "bar" of the object which is the value of the property "foo" of the root
29   * object. The value of <code>ctx.getPointer("aMap/aKey[3]")</code> will be a
30   * pointer to the 3'rd element of the array, which is the value for the key
31   * "aKey" of the map, which is the value of the property "aMap" of the root
32   * object.
33   *
34   * @author Dmitri Plotnikov
35   * @version $Revision: 1.9 $ $Date: 2004/02/29 14:17:42 $
36   */
37  public interface Pointer extends Cloneable  , Comparable  , Serializable   {
38  
39      /**
40       * Returns the value of the object, property or collection element
41       * this pointer represents. May convert the value to one of the 
42       * canonical InfoSet types: String, Number, Boolean, Set.
43       * 
44       * For example, in the case of an XML element, getValue() will
45       * return the text contained by the element rather than 
46       * the element itself.
47       */
48      Object   getValue();
49  
50      /**
51       * Returns the raw value of the object, property or collection element
52       * this pointer represents.  Never converts the object to a
53       * canonical type: returns it as is. 
54       * 
55       * For example, for an XML element, getNode() will
56       * return the element itself rather than the text it contains.
57       */
58      Object   getNode();
59  
60      /**
61       * Modifies the value of the object, property or collection element
62       * this pointer represents.
63       */
64      void setValue(Object   value);
65  
66      /**
67       * Returns the node this pointer is based on. 
68       */
69      Object   getRootNode();
70      
71      /**
72       * Returns a string that is a proper "canonical" XPath that corresponds to
73       * this pointer.  Consider this example:
74       * <p><code>Pointer  ptr = ctx.getPointer("//employees[firstName = 'John']")
75       * </code>
76       * <p>The  value of <code>ptr.asPath()</code> will look something like
77       * <code>"/departments[2]/employees[3]"</code>, so, basically, it represents
78       * the concrete location(s) of the result of a search performed by JXPath.
79       * If an object in the pointer's path is a Dynamic Property object (like a
80       * Map), the asPath method generates an XPath that looks like this: <code>"
81       * /departments[@name = 'HR']/employees[3]"</code>.
82       */
83      String   asPath();
84      
85      /**
86       * Pointers are cloneable
87       */
88      Object   clone();
89  }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags