RowBatcher for raw AST and QueryDSL #1271

ehennum · ehennum · commit 50fee8b2593f · 2020-12-30T08:48:38.000-08:00
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/RowBatcher.java b/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/RowBatcher.java
@@ -18,6 +18,11 @@
 import com.marklogic.client.expression.PlanBuilder;
 import com.marklogic.client.expression.PlanBuilder.ModifyPlan;
 import com.marklogic.client.io.marker.ContentHandle;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+import com.marklogic.client.io.marker.TextWriteHandle;
+import com.marklogic.client.row.RawPlanDefinition;
+import com.marklogic.client.row.RawQueryDSLPlan;
+import com.marklogic.client.row.RawSQLPlan;
 import com.marklogic.client.row.RowManager;
 import com.marklogic.client.type.PlanCondition;
 import com.marklogic.client.type.PlanExprColSeq;
@@ -114,11 +119,31 @@ public interface RowBatcher<T> extends Batcher {
     RowManager getRowManager();
 
     /**
-     * Specifies the plan for getting rows from a view.
-     * @param viewPlan the view providing the rows exported by the RowBatcher
+     * Specifies the plan for getting rows from a view
+     * with PlanBuilder.
+     * @see RowManager#newPlanBuilder()
+     * @see PlanBuilder#fromView(String, String) 
+     * @param viewPlan the PlanBuilder view providing the rows exported by the RowBatcher
      * @return the RowBatcher for chaining other initializations
      */
     RowBatcher<T> withBatchView(PlanBuilder.ModifyPlan viewPlan);
+    /**
+     * Specifies the plan for getting rows from a view
+     * from a serialized AST in JSON format.
+     * @see RowManager#newRawPlanDefinition(JSONWriteHandle) 
+     * @param viewPlan the raw AST for the rows exported by the RowBatcher
+     * @return the RowBatcher for chaining other initializations
+     */
+    RowBatcher<T> withBatchView(RawPlanDefinition viewPlan);
+    /**
+     * Specifies the plan for getting rows from a view
+     * from a serialized Query DSL in JavaScript format.
+     * @see RowManager#newRawQueryDSLPlan(TextWriteHandle) 
+     * @param viewPlan the raw Query DSL for the rows exported by the RowBatcher
+     * @return the RowBatcher for chaining other initializations
+     */
+    RowBatcher<T> withBatchView(RawQueryDSLPlan viewPlan);
+
     /**
      * Enables retrieval of rows that were  present in the view
      * at the time that the first batch was retrieved, ignoring
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/impl/RowBatcherImpl.java b/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/impl/RowBatcherImpl.java
@@ -26,9 +26,12 @@
 import com.marklogic.client.io.Format;
 import com.marklogic.client.io.JacksonHandle;
 import com.marklogic.client.io.StringHandle;
+import com.marklogic.client.io.marker.AbstractWriteHandle;
 import com.marklogic.client.io.marker.ContentHandle;
 import com.marklogic.client.io.marker.StructureReadHandle;
 import com.marklogic.client.row.RawPlanDefinition;
+import com.marklogic.client.row.RawQueryDSLPlan;
+import com.marklogic.client.row.RawSQLPlan;
 import com.marklogic.client.row.RowManager;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -56,7 +59,6 @@ class RowBatcherImpl<T>  extends BatcherImpl implements RowBatcher<T> {
     private RowBatchFailureListener[] failureListeners;
     private RowBatchSuccessListener[] sucessListeners;
 
-    private PlanBuilder.ModifyPlan inputPlan;
     private String schemaName;
     private String viewName;
 
@@ -103,16 +105,27 @@ public RowManager getRowManager() {
 
     @Override
     public RowBatcher<T> withBatchView(PlanBuilder.ModifyPlan inputPlan) {
-        requireNotStarted("Must specify batch view before starting job");
-        analyzePlan(inputPlan);
+        if (inputPlan == null)
+            throw new IllegalArgumentException("Plan cannot be null");
+        analyzePlan(inputPlan.export(new StringHandle().withFormat(Format.JSON)));
         return this;
     }
-    private void analyzePlan(PlanBuilder.ModifyPlan inputPlan) {
-        if (inputPlan == null)
-            throw new IllegalArgumentException("modify plan cannot be null");
-        this.inputPlan = inputPlan;
-
-        StringHandle initialPlan = inputPlan.export(new StringHandle().withFormat(Format.JSON));
+    @Override
+    public RowBatcher<T> withBatchView(RawPlanDefinition viewPlan) {
+        if (viewPlan == null)
+            throw new IllegalArgumentException("Raw plan definition cannot be null");
+        analyzePlan(viewPlan.getHandle());
+        return this;
+    }
+    @Override
+    public RowBatcher<T> withBatchView(RawQueryDSLPlan viewPlan) {
+        if (viewPlan == null)
+            throw new IllegalArgumentException("Raw query DSL plan cannot be null");
+        analyzePlan(viewPlan.getHandle());
+        return this;
+    }
+    private void analyzePlan(AbstractWriteHandle initialPlan) {
+        requireNotStarted("Must specify batch view before starting job");
 
         DatabaseClientImpl client = (DatabaseClientImpl) getPrimaryClient();
         JsonNode viewInfo = client.getServices().postResource(
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/impl/RowManagerImpl.java b/marklogic-client-api/src/main/java/com/marklogic/client/impl/RowManagerImpl.java
@@ -119,7 +119,7 @@ public RawPlanDefinition newRawPlanDefinition(JSONWriteHandle handle) {
   }
 
   @Override
-  public RawQueryDSLPlan newQueryDSLPlan(TextWriteHandle handle) {
+  public RawQueryDSLPlan newRawQueryDSLPlan(TextWriteHandle handle) {
     return new RawQueryDSLPlanImpl(handle);
   }
   @Override
@@ -1604,16 +1604,19 @@ static class RawSQLPlanImpl extends RawPlanImpl<TextWriteHandle> implements RawS
       super(handle, params);
     }
 
+    @Override
     RawSQLPlanImpl parameterize(
             TextWriteHandle handle, Map<PlanBuilderBaseImpl.PlanParamBase,BaseTypeImpl.ParamBinder> params
     ) {
       return new RawSQLPlanImpl(handle, params);
     }
+    @Override
     void configHandle(BaseHandle handle) {
       handle.setFormat(Format.TEXT);
       handle.setMimetype("application/sql");
     }
 
+    @Override
     public RawSQLPlan withHandle(TextWriteHandle handle) {
       setHandle(handle);
       return this;
@@ -1629,16 +1632,19 @@ static class RawSPARQLSelectPlanImpl extends RawPlanImpl<TextWriteHandle> implem
       super(handle, params);
     }
 
+    @Override
     RawSPARQLSelectPlanImpl parameterize(
             TextWriteHandle handle, Map<PlanBuilderBaseImpl.PlanParamBase,BaseTypeImpl.ParamBinder> params
     ) {
       return new RawSPARQLSelectPlanImpl(handle, params);
     }
+    @Override
     void configHandle(BaseHandle handle) {
       handle.setFormat(Format.TEXT);
       handle.setMimetype("application/sparql-query");
     }
 
+    @Override
     public RawSPARQLSelectPlan withHandle(TextWriteHandle handle) {
       setHandle(handle);
       return this;
@@ -1654,16 +1660,19 @@ static class RawQueryDSLPlanImpl extends RawPlanImpl<TextWriteHandle> implements
       super(handle, params);
     }
 
+    @Override
     RawQueryDSLPlanImpl parameterize(
             TextWriteHandle handle, Map<PlanBuilderBaseImpl.PlanParamBase,BaseTypeImpl.ParamBinder> params
     ) {
       return new RawQueryDSLPlanImpl(handle, params);
     }
+    @Override
     void configHandle(BaseHandle handle) {
       handle.setFormat(Format.TEXT);
       handle.setMimetype("application/vnd.marklogic.querydsl+javascript");
     }
 
+    @Override
     public RawQueryDSLPlan withHandle(TextWriteHandle handle) {
       setHandle(handle);
       return this;
@@ -1679,11 +1688,13 @@ private RawPlanDefinitionImpl(
       super(handle, params);
     }
 
+    @Override
     RawPlanDefinitionImpl parameterize(
             JSONWriteHandle handle, Map<PlanBuilderBaseImpl.PlanParamBase,BaseTypeImpl.ParamBinder> params
     ) {
       return new RawPlanDefinitionImpl(handle, params);
     }
+    @Override
     void configHandle(BaseHandle handle) {
       handle.setFormat(Format.JSON);
       handle.setMimetype("application/json");
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/row/RawPlan.java b/marklogic-client-api/src/main/java/com/marklogic/client/row/RawPlan.java
@@ -17,5 +17,10 @@
 
 import com.marklogic.client.expression.PlanBuilder;
 
+/**
+ * An abstraction for a serialization of a plan
+ * such as an AST in JSON format, a Query DSL in JavaScript syntax,
+ * or a SQL or SPARQL SELECT query.
+ */
 public interface RawPlan extends PlanBuilder.Plan {
 }
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/row/RawQueryDSLPlan.java b/marklogic-client-api/src/main/java/com/marklogic/client/row/RawQueryDSLPlan.java
@@ -17,8 +17,25 @@
 
 import com.marklogic.client.io.marker.TextWriteHandle;
 
+/**
+ * A Raw Query DSL Plan provides access to a plan
+ * expressed in JavaScript syntax.
+ */
 public interface RawQueryDSLPlan extends RawPlan {
+    /**
+     * Returns the handle for the text of the JavaScript representation of the Query DSL.
+     * @return	the text handle for the JavaScript serialization
+     */
     TextWriteHandle getHandle();
+    /**
+     * Specifies the handle for the text of the JavaScript representation of the Query DSL.
+     * @param handle	the text handle for the JavaScript serialization
+     */
     void setHandle(TextWriteHandle handle);
+    /**
+     * Assigns the handle and returns the raw plan as a convenience.
+     * @param handle	the text handle for the JavaScript serialization
+     * @return	this raw plan object
+     */
     RawQueryDSLPlan withHandle(TextWriteHandle handle);
 }
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/row/RawSPARQLSelectPlan.java b/marklogic-client-api/src/main/java/com/marklogic/client/row/RawSPARQLSelectPlan.java
@@ -17,8 +17,26 @@
 
 import com.marklogic.client.io.marker.TextWriteHandle;
 
+/**
+ * A Raw SPARQL Select Plan provides access to a plan
+ * expressed as a SPARQL SELECT statement.  A SPARQL query can only
+ * represent a subset of the capabilities of a plan.
+ */
 public interface RawSPARQLSelectPlan extends RawPlan {
+    /**
+     * Returns the handle for the text of the SPARQL query.
+     * @return	the text handle for the SPARQL query
+     */
     TextWriteHandle getHandle();
+    /**
+     * Specifies the handle for the text of the SPARQL query.
+     * @param handle	the text handle for the SPARQL query
+     */
     void setHandle(TextWriteHandle handle);
+    /**
+     * Assigns the handle and returns the raw plan as a convenience.
+     * @param handle	the text handle for the SPARQL query
+     * @return	this raw plan object
+     */
     RawSPARQLSelectPlan withHandle(TextWriteHandle handle);
 }
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/row/RawSQLPlan.java b/marklogic-client-api/src/main/java/com/marklogic/client/row/RawSQLPlan.java
@@ -17,8 +17,26 @@
 
 import com.marklogic.client.io.marker.TextWriteHandle;
 
+/**
+ * A Raw SQL Plan provides access to a plan
+ * expressed as an SQL SELECT statement.  An SQL query can only
+ * represent a subset of the capabilities of a plan.
+ */
 public interface RawSQLPlan extends RawPlan {
+    /**
+     * Returns the handle for the text of the SQL query.
+     * @return	the text handle for the SQL query
+     */
     TextWriteHandle getHandle();
+    /**
+     * Specifies the handle for the text of the SQL query.
+     * @param handle	the text handle for the SQL query
+     */
     void setHandle(TextWriteHandle handle);
+    /**
+     * Assigns the handle and returns the raw plan as a convenience.
+     * @param handle	the text handle for the SQL query
+     * @return	this raw plan object
+     */
     RawSQLPlan withHandle(TextWriteHandle handle);
 }
diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/row/RowManager.java b/marklogic-client-api/src/main/java/com/marklogic/client/row/RowManager.java
@@ -80,17 +80,29 @@ public enum RowStructure{ARRAY, OBJECT}
 
     /**
      * Defines a plan from a JSON serialization of the plan AST (Abstract Syntax Tree).
-     * @param	handle a handle for a JSON serialization of a PlanAST
+     * @param	handle a handle for a JSON serialization of a plan AST
      * @return	a plan for constructing and retrieving database rows
      */
     RawPlanDefinition newRawPlanDefinition(JSONWriteHandle handle);
-
-// TODO: JavaDoc
-    RawQueryDSLPlan newQueryDSLPlan(TextWriteHandle handle);
+    /**
+     * Defines a plan from a Query DSL in a JavaScript serialization.
+     * @param handle a textual handle for Query DSL in JavaScript format
+     * @return	a plan for constructing and retrieving database rows
+     */
+    RawQueryDSLPlan newRawQueryDSLPlan(TextWriteHandle handle);
+    /**
+     * Defines a plan from an SQL query.
+     * @param handle a textual handle for the SQL serialization
+     * @return	a plan for constructing and retrieving database rows
+     */
     RawSQLPlan newRawSQLPlan(TextWriteHandle handle);
+    /**
+     * Defines a plan from a SPARQL SELECT query.
+     * @param handle a textual handle for the SPARQL serialization
+     * @return	a plan for constructing and retrieving database rows
+     */
     RawSPARQLSelectPlan newRawSPARQLSelectPlan(TextWriteHandle handle);
 
-
     /**
      * Constructs and retrieves a set of database rows based on a plan using
      * a map interface for the column values in each row.
diff --git a/marklogic-client-api/src/test/java/com/marklogic/client/test/RowManagerTest.java b/marklogic-client-api/src/test/java/com/marklogic/client/test/RowManagerTest.java
@@ -846,20 +846,40 @@ private DOMHandle initNamespaces(DOMHandle handle) {
 
     return handle;
   }
-// TODO: query and results
-  // @Test
+  @Test
   public void testRawSQL() throws IOException {
     String plan = "SELECT *\n" +
-            "FROM opticUnitTest.musician\n" +
+            "FROM opticUnitTest.musician AS ''\n" +
+            "WHERE lastName IN ('Armstrong', 'Davis')" +
             "ORDER BY lastName;\n";
+
+    RowManager rowMgr = Common.client.newRowManager();
+
+    testViewRows(rowMgr.resultRows(rowMgr.newRawSQLPlan(new StringHandle(plan))));
   }
-// TODO: query and results
-  // @Test
+  @Test
   public void testRawSPARQLSelect() throws IOException {
-    String plan = "PREFIX dc: <http://purl.org/dc/terms/>\n" +
-            "SELECT ?datastore ?title\n" +
-            "WHERE {?datastore dc:type <http://purl.org/dc/dcmitype/Dataset> ; dc:title ?title .}\n" +
-            "ORDER BY ?title\n";
+    String plan = "PREFIX rg: <http://example.org/rowgraph/>\n" +
+            "SELECT ?graph ?object1 ?object2\n" +
+            "WHERE {?graph rg:p1 ?object1 ; rg:p2 ?object2}\n" +
+            "ORDER BY ?graph";
+
+    String[] graph   = {"http://example.org/rowgraph/s1", "http://example.org/rowgraph/s2"};
+    String[] object1 = {"http://example.org/rowgraph/o1", "http://example.org/rowgraph/o3"};
+    String[] object2 = {"http://example.org/rowgraph/o2", "http://example.org/rowgraph/o4"};
+
+    RowManager rowMgr = Common.client.newRowManager();
+
+    RowSet<RowRecord> rows = rowMgr.resultRows(rowMgr.newRawSPARQLSelectPlan(new StringHandle(plan)));
+
+    int rowNum = 0;
+    for (RowRecord row: rows) {
+      assertEquals("unexpected graph value in row record "+rowNum,   graph[rowNum],   row.getString("graph"));
+      assertEquals("unexpected object1 value in row record "+rowNum, object1[rowNum], row.getString("object1"));
+      assertEquals("unexpected object2 value in row record "+rowNum, object2[rowNum], row.getString("object2"));
+      rowNum++;
+    }
+    assertEquals("unexpected count of result records", 2, rowNum);
   }
   @Test
   public void testRawQueryDSL() throws IOException {
@@ -874,7 +894,7 @@ public void testRawQueryDSL() throws IOException {
 
     RowManager rowMgr = Common.client.newRowManager();
 
-    testViewRows(rowMgr.resultRows(rowMgr.newQueryDSLPlan(new StringHandle(plan))));
+    testViewRows(rowMgr.resultRows(rowMgr.newRawQueryDSLPlan(new StringHandle(plan))));
   }
   private void checkSingleRow(NodeList row, RowSetPart datatypeStyle) {
     assertEquals("unexpected column count in XML", 2, row.getLength());
diff --git a/marklogic-client-api/src/test/java/com/marklogic/client/test/datamovement/RowBatcherTest.java b/marklogic-client-api/src/test/java/com/marklogic/client/test/datamovement/RowBatcherTest.java

Original file line number	Diff line number	Diff line change
`@@ -17,5 +17,10 @@`
`17`	`17`
`18`	`18`	`import com.marklogic.client.expression.PlanBuilder;`
`19`	`19`
	`20`	`+/**`
	`21`	`+ * An abstraction for a serialization of a plan`
	`22`	`+ * such as an AST in JSON format, a Query DSL in JavaScript syntax,`
	`23`	`+ * or a SQL or SPARQL SELECT query.`
	`24`	`+ */`
`20`	`25`	`public interface RawPlan extends PlanBuilder.Plan {`
`21`	`26`	`}`