Merge branch 'release-3.0.4' into 3.0-master

.classpath

@@ -1,36 +1,32 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<classpath>
-	<classpathentry kind="src" output="target/classes" path="src/main/java">
-		<attributes>
-			<attribute name="optional" value="true"/>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
-		<attributes>
-			<attribute name="optional" value="true"/>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
-		<attributes>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry excluding="**" kind="src" output="target/test-classes" path="src/test/resources">
-		<attributes>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.6">
-		<attributes>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
-		<attributes>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="output" path="target/classes"/>
-</classpath>
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>

.gitignore

@@ -7,3 +7,5 @@ test-complete/build/
 *.jar
 *.war
 *.ear
+.classpath
+.gitignore

README.md

@@ -26,6 +26,24 @@ The Java API supports the following core features of the MarkLogic database:
 
 For more details, please read this [deeper dive](http://developer.marklogic.com/features/java-client-api-2)
 
+### What's New in Java Client API 3.0.2
+
+* Many bug fixes
+
+### What's New in Java Client API 3.0.3
+
+* Search Extract - add support to SearchHandle (actually MatchDocumentSummary) for content extracted by
+  the [extract-document-data option](http://docs.marklogic.com/search:search#opt-extract-document-data)
+* Bi-Temporal enhancements - support bulk write of bitemporal documents; expose bitemporal system time
+* Bulk delete
+
+### What's New in Java Client API 3.0.4
+
+* Semantics API - GraphManager for CRUD of semantic graphs; SPARQLQueryManager for executing SPARQL
+  queries (select, describe, construct, and ask) and using SPARQL Update
+* Enable [MarkLogic Jena API](https://github.com/marklogic/marklogic-jena) (separate project)
+* Enable [MarkLogic Sesame API](https://github.com/marklogic/marklogic-sesame) (separate project)
+
 ### QuickStart
 
 To use the API in your maven project, include the following in your pom.xml:

pom.xml

@@ -4,7 +4,7 @@
 	<groupId>com.marklogic</groupId>
 	<artifactId>java-client-api</artifactId>
 	<packaging>jar</packaging>
-	<version>3.0.3</version>
+	<version>3.0.4</version>
 	<name>MarkLogic Java Client API</name>
 	<description>The official MarkLogic Java client API.</description>
 	<url>https://github.com/marklogic/java-client-api</url>

src/main/java/com/marklogic/client/DatabaseClient.java

@@ -31,6 +31,8 @@
 import com.marklogic.client.alerting.RuleManager;
 import com.marklogic.client.util.RequestLogger;
 import com.marklogic.client.pojo.PojoRepository;
+import com.marklogic.client.semantics.GraphManager;
+import com.marklogic.client.semantics.SPARQLQueryManager;
 
 /**
  * A Database Client instantiates document and query managers and other objects
@@ -113,6 +115,12 @@ public interface DatabaseClient {
      */
     public ServerConfigurationManager newServerConfigManager();
 
+    /** Creates a manager for CRUD operations on semantic graphs.  */
+    public GraphManager newGraphManager();
+
+    /** Creates a manager for executing SPARQL queries and retrieving results. */
+    public SPARQLQueryManager newSPARQLQueryManager();
+
     /**
      * Creates a PojoRepository specific to the specified class and its id type. 
      * The PojoRepository provides a facade for persisting, retrieving, and

src/main/java/com/marklogic/client/FailedRequestException.java

@@ -15,6 +15,8 @@
  */
 package com.marklogic.client;
 
+import java.io.IOException;
+
 import com.marklogic.client.impl.FailedRequest;
 
 /**
@@ -29,7 +31,12 @@ public FailedRequestException(String message) {
 		super(message);
 	}
 
+	public FailedRequestException(String localMessage, Throwable cause) {
+		super(localMessage, cause);
+	}
+
 	public FailedRequestException(String localMessage, FailedRequest failedRequest) {
 		super(localMessage, failedRequest);
 	}
+
 }

src/main/java/com/marklogic/client/MarkLogicServerException.java

@@ -45,6 +45,10 @@ public MarkLogicServerException(String localMessage) {
 		super(localMessage);
 	}
 
+	public MarkLogicServerException(String localMessage, Throwable cause) {
+		super(localMessage, cause);
+	}
+
 	@Override
 	public String getMessage() {
 		if (super.getMessage() != null && failedRequest != null) {

src/main/java/com/marklogic/client/bitemporal/TemporalDescriptor.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2012-2015 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marklogic.client.bitemporal;
+
+import javax.xml.bind.DatatypeConverter;
+import com.marklogic.client.document.DocumentDescriptor;
+
+public interface TemporalDescriptor extends DocumentDescriptor {
+    /**
+     * Returns the URI identifier for the database document.
+     * @return	the document URI
+     */
+    public String getUri();
+
+    /**
+     * Returns the temporal system time when the document was written or deleted.
+     * The time is returned in ISO 8601 format like all MarkLogic timestamps.  It
+     * can be parsed by
+     * {@link DatatypeConverter#parseDateTime DatatypeConverter.parseDateTime}
+     * but will lose precision since java.util.Calendar only supports millisecond
+     * precision.
+     * @return  the temporal system time
+     */
+    public String getTemporalSystemTime();
+}

src/main/java/com/marklogic/client/bitemporal/TemporalDocumentManager.java

@@ -19,9 +19,11 @@
 import com.marklogic.client.ForbiddenUserException;
 import com.marklogic.client.ResourceNotFoundException;
 import com.marklogic.client.Transaction;
+import com.marklogic.client.bitemporal.TemporalDescriptor;
 import com.marklogic.client.document.DocumentDescriptor;
 import com.marklogic.client.document.DocumentManager;
 import com.marklogic.client.document.DocumentUriTemplate;
+import com.marklogic.client.document.DocumentWriteSet;
 import com.marklogic.client.document.ServerTransform;
 import com.marklogic.client.io.marker.AbstractReadHandle;
 import com.marklogic.client.io.marker.AbstractWriteHandle;
@@ -33,7 +35,7 @@ public interface TemporalDocumentManager<R extends AbstractReadHandle, W extends
    * Just like {@link DocumentManager#create(DocumentUriTemplate, DocumentMetadataWriteHandle,
    * AbstractWriteHandle, ServerTransform, Transaction) create} but create document
    * in a temporalCollection, which will enforce all the rules of
-   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * <a href="http://docs.marklogic.com/guide/temporal/managing">
    * bitemporal data management</a>.
    * @param template	the template for constructing the document uri
    * @param metadataHandle	a handle for writing the metadata of the document
@@ -42,9 +44,10 @@ public interface TemporalDocumentManager<R extends AbstractReadHandle, W extends
    * @param transaction	an open transaction under which the document may have been created or deleted
    * @param temporalCollection	the name of the temporal collection existing in the database into
    *    which this document should be written
-   * @return the database uri that identifies the created document
+   * @return the TemporalDescriptor including the database uri that identifies the created document,
+   *    as well as the temporal system time when the document was created
    */
-  public DocumentDescriptor create(DocumentUriTemplate template,
+  public TemporalDescriptor create(DocumentUriTemplate template,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
       ServerTransform transform,
@@ -56,7 +59,7 @@ public DocumentDescriptor create(DocumentUriTemplate template,
    * Just like {@link DocumentManager#write(DocumentDescriptor, DocumentMetadataWriteHandle,
    * AbstractWriteHandle, ServerTransform, Transaction) write} but write document
    * in a temporalCollection, which will enforce all the rules of
-   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * <a href="http://docs.marklogic.com/guide/temporal/managing">
    * bitemporal data management</a>.
    * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
    * @param metadataHandle	a handle for writing the metadata of the document
@@ -65,8 +68,9 @@ public DocumentDescriptor create(DocumentUriTemplate template,
    * @param transaction	an open transaction under which the document may have been created or deleted
    * @param temporalCollection	the name of the temporal collection existing in the database into
    *    which this document should be written
+   * @return the TemporalDescriptor with the temporal system time when the document was written
    */
-  public void write(DocumentDescriptor desc,
+  public TemporalDescriptor write(DocumentDescriptor desc,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
       ServerTransform transform,
@@ -78,7 +82,7 @@ public void write(DocumentDescriptor desc,
    * Just like {@link DocumentManager#write(String, DocumentMetadataWriteHandle,
    * AbstractWriteHandle, ServerTransform, Transaction) write} but write document
    * in a temporalCollection, which will enforce all the rules of
-   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * <a href="http://docs.marklogic.com/guide/temporal/managing">
    * bitemporal data management</a>.
    * @param docId	the URI identifier for the document
    * @param metadataHandle	a handle for writing the metadata of the document
@@ -87,8 +91,9 @@ public void write(DocumentDescriptor desc,
    * @param transaction	an open transaction under which the document may have been created or deleted
    * @param temporalCollection	the name of the temporal collection existing in the database into
    *    which this document should be written
+   * @return the TemporalDescriptor with the temporal system time when the document was written
    */
-  public void write(String docId,
+  public TemporalDescriptor write(String docId,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
       ServerTransform transform,
@@ -99,29 +104,31 @@ public void write(String docId,
   /**
    * Just like {@link DocumentManager#delete(DocumentDescriptor, Transaction) delete} but delete
    * document in a temporalCollection, which will enforce all the rules of
-   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * <a href="http://docs.marklogic.com/guide/temporal/managing">
    * bitemporal data management</a>.
    * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
    * @param transaction	an open transaction under which the document may have been created or deleted
    * @param temporalCollection	the name of the temporal collection existing in the database in
    *    which this document should be marked as deleted
+   * @return the TemporalDescriptor with the temporal system time when the document was deleted
    */
-  public void delete(DocumentDescriptor desc,
+  public TemporalDescriptor delete(DocumentDescriptor desc,
       Transaction transaction,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
 
   /**
    * Just like {@link DocumentManager#delete(String, Transaction) delete} but delete
    * document in a temporalCollection, which will enforce all the rules of
-   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * <a href="http://docs.marklogic.com/guide/temporal/managing">
    * bitemporal data management</a>.
    * @param docId	the URI identifier for the document
    * @param transaction	an open transaction under which the document may have been created or deleted
    * @param temporalCollection	the name of the temporal collection existing in the database in
    *    which this document should be marked as deleted
+   * @return the TemporalDescriptor with the temporal system time when the document was deleted
    */
-  public void delete(String docId,
+  public TemporalDescriptor delete(String docId,
       Transaction transaction,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
@@ -139,9 +146,10 @@ public void delete(String docId,
      * @param temporalCollection	the name of the temporal collection existing in the database into
      *    which this document should be written
      * @param systemTime	the application-specified system time with which this document will be marked
-     * @return the database uri that identifies the created document
+     * @return the database uri that identifies the created document,
+     *    as well as the temporal system time when the document was created
      */
-    public DocumentDescriptor create(DocumentUriTemplate template,
+    public TemporalDescriptor create(DocumentUriTemplate template,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
         ServerTransform transform,
@@ -162,8 +170,9 @@ public DocumentDescriptor create(DocumentUriTemplate template,
      * @param temporalCollection	the name of the temporal collection existing in the database into
      *    which this document should be written
      * @param systemTime	the application-specified system time with which this document will be marked
+     * @return the TemporalDescriptor with the temporal system time when the document was written
      */
-    public void write(DocumentDescriptor desc,
+    public TemporalDescriptor write(DocumentDescriptor desc,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
         ServerTransform transform,
@@ -184,8 +193,9 @@ public void write(DocumentDescriptor desc,
      * @param temporalCollection	the name of the temporal collection existing in the database into
      *    which this document should be written
      * @param systemTime	the application-specified system time with which this document will be marked
+     * @return the TemporalDescriptor with the temporal system time when the document was written
      */
-    public void write(String docId,
+    public TemporalDescriptor write(String docId,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
         ServerTransform transform,
@@ -194,6 +204,25 @@ public void write(String docId,
         java.util.Calendar systemTime)
     throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
 
+    /**
+     * Just like {@link DocumentManager#write(DocumentWriteSet, ServerTransform, Transaction)
+     *  write} but create document in a temporalCollection, which will enforce all the rules of
+     * <a href="http://docs.marklogic.com/guide/temporal/managing">
+     * bitemporal data management</a>.
+     * @param writeSet	the set of documents and metadata to write
+     * @param transform	a server transform to modify the contents of each document
+     * @param transaction	an open transaction under which the documents will be written
+     * @param temporalCollection	the name of the temporal collection existing in the database into
+     *    which this document should be written
+     * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk">REST API -&gt; Reading
+     *      and Writing Multiple Documents</a>
+     */
+    // TODO: do we return something for the temporal system time? is it per-document?
+    public void write(DocumentWriteSet writeSet,
+        ServerTransform transform,
+        Transaction transaction,
+        String temporalCollection);
+
     /**
      * Just like {@link #delete(DocumentDescriptor, Transaction, String) delete} but delete
      * document at a specified system time
@@ -202,8 +231,9 @@ public void write(String docId,
      * @param temporalCollection	the name of the temporal collection existing in the database in
      *    which this document should be marked as deleted
      * @param systemTime	the application-specified system time with which this document will be marked
+     * @return the TemporalDescriptor with the temporal system time when the document was deleted
      */
-    public void delete(DocumentDescriptor desc,
+    public TemporalDescriptor delete(DocumentDescriptor desc,
         Transaction transaction,
         String temporalCollection,
         java.util.Calendar systemTime)
@@ -217,8 +247,9 @@ public void delete(DocumentDescriptor desc,
      * @param temporalCollection	the name of the temporal collection existing in the database in
      *    which this document should be marked as deleted
      * @param systemTime	the application-specified system time with which this document will be marked
+     * @return the TemporalDescriptor with the temporal system time when the document was deleted
      */
-    public void delete(String docId,
+    public TemporalDescriptor delete(String docId,
         Transaction transaction,
         String temporalCollection,
         java.util.Calendar systemTime)