Add CtsQueryBuilder for search in Java API marklogic#1260

Author: lling

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

@@ -19,6 +19,7 @@
 import com.marklogic.client.FailedRequestException;
 import com.marklogic.client.ForbiddenUserException;
 import com.marklogic.client.io.Format;
+import com.marklogic.client.query.SearchQueryDefinition;
 import com.marklogic.client.util.RequestLogger;
 import com.marklogic.client.ResourceNotFoundException;
 import com.marklogic.client.Transaction;
@@ -582,7 +583,7 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
   DocumentPage readMetadata(Transaction transaction, String... uris);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -591,10 +592,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param start	the offset of the first document in the page (where 1 is the first result)
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start);
+  DocumentPage search(SearchQueryDefinition querydef, long start);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, String) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, String) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -604,10 +605,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param forestName a forest to limit this search
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, String forestName);
+  DocumentPage search(SearchQueryDefinition querydef, long start, String forestName);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -620,11 +621,11 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @return the DocumentPage of matching documents and metadata
    */
   /* Hide the following for now because the API isn't yet fully fleshed-out
-    DocumentPage search(QueryDefinition querydef, long start, long serverTimestamp);
+    DocumentPage search(SearchQueryDefinition querydef, long start, long serverTimestamp);
    */
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, Transaction) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -634,10 +635,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param transaction	an open transaction for matching documents
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, Transaction transaction);
+  DocumentPage search(SearchQueryDefinition querydef, long start, Transaction transaction);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, Transaction, String) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction, String) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -648,10 +649,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param forestName a forest to limit this search
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, Transaction transaction, String forestName);
+  DocumentPage search(SearchQueryDefinition querydef, long start, Transaction transaction, String forestName);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, Transaction) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage. If setMetadataCategories has
    * been called, populates metadata for each result in the format specified by
@@ -665,11 +666,11 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @return the DocumentPage of matching documents and metadata
    */
   /* Hide the following for now because the API isn't yet fully fleshed-out
-    DocumentPage search(QueryDefinition querydef, long start, long serverTimestamp, Transaction transaction);
+    DocumentPage search(SearchQueryDefinition querydef, long start, long serverTimestamp, Transaction transaction);
    */
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage.  If searchHandle is not null,
    * requests a search response and populates searchHandle with it. If setMetadataCategories has
@@ -682,10 +683,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    *     {@link #setNonDocumentFormat setNonDocumentFormat}
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, SearchReadHandle searchHandle);
+  DocumentPage search(SearchQueryDefinition querydef, long start, SearchReadHandle searchHandle);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, String) QueryManager.search}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, String) QueryManager.search}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage.  If searchHandle is not null,
    * requests a search response and populates searchHandle with it. If setMetadataCategories has
@@ -699,10 +700,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param forestName a forest to limit this search
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, SearchReadHandle searchHandle, String forestName);
+  DocumentPage search(SearchQueryDefinition querydef, long start, SearchReadHandle searchHandle, String forestName);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, Transaction)}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction)}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage.  If searchHandle is not null,
    * requests a search response and populates searchHandle with it. If setMetadataCategories has
@@ -716,10 +717,10 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param transaction	an open transaction for matching documents
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, SearchReadHandle searchHandle, Transaction transaction);
+  DocumentPage search(SearchQueryDefinition querydef, long start, SearchReadHandle searchHandle, Transaction transaction);
 
   /**
-   * Just like {@link QueryManager#search(QueryDefinition, SearchReadHandle, long, Transaction, String)}
+   * Just like {@link QueryManager#search(SearchQueryDefinition, SearchReadHandle, long, Transaction, String)}
    * but return complete documents via iterable DocumentPage.  Retrieves up to getPageLength()
    * documents in each DocumentPage.  If searchHandle is not null,
    * requests a search response and populates searchHandle with it. If setMetadataCategories has
@@ -734,7 +735,7 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
    * @param forestName a forest to limit this search
    * @return the DocumentPage of matching documents and metadata
    */
