Merge pull request #1623 from marklogic/feature/search-timestamp

Exposing read/search methods that accept a server timestamp

Author: rjrudin

marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/fastfunctest/ReadAndSearchWithTimestampTest.java

@@ -0,0 +1,44 @@
+package com.marklogic.client.fastfunctest;
+
+import com.marklogic.client.document.GenericDocumentManager;
+import com.marklogic.client.io.SearchHandle;
+import com.marklogic.client.query.QueryManager;
+import com.marklogic.client.query.StructuredQueryDefinition;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * Added in 6.4.1; the 5 methods had been commented out with a comment indicating that the server APIs
+ * were not fully fleshed out, but those APIs - specifically, how the REST API receives a server timestamp - have long
+ * been present in the REST API.
+ */
+public class ReadAndSearchWithTimestampTest extends AbstractFunctionalTest {
+
+	@Test
+	void test() {
+		final String collection = "timestamp-test";
+		final String[] uris = writeJsonDocs(2, collection).toArray(new String[]{});
+
+		final QueryManager queryManager = client.newQueryManager();
+		final GenericDocumentManager docManager = client.newDocumentManager();
+		final StructuredQueryDefinition collectionQuery = queryManager.newStructuredQueryBuilder().collection(collection);
+
+		SearchHandle searchResults = queryManager.search(collectionQuery, new SearchHandle());
+		assertEquals(2, searchResults.getTotalResults());
+		final long serverTimestamp = searchResults.getServerTimestamp();
+		logger.info("Server timestamp: " + serverTimestamp);
+
+		// Write additional docs to the same collection and verify they are not returned by subsequent point-in-time
+		// queries. Note that the first 2 URIs are the same as the ones originally written.
+		writeJsonDocs(5, collection);
+
+		// Verify each of the exposed methods in 6.4.1
+		assertEquals(2, docManager.read(serverTimestamp, uris).size());
+		assertEquals(2, docManager.read(serverTimestamp, null, uris).size());
+		assertEquals(2, docManager.search(collectionQuery, 1, serverTimestamp).size());
+
+		assertEquals(5, docManager.search(collectionQuery, 1).size(),
+			"A query without a timestamp should return all of the documents in the collection.");
+	}
+}

marklogic-client-api/src/main/java/com/marklogic/client/document/DocumentManager.java

@@ -463,10 +463,9 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    *   server via getServerTimestamp() on any handle.
    * @param uris the database uris identifying documents to retrieve
    * @return the DocumentPage of matching documents and metadata
+   * @since 6.4.1
    */
-  /* Hide the following for now because the API isn't yet fully fleshed-out
     DocumentPage read(long serverTimestamp, String... uris);
-   */
 
   /**
    * Reads from the database a list of documents matching the provided uris.  Allows
@@ -492,10 +491,9 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param transform the transform to be run on the server on each document (must already be installed)
    * @param uris the database uris identifying documents to retrieve
    * @return the DocumentPage of matching documents and metadata
+   * @since 6.4.1
    */
-  /* Hide the following for now because the API isn't yet fully fleshed-out
     DocumentPage read(long serverTimestamp, ServerTransform transform, String... uris);
-   */
 
   /**
    * Reads from the database a list of documents matching the provided uris.  Allows
@@ -509,23 +507,6 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    */
   DocumentPage read(Transaction transaction, String... uris);
 
-  /**
-   * Reads from the database a list of documents matching the provided uris.  Allows
-   * iteration across matching documents and metadata (only if setMetadataCategories
-   * has been called to request metadata).  To find out how many of your uris matched,
-   * call the {@link DocumentPage#size() DocumentPage.size()} method.
-   *
-   * @param serverTimestamp the point in time at which to read these
-   *   documents.  The value must be a merge timestamp obtained from the
-   *   server via getServerTimestamp() on any handle.
-   * @param transaction the transaction in which this read is participating
-   * @param uris the database uris identifying documents to retrieve
-   * @return the DocumentPage of matching documents and metadata
-   */
-  /* Hide the following for now because the API isn't yet fully fleshed-out
-    DocumentPage read(long serverTimestamp, Transaction transaction, String... uris);
-   */
-
   /**
    * Reads from the database a list of documents matching the provided uris.  Allows
    * iteration across matching documents and metadata (only if setMetadataCategories
@@ -539,24 +520,6 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    */
   DocumentPage read(ServerTransform transform, Transaction transaction, String... uris);
 
-  /**
-   * Reads from the database a list of documents matching the provided uris.  Allows
-   * iteration across matching documents and metadata (only if setMetadataCategories
-   * has been called to request metadata).  To find out how many of your uris matched,
-   * call the {@link DocumentPage#size() DocumentPage.size()} method.
-   *
-   * @param serverTimestamp the point in time at which to read these
-   *   documents.  The value must be a merge timestamp obtained from the
-   *   server via getServerTimestamp() on any handle.
-   * @param transform the transform to be run on the server on each document (must already be installed)
-   * @param transaction the transaction in which this read is participating
-   * @param uris the database uris identifying documents to retrieve
-   * @return the DocumentPage of matching documents and metadata
-   */
-  /* Hide the following for now because the API isn't yet fully fleshed-out
-    DocumentPage read(long serverTimestamp, ServerTransform transform, Transaction transaction, String... uris);
-   */
-
   /**
    * Reads from the database the metadata for a list of documents matching the
    * provided uris.  Allows iteration across the metadata for matching documents
@@ -619,10 +582,9 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    *   documents.  The value must be a merge timestamp obtained from the
    *   server via getServerTimestamp() on any handle.
    * @return the DocumentPage of matching documents and metadata
+   * @since 6.4.1
    */
-  /* Hide the following for now because the API isn't yet fully fleshed-out
     DocumentPage search(SearchQueryDefinition querydef, long start, long serverTimestamp);
-   */
 
   /**
    * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction) QueryManager.search}