Merge pull request #1610 from marklogic/feature/1603-docs

#1603 Deprecating the `directory` method that receives a depth value

Author: rjrudin

examples/src/main/java/com/marklogic/client/example/cookbook/datamovement/BulkLoadFromJdbcRaw.java

@@ -193,7 +193,7 @@ public void load() throws IOException, SQLException {
 
   public void transform() throws IOException, SQLException {
     // search for all records in the /employees/ directory
-    StructuredQueryDefinition query = new StructuredQueryBuilder().directory(1, "/employees/");
+    StructuredQueryDefinition query = new StructuredQueryBuilder().directory(false, "/employees/");
 
     // the QueryBatcher efficiently paginates through matching batches from all
     // appropriate nodes in the cluster then applies the transform on each batch

examples/src/main/java/com/marklogic/client/example/cookbook/datamovement/ExtractRowsViaTemplate.java

@@ -63,7 +63,7 @@ public static void main(String[] args) throws ParseException, IOException {
 
   public void run() throws ParseException, IOException {
     setup();
-    StructuredQueryDefinition query = new StructuredQueryBuilder().directory(1, "/employees/");
+    StructuredQueryDefinition query = new StructuredQueryBuilder().directory(false, "/employees/");
     QueryBatcher qb = moveMgr.newQueryBatcher(query)
       .onUrisReady(
         // This object will be closed by the QueryBatcher when stopJob is

marklogic-client-api/src/main/java/com/marklogic/client/query/StructuredQueryBuilder.java

@@ -469,7 +469,11 @@ public StructuredQueryDefinition directory(boolean isInfinite, String... uris) {
    * A value of 1 means to exclude subdirectories.
    * @param uris    the identifiers for the criteria directories
    * @return    the StructuredQueryDefinition for the directory query
+   * @deprecated  since 4.6.1; a directory query in MarkLogic does not support custom depths; it is either limited
+   * to the given directory or it is "infinite". For that reason, prefer the {@code directory} method that accepts a
+   * boolean indicating whether the directory query is infinite.
    */
+  @Deprecated
   public StructuredQueryDefinition directory(int depth, String... uris) {
     return new DirectoryQuery(depth, uris);
   }

marklogic-client-api/src/test/java/com/marklogic/client/test/BulkReadWriteTest.java

@@ -197,7 +197,7 @@ public void testC_BulkSearch() {
     SearchHandle searchHandle = new SearchHandle();
     int pageLength = 100;
     docMgr.setPageLength(pageLength);
-    DocumentPage page = docMgr.search(new StructuredQueryBuilder().directory(1, DIRECTORY), 1, searchHandle);
+    DocumentPage page = docMgr.search(new StructuredQueryBuilder().directory(false, DIRECTORY), 1, searchHandle);
     try {
       for ( DocumentRecord record : page ) {
         validateRecord(record);

marklogic-client-api/src/test/java/com/marklogic/client/test/MarkLogicCloudAuthenticationDebugger.java

@@ -49,7 +49,7 @@ public static void main(String[] args) throws Exception {
 		}
 
 		System.out.println(client.newQueryManager().search(
-			client.newQueryManager().newStructuredQueryBuilder().directory(0, "/")
+			client.newQueryManager().newStructuredQueryBuilder().directory(true, "/")
 			, new JacksonHandle()).get().toPrettyString());
 
 		System.out.println("Successfully finished cloud-based authentication test");

marklogic-client-api/src/test/java/com/marklogic/client/test/datamovement/QueryBatcherFailureTest.java

@@ -40,7 +40,7 @@ public void invalidQuery() {
 
         FailedRequestException ex = assertThrows(FailedRequestException.class, () ->
             client.newDataMovementManager().newQueryBatcher(
-                client.newQueryManager().newStructuredQueryBuilder().directory(0, "/invalid/path")
+                client.newQueryManager().newStructuredQueryBuilder().directory(false, "/invalid/path")
             ).onQueryFailure(failure -> failureMessages.add(failure.getMessage()))
         );