1. Introduction to XPath Transparency No. 1 Introduction to XPath API Cheng-Chia Chen

2. Introduction to XPath Transparency No. 2 Java API for XPath  Part of J2se5.0 and JAXP 1.3J2se5.0JAXP 1.3  included in a package : javax.xml.xpath Interfaces XPath XPathExpression XPathFunction XPathFunctionResolver XPathVariableResolver XPath XPathExpression XPathFunction XPathFunctionResolver XPathVariableResolver Classes XPathConstants XPathFactory XPathConstants XPathFactory Exceptions XPathException XPathExpressionException XPathFactoryConfigurationException XPathFunctionException XPathException XPathExpressionException XPathFactoryConfigurationException XPathFunctionException

3. Introduction to XPath Transparency No. 3 Using pattern of the XPath API Path xpath = XPathFactory.newInstance().newXPath(); String expression = "/widgets/widget"; InputSource inputSource = new InputSource("widgets.xml"); NodeList nodes = (NodeList) xpath.evaluate( expression, inputSource, XPathConstants.NODESET);

4. Introduction to XPath Transparency No. 4 XPath Expressions and Types  the XPath API allows the selected nodes to be coalesced into one of the following other data types: Boolean, Number, String.  The desired return type specified by a QName parameter in method calls of either XPathExpression.evalute(...) or one of the XPath.evaluate(...) convenience methods.  The allowed QName values are specified as constants in the XPathConstants class; they are: XPathConstants.NODESET,.NODE,  return first Node,.STRING  return string value of retruned node set.BOOLEAN  return Boolean.TRUE (FALSE),.NUMBER  return double

5. Introduction to XPath Transparency No. 5 XPath context  XPath location paths may be relative to a particular node in the document, known as the context node.  Consider the following XML document:  The element can be selected with the following XPath API code:

6. Introduction to XPath Transparency No. 6 // parse the XML as a W3C Document DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); Document document = builder.parse(new File("/widgets.xml")); XPath xpath = XPathFactory.newInstance().newXPath(); String expression = "/widgets/widget"; // absolute location path Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); // With a reference to the element, a relative XPath expression can now written to select the child element: XPath xpath = XPathFactory.newInstance().newXPath(); // relative location path needa context node String expression = "manufacturer"; Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE);

7. Introduction to XPath Transparency No. 7 Class Summary class XPathFactory  public static newInstance( [String modelUri ]) Get a new XPathFactory instance using the specified object model. default: XPathFactory.DEFAULT_OBJECT_MODEL_URI (the W3C DOM)DEFAULT_OBJECT_MODEL_URI looking up places and order:  ClassName given by the SystemProperty DEFAULT_PROPERTY_NAME [=“javax.xml.xpathXPathFactory”] + “:” + modelURI  property given in ${java.home}/lib/jaxp.properties  file named javax.xml.xpath.XPathFactory given in META-INF/services.  Platform default XPathFactory  Throw XPathFactoryConfigurationException  getFeature(String) /setFeature(String uri, boolean)

8. Introduction to XPath Transparency No. 8  boolean isObjectModelSupported (String)String Is specified object model supported by this XPathFactory?  XPath newXPath() XPath Return a new XPath using the underlying object model determined when the XPathFactory was instantiated.  void setXPathFunctionResolver( XPathFunctionResolver resolver ) Establish a default function resolver. Any XPath objects constructed from this factory will use the specified resolver by default.  void setXPathVariableResolver( XPathVariableResolver resolver) Establish a default variable resolver.

9. Introduction to XPath Transparency No. 9 calss XPathConstants Field Summary  static String DOM_OBJECT_MODEL The URI for the DOM object model : "http://java.sun.com/jaxp/xpath/dom".  static QName BOOLEAN The XPath 1.0 boolean data type. Mapped to java Boolean.  static QName NODE The XPath 1.0 NodeSet data type. Mapped to java org.w3c.dom.Node.  static QName NODESET The XPath 1.0 NodeSet data type. Mapped to java org.w3c.dom.NodeList.  static QName NUMBER The XPath 1.0 number data type. Mapped to java Double  static QName STRING The XPath 1.0 string data type. Mapped to Java String.

