wt.util.xml.xpath
Interface XPath

All Known Subinterfaces:

XPathNI

All Known Implementing Classes:

XPathXalan2Impl

public interface XPath

Abstraction for holding and evaluating XPaths into XML documents.

XPaths can be evaluated multiple times, but implementations are free to synchronized access so that only one thread at a time may be evaluating the path.

Instances should be created by an XPathFactory (i.e. abstract factory pattern).

Supported API: true

Extendable: false

See Also:

XPathFactory

Method Summary

Object	evaluate(Node node_to_operate_on) Evaluates the xpath relative to the specified node and returns the result as the most appropriate object.
void	evaluate(Node node_to_operate_on, XPathCallback callback) Evaluates the xpath relative to the specified node and invokes the callback method most appropriate for the located object.

Method Detail

evaluate

public void evaluate(Node node_to_operate_on,
                     XPathCallback callback)
              throws XPathException

Evaluates the xpath relative to the specified node and invokes the callback method most appropriate for the located object.

You must supply an XPathCallback object to use this method to evaluate an XPath against a document. The XPath implementation is responsble for switching to the appropriate callback handler based on the XML nodes referenced by the XPath. This necessitates a style of programming that uses inner or anonymous class to handle the results of the XPath.

The motivation to implement XPath support this was largely to discourage styles of programming that use switches or cascading if-else-ifs where the type of the result is checked via the instanceof operator. To see how to effectively use this means of evaluation, look at the following example code.

Example

The following example evaluates the expression on the document and returns true if the xpath evaluates to a resulta and false if no result is located.

    public class SomeUtilityClass
    {
       private XPathFactory factory_ = ...;
        
       public static boolean doesXPathPointToSomething(
                Document doc_to_search,
                String x_path_expression)
          throws XPathException
       {
          // this inner class is the callback for the evaluated xpath
          class WasExpressionFoundCallback
             extends AbstractXPathCallback
          {
             private boolean wasFound = true;
             public void processNotFound() { wasFound = false; }
          };
           
          XPath x_path = factory_.newXPath(x_path_expression);
          WasExpressionFoundCallback callback = new WasExpressionFoundCallback();
          x_path.evaluate(doc_to_search, callback);
           
          return callback.wasFound;
       }
    }
 

Supported API: false

Parameters:

node_to_operate_on - node to search relative to

callback - interface bearing methods for each type of located object

Throws:

XPathException - implementations should rethrow all failures as XPathExceptions

See Also:

XPathCallback

evaluate

public Object evaluate(Node node_to_operate_on)
                throws XPathException

Evaluates the xpath relative to the specified node and returns the result as the most appropriate object. This will be a Double, String, Boolean, NodeList, DocumentFragment, null, or, where none of these are appropriate, an implementation specific object.

One should not use this method as an excuse to implement poor code consisting of switches or cascading if-else-ifs where the type of the result is checked via the instanceof operator. This method should only be used when a single result type is demanded.

Supported API: true

Parameters:

node_to_operate_on -

Returns:

Object

Throws:

XPathException