-  DocumentPage search(QueryDefinition querydef, long start, SearchReadHandle searchHandle, Transaction transaction, String forestName);
+  DocumentPage search(SearchQueryDefinition querydef, long start, SearchReadHandle searchHandle, Transaction transaction, String forestName);
 
   /** Get the maximum number of records to return in a page from calls to {@link #search search}
    *  @return the maximum number of records to return in a page from calls to
@@ -751,7 +752,7 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
 
   /**
    * Returns the format (if set) for the search response from
-   * {@link #search(QueryDefinition, long, SearchReadHandle) search} and
+   * {@link #search(SearchQueryDefinition, long, SearchReadHandle) search} and
    * metadata available from {@link DocumentRecord#getMetadata(DocumentMetadataReadHandle)
    * DocumentPage.next().getMetadata(handle)} (assuming
    * {@link #setMetadataCategories setMetadataCategories} has been called
@@ -763,7 +764,7 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
 
   /**
    * Specifies the format for the search response from
-   * {@link #search(QueryDefinition, long, SearchReadHandle) search} and
+   * {@link #search(SearchQueryDefinition, long, SearchReadHandle) search} and
    * metadata available from {@link DocumentRecord#getMetadata(DocumentMetadataReadHandle)
    * DocumentPage.next().getMetadata(handle)} (assuming
    * {@link #setMetadataCategories setMetadataCategories} has been called
@@ -775,17 +776,17 @@ <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadat
 
   /**
    * Returns the view types included in a SearchReadHandle populated by calls to
-   * {@link #search(QueryDefinition, long, SearchReadHandle) search}
+   * {@link #search(SearchQueryDefinition, long, SearchReadHandle) search}
    * @return	the view types included in a SearchReadHandle populated by calls to
-   *     {@link #search(QueryDefinition, long, SearchReadHandle) search}
+   *     {@link #search(SearchQueryDefinition, long, SearchReadHandle) search}
    */
   QueryView getSearchView();
 
   /**
    * Specifies the view types included in a SearchReadHandle populated by calls to
-   * {@link #search(QueryDefinition, long, SearchReadHandle) search}
+   * {@link #search(SearchQueryDefinition, long, SearchReadHandle) search}
    * @param view	the view types included in a SearchReadHandle populated by calls to
-   *     {@link #search(QueryDefinition, long, SearchReadHandle) search}
+   *     {@link #search(SearchQueryDefinition, long, SearchReadHandle) search}
    */
   void setSearchView(QueryView view);
 

marklogic-client-api/src/main/java/com/marklogic/client/expression/CtsQueryBuilder.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2019 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.expression;
+
+import com.marklogic.client.io.marker.JSONReadHandle;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+import com.marklogic.client.query.CtsQueryDefinition;
+import com.marklogic.client.type.CtsQueryExpr;
+
+public abstract class CtsQueryBuilder {
+
+    public final CtsExpr cts;
+    public final FnExpr fn;
+    public final GeoExpr geo;
+    public final JsonExpr json;
+    public final MapExpr map;
+    public final MathExpr math;
+    public final RdfExpr rdf;
+    public final SemExpr sem;
+    public final SpellExpr spell;
+    public final SqlExpr sql;
+    public final XdmpExpr xdmp;
+    public final XsExpr xs;
+
+    protected CtsQueryBuilder(
+            CtsExpr cts, FnExpr fn, GeoExpr geo, JsonExpr json, MapExpr map, MathExpr math, RdfExpr rdf, SemExpr sem,
+            SpellExpr spell, SqlExpr sql, XdmpExpr xdmp, XsExpr xs
+    ) {
+        this.cts = cts;
+        this.fn = fn;
+        this.geo = geo;
+        this.json = json;
+        this.map = map;
+        this.math = math;
+        this.rdf = rdf;
+        this.sem = sem;
+        this.spell = spell;
+        this.sql = sql;
+        this.xdmp = xdmp;
+        this.xs = xs;
+    }
+
+
+    public abstract CtsQueryDefinition newCtsQueryDefinition(CtsQueryExpr query);
+
+    public abstract CtsQueryDefinition newCtsQueryDefinition(CtsQueryExpr query, JSONWriteHandle queryOptions);
+
+    public abstract <T extends JSONReadHandle> T export(CtsQueryExpr query, T handle);
+}