10. Introduction to XPath Transparency No. 10 interface javax.xml.xpath.XPath  provides access to the XPath evaluation environment and expressions.  Required properties for evaluating an xpath expression: ContextNode :  no ContextNode given  Empty DocumentNode provided  DocumentFragment treated the same as Documents. XPathVariableResolver for resolving (finding object bound to) varaibles used in the expression. XPathFunctionResolver for resolving (finding XPathFunciton bound to) fucntions used in the expression. NamespaceContext used to resolve QNames used in the expression.

11. Introduction to XPath Transparency No. 11  Methods: get/set NamespaceContext, XathVariableResolver and XPathFunctionResolver. getNamespaceContext() /setNamespaceContext(NamespaceContext) getXPathFunctionResolver() /setXPathFunctionResolver(XPathFunctionResolver) getXPathVariableResolver() /setXPathVariableResolver(XPathVariableResolver)  void Reset() reset the xpath to the same state as when it was created with XPathFactory.newXPath().  XPathExpression compile(String expression) XPathExpressionString Compile an XPath expression for later evaluation.

12. Introduction to XPath Transparency No. 12  Object evaluate(String expr, Object cxt, QName returnType) ObjectStringObjectQName Evaluate an XPath expression in the specified context and return the result as the specified type. expr or returntype null  NullPointerException cxt null  an empty doc is given as the context.  String evaluate(String expr, Object cxt)StringObject = evaluate(expr, cxt, XPathConstants.STRING )  Object evaluate(String expr, InputSource src, QName returnType) ObjectString QName Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type. expr or returntype null  NullPointerException  String evaluate(String expr, InputSource src)String = evaluate(expr, src, XPathConstants.STRING )

13. Introduction to XPath Transparency No. 13 Interface XPathExpression  provides access to compiled XPath expressions.  Object evaluate( Object cxt, QName returnType) Object QName Evaluate the XPathExpression in the specified context and return the result as the specified type. returntype null  NullPointerException cxt null  an empty doc is given as the context.  String evaluate( Object cxt)Object = evaluate(cxt, XPathConstants.STRING )  Object evaluate( InputSource src, QName returnType) ObjectQName Evaluate the XPathExpression in the context of the specified InputSource and return the result as the specified type. returntype null  NullPointerException  String evaluate( InputSource src) = evaluate( src, XPathConstants.STRING )

14. Introduction to XPath Transparency No. 14 XPathFunctionResolver  public interface XPathFunctionResolver  provides access to the set of user defined XPathFunctions.  XPath functions are resolved by name and arity. Resolver not needed for XPath built-in functions and the resolver cannot be used to override those functions.  The resolver is only called for functions in an another namespace (functions with an explicit prefix). cannot use the Resolver to implement specifications like XML-Signature Syntax and Processing which extend the function library of XPath 1.0 in the same namespace.  XPathFunction resolveFunction( QName functionName, int arity) Find a function in the set of available functions.

15. Introduction to XPath Transparency No. 15 XPathFunction  public interface XPathFunction provides access to XPath (external or built-in ) functions. Functions are identified by QName and arity in XPath.  Method Summary Object evaluate(List args) Evaluate the function with the specified arguments.

16. Introduction to XPath Transparency No. 16 XPathVariableResolver  public interface XPathVariableResolver provides access to the set of user defined XPath variables.  The XPathVariableResolver and the XPath evaluator must adhere to a contract that cannot be directly enforced by the API. Although variables may be mutable, that is, an application may wish to evaluate the same XPath expression more than once with different variable values, in the course of evaluating any single XPath expression, a variable's value must be immutable.  Object resolveVariable(QName variableName) ObjectQName Find a variable in the set of available variables. If variableName is null, then a NullPointerException is thrown.

