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

Introduction to XPath

Transparency No. 1

Introduction to XPath API

Cheng-Chia Chen


Transparency No. 2

Java API for XPath

Part of J2se5.0 and JAXP 1.3 included in a package : javax.xml.xpath

Interfaces XPath XPathExpression XPathFunction XPathFunctionResolver XPathVariableResolver

Classes XPathConstants XPathFactory

Exceptions XPathException XPathExpressionException XPathFactoryConfigurationException XPathFunctionException


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);


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


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:

<widgets>

<widget>

<manufacturer/>

<dimensions/>

</widget>

</widgets> The <widget> element can be selected with the

following XPath API code:


Transparency No. 6

// parse the XML as a W3C DocumentDocumentBuilder builder =

DocumentBuilderFactory.newInstance().newDocumentBuilder();Document document = builder.parse(new File("/widgets.xml"));

XPath xpath = XPathFactory.newInstance().newXPath();String expression = "/widgets/widget"; // absolute location pathNode widgetNode = (Node) xpath.evaluate(expression, document,

XPathConstants.NODE);

// With a reference to the <widget> element, a relative XPath expression can now written to select the <manufacturer> child element:

XPath xpath = XPathFactory.newInstance().newXPath();// relative location path needa context nodeString expression = "manufacturer"; Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode,

XPathConstants.NODE);


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)

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)


Transparency No. 8

boolean isObjectModelSupported (String) Is specified object model supported by this

XPathFactory? XPath newXPath()

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.


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.


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 providedDocumentFragment 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.


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) Compile an XPath expression for later evaluation.


Transparency No. 12

Object evaluate(String expr, Object cxt, QName returnType) 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) = evaluate(expr, cxt, XPathConstants.STRING )

Object evaluate(String expr, InputSource src, QName returnType) 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) = evaluate(expr, src, XPathConstants.STRING )


Transparency No. 13

Interface XPathExpression

provides access to compiled XPath expressions. Object evaluate( Object cxt, QName returnType)

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) = evaluate(cxt, XPathConstants.STRING )

Object evaluate( InputSource src, QName returnType) 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 )


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.


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.


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) Find a variable in the set of available variables. If variableName is null, then a NullPointerException is

thrown.


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. The prefix is NOT used in QName.equals(Object) or to compute the

QName.hashCode().

If not specified, the Namespace URI is set to XMLConstants.NULL_NS_URI ( =“”)the prefix is set to XMLConstants.DEFAULT_NS_PREFIX (=“”)

QName is immutable.


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.


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. This method does not do full validation of the resulting

QName. The Namespace URI is not validated as a URI reference. The local part is not validated as a NCName as specified in

Namespaces in XML.


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.


Transparency No. 21

uri and return prefix

namespaceURI returned prefix <default namespace URI> 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


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.


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".