marklogic-client-api/src/main/java/com/marklogic/client/impl/AbstractQueryDefinition.java

@@ -17,24 +17,12 @@
 
 import java.util.HashSet;
 
-import com.marklogic.client.document.ServerTransform;
 import com.marklogic.client.query.QueryDefinition;
 import java.util.Set;
 
-public abstract class AbstractQueryDefinition implements QueryDefinition {
-  protected String optionsUri = null;
+public abstract class AbstractQueryDefinition extends AbstractSearchQueryDefinition implements QueryDefinition {
   private Set<String> collections = new HashSet<>();
   private String          directory   = null;
-  private ServerTransform transform   = null;
-
-  @Override
-  public String getOptionsName() {
-    return optionsUri;
-  }
-  @Override
-  public void setOptionsName(String uri) {
-    optionsUri = uri;
-  }
 
   @Override
   public String[] getCollections() {
@@ -58,12 +46,4 @@ public void setDirectory(String directory) {
     this.directory = directory;
   }
 
-  @Override
-  public ServerTransform getResponseTransform() {
-    return transform;
-  }
-  @Override
-  public void setResponseTransform(ServerTransform transform) {
-    this.transform = transform;
-  }
 }

marklogic-client-api/src/main/java/com/marklogic/client/impl/AbstractSearchQueryDefinition.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2019 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.impl;
+
+import com.marklogic.client.document.ServerTransform;
+import com.marklogic.client.query.SearchQueryDefinition;
+
+public abstract class AbstractSearchQueryDefinition implements SearchQueryDefinition {
+
+    protected String optionsUri = null;
+    private ServerTransform transform   = null;
+
+    @Override
+    public String getOptionsName() {
+        return optionsUri;
+    }
+
+    @Override
+    public void setOptionsName(String uri) {
+        this.optionsUri = uri;
+    }
+    @Override
+    public ServerTransform getResponseTransform() {
+        return transform;
+    }
+
+    @Override
+    public void setResponseTransform(ServerTransform transform) {
+        this.transform = transform;
+    }
+}

marklogic-client-api/src/main/java/com/marklogic/client/impl/CtsQueryBuilderImpl.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2020 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.impl;
+
+import com.marklogic.client.expression.*;
+import com.marklogic.client.io.marker.JSONReadHandle;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+import com.marklogic.client.query.CtsQueryDefinition;
+import com.marklogic.client.type.CtsQueryExpr;
+
+public class CtsQueryBuilderImpl extends CtsQueryBuilder {
+     CtsQueryBuilderImpl() {
+        super(CtsExprImpl.cts,
+                FnExprImpl.fn,
+                GeoExprImpl.geo,
+                JsonExprImpl.json,
+                MapExprImpl.map,
+                MathExprImpl.math,
+                RdfExprImpl.rdf,
+                SemExprImpl.sem,
+                SpellExprImpl.spell,
+                SqlExprImpl.sql,
+                XdmpExprImpl.xdmp,
+                XsExprImpl.xs);
+    }
+
+    @Override
+    public CtsQueryDefinition newCtsQueryDefinition(CtsQueryExpr query) {
+        return new CtsQueryDefinitionImpl(query);
+    }
+
+    @Override
+    public CtsQueryDefinition newCtsQueryDefinition(CtsQueryExpr query, JSONWriteHandle queryOptions) {
+        return new CtsQueryDefinitionImpl(query, queryOptions);
+    }
+
+    @Override
+    public <T extends JSONReadHandle> T export(CtsQueryExpr query, T handle) {
+        Utilities.setHandleToString(handle, (new CtsQueryDefinitionImpl(query)).serialize());
+        return handle;
+    }
+}