public static String evalAsString(String expr, XNode node) 
        throws ParseException, EvalException {
        return evalAsString(expr, node, null);
    }

The goal of the above method is to evaluate XPath expression expr (example: "//ol[contains(@style,'decimal')]"), using node as the initial context. The result of the evaluation is to be converted to a string (example: "2.0 + 2.0" is converted to string "4") using the rules described in the XPath spec.

Note that the context node is a com.xmlmind.xmledit.doc.XNode and not any of the Document, Element, Comment, etc, Nodes we have studied in previous chapter.

XMLmind XML Editor DOM uses Nodes. Each kind of Node has a different API. For example, Element has a getName method and Text has a getText method but no getName method. And in XMLmind XML Editor DOM, for efficiency reasons, attributes are not Nodes.

XPath prefers to deal with uniform XNodes. For example, all types of XNodes should support the name method, even this does not make sense in the case of text nodes, comment nodes, document nodes, etc. And, unlike in XMLmind XML Editor DOM, attributes too are XNodes.

All XMLmind XML Editor DOM Nodes implement the XNode interface. This means that you can pass, for example, an Element as the context node of evalAsString without even thinking about it.

The above method is in fact a convenience function for the slightly lower-level method below:

    public static String evalAsString(String expr, XNode node,
                                      HashMap variables) 
        throws ParseException, EvalException {
        StringExpr parsed = 
            ExprParser.parseStringExpr(expr, node.namespacePrefixMap(),
                                       /*acceptUnknownPrefix*/ true);
        return parsed.eval(node, createExprContext(variables));
    }

First step consists in parsing the XPath string as a StringExpr. This step may throw a ParseException.

Second step consists in evaluating the parsed XPath expression, a StringExpr, in the context of node, using an ExprContext as the ``evaluation environment'' (more on this in next section). This step may throw an EvalException.

A parsed XPath expression can of course be stored in order to be evaluated several times.

XPath expressions are namespace-aware^[2]. When parsing an expression such as "/c:description/x:div", the parser needs to know the namespaces corresponding to "c" and to "x". To do this, the parser uses an object which implements the com.xmlmind.xmledit.xmlutil.PrefixToNamespace interface. Method namespacePrefixMap returns such object.

What if a prefix such as "x" is unknown? Unless parameter acceptUnknownPrefix of parseStringExpr is true, the parser will throw a ParseException. In XMLmind XML Editor, documents conforming to a DTD are not namespace aware, therefore it is strongly recommended to always pass true for this parameter, even if this will cause the parser to catch less errors.

    private static ExprContext createExprContext(final HashMap variables) {
        if (variables == null) {
            return new ExprContextBase();
        } else {
            return new ExprContextBase() {
                public Variant getVariableValue(Name name, XNode node) 
                    throws EvalException {
                    Object value = variables.get(name.getLocalPart());
                    if (value == null)
                        return null;
                    else
                        return VariantBase.create(value);
                }
            };
        }
    }

In some cases, the XPath expression you want to evaluate contains references to variables. Example: "//ulink[@url=$home.url]". In such case, the XPath evaluator gets the values of theses variables from the ``evaluation environment'' passed to parseStringExpr.

ExprContext is an interface implemented by XPath evaluation environments. It specifies the following services:

ExprContextBase is a simple implementation of ExprContext, which implements all the services, except the access to variables. That's why an anonymous class derived from ExprContextBase is created in createExprContext. This class redefines method getVariableValue. The implementation of this method uses a HashMap to map the local name of the variable to its value: a Variant (more on this in next section).

A ExprContextBase can be reused several times, unless the documents which are searched using XPath expressions have been modified. In such case, make sure to create and use a new ExprContextBase or if you prefer, invoke method reset before reusing a ExprContextBase.

If you know in advance that the XPath expression will return a number, you may want to use evalAsNumber rather than evalAsString. evalAsNumber is implemented using NumberExpr and parseNumberExpr.

    public static double evalAsNumber(String expr, XNode node,
                                      HashMap variables) 
        throws ParseException, EvalException {
        NumberExpr parsed = 
            ExprParser.parseNumberExpr(expr, node.namespacePrefixMap(),
                                       /*acceptUnknownPrefix*/ true);
        return parsed.eval(node, createExprContext(variables));
    }

If you know in advance that the XPath expression will return a boolean, you may want to use evalAsBoolean rather than evalAsString. evalAsBoolean is implemented using BooleanExpr and parseBooleanExpr.

    public static boolean evalAsBoolean(String expr, XNode node,
                                        HashMap variables) 
        throws ParseException, EvalException {
        BooleanExpr parsed = 
            ExprParser.parseBooleanExpr(expr, node.namespacePrefixMap(),
                                        /*acceptUnknownPrefix*/ true);
        return parsed.eval(node, createExprContext(variables));
    }

If you know in advance that the XPath expression will return XNodes, you'll have to use evalAsNodeSet rather than evalAsString. evalAsNodeSet is implemented using NodeSetExpr and parseNodeSetExpr.

    public static XNode[] evalAsNodeSet(String expr, XNode node,
                                        HashMap variables) 
        throws ParseException, EvalException {
        NodeSetExpr parsed = 
            ExprParser.parseNodeSetExpr(expr, node.namespacePrefixMap(),
                                        /*acceptUnknownPrefix*/ true);
        NodeIterator iter = parsed.eval(node, createExprContext(variables));

        ArrayList list = new ArrayList();
        for (;;) {
            XNode n = iter.next();
            if (n == null)
                break;

            list.add(n);
        }

        XNode[] nodes = new XNode[list.size()];
        list.toArray(nodes);
        return nodes;
    }

A NodeIterator is always used like this:

        for (;;) {
            XNode n = iter.next();
            if (n == null)
                break;

            /* Use XNode n. */
        }

The important thing to remember is that a NodeIterator can only be used once to iterate over the node-set it represents^[3]. If you intend to store a NodeIterator in order to reuse it several times, you need to:

If you don't know in advance what the XPath expression will return, you'll have to use evalAsVariant rather than evalAsString. evalAsVariant is implemented using VariantExpr and parseVariantExpr.

    public static Variant evalAsVariant(String expr, XNode node,
                                        HashMap variables) 
        throws ParseException, EvalException {
        VariantExpr parsed = 
            ExprParser.parseVariantExpr(expr, node.namespacePrefixMap(),
                                        /*acceptUnknownPrefix*/ true);
        return parsed.eval(node, createExprContext(variables));
    }

Variant represents a dynamically typed value manipulated by the XPath evaluator. This interface has methods to query the type of the value (example: isNumber) and methods to convert between different value types (example: convertToBoolean).