17. Introduction to XPath Transparency No. 17 javax.xml.namespace  interface NamespaceContext Interface for read only XML Namespace context processing. Read-only version of NamespaceSupport of SAX2  class QName represents a qualified name as defined in the XML specifications. The value of a QName contains a Namespace URI, local part and prefix. The prefix is included in QName to retain lexical information when present in an XML input source.XML input source  The prefix is NOT used in QName.equals(Object) or to compute the QName.hashCode().QName.equals(Object) QName.hashCode() If not specified,  the Namespace URI is set to XMLConstants.NULL_NS_URI ( =“”)XMLConstants.NULL_NS_URI  the prefix is set to XMLConstants.DEFAULT_NS_PREFIX (=“”)XMLConstants.DEFAULT_NS_PREFIX QName is immutable.

18. Introduction to XPath Transparency No. 18 javax.xml.namespace.QName  Constructor: QName([String namespaceURI,] String localPart) QName(namespaceURI, localPart, String prefix )  Methods String getLocalPart(), getNamespaceURI(), String getPrefix() Get the various parts of this QName. boolean equals(Object qname) Test this QName for equality with another Object. retrun true iff localPart and namespaceURI parts of qname and this are all equal. (prefix not used) int hashCode() Generate the hash code for this QName.

19. Introduction to XPath Transparency No. 19 String toString() (standard) string representation of this QName. formats: namespaceURI != “”  "{" + namespaceURI + "}" + local Part. NamespaceURI==“”  localPart.  static QName valueOf(String qNameAsString) QName derived from parsing the formatted String. input must be in the form return by toString(). The prefix value CANNOT be represented in the String and will be set to XMLConstants.DEFAULT_NS_PREFIX.XMLConstants.DEFAULT_NS_PREFIX This method does not do full validation of the resulting QName.  The Namespace URI is not validated as a URI reference.URI reference  The local part is not validated as a NCName as specified in Namespaces in XML.NCName Namespaces in XML

20. Introduction to XPath Transparency No. 20 interface javax.xml.namespace.NamespaceContext  Two properties: namespaceURI prefix Method Summary  String getNamespaceURI(String prefix) Get Namespace URI bound to prefix in the current scope.  String getPrefix(String namespaceURI) Get a prefix bound to Namespace URI in the current scope.  Iterator getPrefixes(String namespaceURI) Get all prefixes bound to a Namespace URI in the current scope.

21. Introduction to XPath Transparency No. 21 uri and return prefix namespaceURI returned prefix  DEFAULT_NS_PREFIX =“”  bound Namespace URI any/all prefix bound to that uri  unbound URI null  XMLConstants.XML_NS_URI “xml”  XMLConstants.XMLNS_ATTRIBUTE_NS_URI “xmlns”  null IllegalArgumentException

22. Introduction to XPath Transparency No. 22 public final class javax.xml.XMLConstants  Utility class to contain basic XML values as constants.  DEFAULT_NS_PREFIX Prefix to use to represent the default XML Namespace. value: empty string “”.  NULL_NS_URI Namespace URI to use to represent that there is no Namespace. value: empty string “”.  XML_NS_PREFIX, XML_NS_URI The official XML Namespace prefix (=“xml”). The official XML Namespace name URI. =“http://www.w3.org/XML/1998/namespace“  XMLNS_ATTRIBUTE, XMLNS_ATTRIBUTE_NS_URI The official XML attribute used for specifying XML Namespace declarations. (=“xmlns”) The official namespace URI (=“http://www.w3.org/2000/xmlns/”)for the attribute XMLConstants.XMLNS_ATTRIBUTE.

23. Introduction to XPath Transparency No. 23  W3C_XPATH_DATATYPE_NS_URI W3C XPath Datatype Namespace URI. "http://www.w3.org/2003/11/xpath-datatypes". defined in 2.0 only.  XML_DTD_NS_URI XML Document Type Declaration Namespace URI as an arbitrary value. "http://www.w3.org/TR/REC-xml".  FEATURE_SECURE_PROCESSING Feature for secure processing.  static String RELAXNG_NS_URI RELAX NG Namespace URI. Defined to be "http://relaxng.org/ns/structure/1.0".  W3C_XML_SCHEMA_INSTANCE_NS_URI W3C XML Schema Instance Namespace URI. "http://www.w3.org/2001/XMLSchema-instance".  static String W3C_XML_SCHEMA_NS_URI W3C XML Schema Namespace URI. "http://www.w3.org/2001/XMLSchema".