Paths are evaluated using the DataAccessor object available from the RendererContext that is passed to all render methods. When a path is extended into a server interface property value, the method called on the DataAccessor determine the method that is called on the marshal plug-in. For the SimpleXPathMarshal plug-in class data is converted generally as follows:
- The value of an attribute node is the string value of the attribute.
- The value of an element node is the concatenation of the values of all of the child text nodes of that element.
- If the are no selected nodes or a path evaluates to null, the result depends on which DataAccessor method was called. See below for details.
- The value of the result of a function call, is the string value of that result.
This behavior is consistent with use of the standard XPath string() function on the selected nodes or value, except, in the case of an element node, where only direct child text nodes of an element are concatenated, not all descendant text nodes as would be normal for XPath.
The DataAccessor methods refine the general behavior described above. For the SimpleXPathMarshal plug-in class, there is little difference between the formatted and raw variants, except for their handling of null values.
- get
- Gets the string value of a the first node (in document order) selected by the simple XPath expression given by the path, or, in the case of a function call, the string value of the result of that call. If no nodes are selected, the result will be an empty string. To distinguish between an attribute or element that is present but has an empty string value and an attribute or element that is not present at all, use the getRaw method and test if the result is an empty string or a null value.
- getRaw
- Gets the first raw value of the first node (in document order) selected by the path, or, in the case of a function call, the resulting value of that call. If no nodes are selected, the result will be null.
- getList
- Gets the list containing the string values of the nodes (in document order) selected by the path. For non-function-call paths, the values in the list represent the result of calling the get method on each selected node. If the path represents a function call, then the list will contain the single result of calling the function ones on all of the selected nodes, not a list of the results of the function call on each node. The functions operate only on the first node when presented with a list of several nodes.
For example, /values/value[3]/* selects all of the child elements of the third value element within the values root element. The resulting list will contain the three string objects, one each for the body text of each element. However, evaluating the path /values/value[3]/*/name() will return a list containing a single string that is the name of the first selected element (addr), not one string for the name of each selected element.
- getRawList
- Gets the list containing the values of the nodes (in document order) selected by the path. The conversion behavior of this method is the same as the getRaw method and the list handling is the same as the getList method.
- count
- Counts the number of nodes selected by the given path. If the path represents a function call, then the count is the number of results from the function call (usually one).