Bug:25956 glue for XPath interface to DOM documents

git-svn-id: svn+ssh://svn.marklogic.com/project/engsvn/client-api/java/branches/b2_0@162644 62cac252-8da6-4816-9e9d-6dc37b19578c

Author: ehennum

src/main/java/com/marklogic/client/example/cookbook/AllCookbookExamples.java

@@ -18,6 +18,7 @@
 import java.io.IOException;
 
 import javax.xml.bind.JAXBException;
+import javax.xml.xpath.XPathExpressionException;
 
 import com.marklogic.client.FailedRequestException;
 import com.marklogic.client.ForbiddenUserException;
@@ -32,7 +33,7 @@
  */
 public class AllCookbookExamples {
 	public static void main(String[] args)
-	throws IOException, JAXBException, ResourceNotFoundException, ForbiddenUserException, FailedRequestException, ResourceNotResendableException {
+	throws IOException, JAXBException, ResourceNotFoundException, ForbiddenUserException, FailedRequestException, ResourceNotResendableException, XPathExpressionException {
 		ExampleProperties props = Util.loadProperties();
 
 		// execute the examples

src/main/java/com/marklogic/client/example/cookbook/DocumentRead.java

@@ -19,6 +19,8 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+import javax.xml.xpath.XPathExpressionException;
+
 import org.w3c.dom.Document;
 
 import com.marklogic.client.DatabaseClient;
@@ -32,11 +34,13 @@
  * DocumentReader illustrates how to read the content of a database document.
  */
 public class DocumentRead {
-	public static void main(String[] args) throws IOException {
+	public static void main(String[] args)
+	throws IOException, XPathExpressionException {
 		run(Util.loadProperties());
 	}
 
-	public static void run(ExampleProperties props) throws IOException {
+	public static void run(ExampleProperties props)
+	throws IOException, XPathExpressionException {
 		System.out.println("example: "+DocumentRead.class.getName());
 
 		// create the client
@@ -69,7 +73,8 @@ public static void runShortcut(DatabaseClient client) throws IOException {
 		String rootName = document.getDocumentElement().getTagName();
 		System.out.println("(Shortcut) Read "+docId+" content with the <"+rootName+"/> root element");
 	}
-	public static void runStrongTyped(DatabaseClient client) throws IOException {
+	public static void runStrongTyped(DatabaseClient client)
+	throws IOException, XPathExpressionException {
 		// create a manager for XML documents
 		XMLDocumentManager docMgr = client.newXMLDocumentManager();
 
@@ -83,9 +88,12 @@ public static void runStrongTyped(DatabaseClient client) throws IOException {
 		docMgr.read(docId, handle);
 		Document document = handle.get();
 
+		// apply an XPath 1.0 expression to the document
+		String productName = handle.evaluateXPath("string(/product/name)", String.class);
+
 		// access the document content
 		String rootName = document.getDocumentElement().getTagName();
-		System.out.println("(Strong Typed) Read /example/"+docId+" content with the <"+rootName+"/> root element");
+		System.out.println("(Strong Typed) Read /example/"+docId+" content with the <"+rootName+"/> root element for the "+productName+" product");
 	}
 
 	// set up by writing document content for the example to read

src/main/java/com/marklogic/client/io/DOMHandle.java

@@ -22,13 +22,21 @@
 import java.io.OutputStream;
 import java.io.UnsupportedEncodingException;
 
+import javax.xml.namespace.QName;
 import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;
+import javax.xml.xpath.XPath;
+import javax.xml.xpath.XPathConstants;
+import javax.xml.xpath.XPathExpression;
+import javax.xml.xpath.XPathExpressionException;
+import javax.xml.xpath.XPathFactory;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.w3c.dom.DOMException;
 import org.w3c.dom.Document;
+import org.w3c.dom.Node;
+import org.w3c.dom.NodeList;
 import org.w3c.dom.ls.DOMImplementationLS;
 import org.w3c.dom.ls.LSException;
 import org.w3c.dom.ls.LSInput;
@@ -60,6 +68,7 @@ public class DOMHandle
 	private LSResourceResolver     resolver;
 	private Document               content;
 	private DocumentBuilderFactory factory;
+	private XPath                  xpathProcessor;
 
 	/**
 	 * Creates a factory to create a DOMHandle instance for a DOM document.
@@ -221,6 +230,133 @@ protected DocumentBuilderFactory makeDocumentBuilderFactory() throws ParserConfi
 		return factory;
 	}
 
+	/**
+	 * Get the processor used to evaluate XPath expressions.
+	 * You might get the XPath processor to configure it. For instance,
+	 * you can configure the XPath processor to declare namespace
+	 * bindings or to set a function or variable resolver.
+	 * @see com.marklogic.client.util.EditableNamespaceContext
+	 * @return	the XPath expression processor
+	 */
+	public XPath getXPathProcessor() {
+		if (xpathProcessor == null)
+			xpathProcessor = makeXPathProcessorFactory().newXPath();
+		return xpathProcessor;
+	}
+	/**
+	 * Specifies the processor used to evaluate XPath expressions against
+	 * the document.
+	 * @param xpathProcessor	the XPath expression processor
+	 */
+	public void setXPathProcessor(XPath xpathProcessor) {
+		this.xpathProcessor = xpathProcessor;
+	}
+	protected XPathFactory makeXPathProcessorFactory() {
+		return XPathFactory.newInstance();
+	}
+
+	/**
+	 * Evaluate a string XPath expression against the retrieved document.
+	 * An XPath expression can return a Node or subinterface such as
+	 * Element or Text, a NodeList, or a Boolean, Number, or String value.
+	 * @param xpathExpression	the XPath expression as a string
+	 * @param as	the type of the value 
+	 * @return	the value produced by the XPath expression
+	 */
+	public <T> T evaluateXPath(String xpathExpression, Class<T> as)
+	throws XPathExpressionException {
+		return evaluateXPath(xpathExpression, get(), as);
+	}
+	/**
+	 * Evaluate a string XPath expression relative to a node such as a node
+	 * returned by a previous XPath expression.
+	 * An XPath expression can return a Node or subinterface such as
+	 * Element or Text, a NodeList, or a Boolean, Number, or String value.
+	 * @param xpathExpression	the XPath expression as a string
+	 * @param context	the node for evaluating the expression
+	 * @param as	the type of the value 
+	 * @return	the value produced by the XPath expression
+	 */
+	public <T> T evaluateXPath(String xpathExpression, Node context, Class<T> as)
+	throws XPathExpressionException {
+		checkContext(context);
+		return castAs(
+				getXPathProcessor().evaluate(xpathExpression, context, returnXPathConstant(as)),
+				as
+				);
+	}
+	/**
+	 * Compile an XPath string expression for efficient evaluation later.
+	 * @param xpathExpression	the XPath expression as a string
+	 * @return	the compiled XPath expression
+	 */
+	public XPathExpression compileXPath(String xpathExpression)
+	throws XPathExpressionException {
+		return getXPathProcessor().compile(xpathExpression);
+	}
+	/**
+	 * Evaluate a compiled XPath expression against the retrieved document.
+	 * An XPath expression can return a Node or subinterface such as
+	 * Element or Text, a NodeList, or a Boolean, Number, or String value.
+	 * @param xpathExpression	an XPath expression compiled previously
+	 * @param as	the type of the value 
+	 * @return	the value produced by the XPath expression
+	 */
+	public <T> T evaluateXPath(XPathExpression xpathExpression, Class<T> as)
+	throws XPathExpressionException {
+		return evaluateXPath(xpathExpression, get(), as);
+	}
+	/**
+	 * Evaluate a compiled XPath expression relative to a node such as a node
+	 * returned by a previous XPath expression.
+	 * An XPath expression can return a Node or subinterface such as
+	 * Element or Text, a NodeList, or a Boolean, Number, or String value.
+	 * @param xpathExpression	an XPath expression compiled previously
+	 * @param context	the node for evaluating the expression
+	 * @param as	the type of the value 
+	 * @return	the value produced by the XPath expression
+	 */
+	public <T> T evaluateXPath(XPathExpression xpathExpression, Node context, Class<T> as)
+	throws XPathExpressionException {
+		checkContext(context);
+		return castAs(
+				xpathExpression.evaluate(context, returnXPathConstant(as)),
+				as
+				);
+	}
+	protected void checkContext(Node context) {
+		if (context == null) {
+			throw new IllegalStateException("Cannot process empty context");
+		}
+	}
+	protected QName returnXPathConstant(Class<?> as) {
+		if (as == null) {
+			throw new IllegalArgumentException("cannot execute XPath as null");
+		} else if (Node.class.isAssignableFrom(as)) {
+			return XPathConstants.NODE;
+		} else if (NodeList.class.isAssignableFrom(as)) {
+			return XPathConstants.NODESET;
+		} else if (String.class.isAssignableFrom(as)) {
+			return XPathConstants.STRING;
+		} else if (Number.class.isAssignableFrom(as)) {
+			return XPathConstants.NUMBER;
+		} else if (Boolean.class.isAssignableFrom(as)) {
+			return XPathConstants.BOOLEAN;
+		}
+		throw new IllegalArgumentException("cannot execute XPath as "+as.getName());
+	}
+	protected <T> T castAs(Object result, Class<?> as) {
+		if (result == null) {
+			return null;
+		}
+		if (!as.isAssignableFrom(result.getClass())) {
+			throw new IllegalArgumentException("cannot cast "+result.getClass().getName()+" to "+as.getName());
+		}
+		@SuppressWarnings("unchecked")
+		T typedResult = (T) result;
+		return typedResult;
+	}
+
 	@Override
 	protected Class<InputStream> receiveAs() {
 		return InputStream.class;

src/test/java/com/marklogic/client/test/DOMSearchResultTest.java

@@ -16,18 +16,24 @@
 package com.marklogic.client.test;
 
 import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertEquals;
 
 import java.io.IOException;
 
 import javax.xml.parsers.ParserConfigurationException;
+import javax.xml.xpath.XPathExpression;
+import javax.xml.xpath.XPathExpressionException;
 
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
 import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.NodeList;
 
 import com.marklogic.client.query.QueryManager;
 import com.marklogic.client.query.StringQueryDefinition;
+import com.marklogic.client.util.EditableNamespaceContext;
 import com.marklogic.client.io.DOMHandle;
 
 public class DOMSearchResultTest {
@@ -42,14 +48,38 @@ public static void afterClass() {
     }
 
     @Test
-    public void testStringSearch() throws IOException, ParserConfigurationException {
+    public void testStringSearch()
+    throws IOException, ParserConfigurationException, XPathExpressionException {
         // This test really just exists to show how to get search results in other formats.
         QueryManager queryMgr = Common.client.newQueryManager();
         StringQueryDefinition qdef = queryMgr.newStringDefinition(null);
         qdef.setCriteria("leaf3");
 
-        DOMHandle results = queryMgr.search(qdef, new DOMHandle());
-        Document doc = results.get();
-        assertNotNull(doc);
+        DOMHandle responseHandle = queryMgr.search(qdef, new DOMHandle());
+        Document doc = responseHandle.get();
+        assertNotNull("null response document", doc);
+
+        // configure namespace bindings for the XPath processor
+        EditableNamespaceContext namespaces = new EditableNamespaceContext();
+        namespaces.setNamespaceURI("search", "http://marklogic.com/appservices/search");
+        responseHandle.getXPathProcessor().setNamespaceContext(namespaces);
+
+        // string expression against the document
+        String total = responseHandle.evaluateXPath("string(/search:response/@total)", String.class);
+        assertNotNull("null total", total);
+
+        // compiled expression against the document
+        XPathExpression resultsExpression = responseHandle.compileXPath("/search:response/search:result");
+        NodeList resultList = responseHandle.evaluateXPath(resultsExpression, NodeList.class);
+        assertNotNull("null result list", resultList);
+        assertEquals("result count mismatch", resultList.getLength(), Integer.parseInt(total));
+
+        // string expression against an element
+        Element firstResult = responseHandle.evaluateXPath("/search:response/search:result[1]", Element.class);
+        assertNotNull("null first result", firstResult);
+
+        String firstResultUri = responseHandle.evaluateXPath("string(@uri)", firstResult, String.class);
+        String firstItemUri   = ((Element) resultList.item(0)).getAttribute("uri");
+        assertEquals("first uri mismatch", firstResultUri, firstItemUri);
     }
 }

src/test/java/com/marklogic/client/test/example/cookbook/DocumentReadTest.java

@@ -19,6 +19,8 @@
 
 import java.io.IOException;
 
+import javax.xml.xpath.XPathExpressionException;
+
 import org.junit.Test;
 
 import com.marklogic.client.example.cookbook.DocumentRead;
@@ -32,6 +34,8 @@ public void testMain() {
 			succeeded = true;
 		} catch (IOException e) {
 			e.printStackTrace();
+		} catch (XPathExpressionException e) {
+			e.printStackTrace();
 		}
 		assertTrue("DocumentRead example failed", succeeded);
 	}