Skip to content

Commit b2ee274

Browse files
author
Ryan Dew
committed
MLE-29888 Add cts expressions as allowable cts params
1 parent fa3b530 commit b2ee274

11 files changed

Lines changed: 555 additions & 13 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ xml-with-props.xml
3636
ml-development-tools/src/test/ml-modules
3737
ml-development-tools/src/test/java/com/marklogic/client/test/dbfunction/generated
3838

39+
.codesight
3940
.vscode
4041
docker/
4142

‎marklogic-client-api/src/main/java/com/marklogic/client/expression/CtsExpr.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import com.marklogic.client.type.CtsBoxSeqExpr;
2121
import com.marklogic.client.type.CtsCircleExpr;
2222
import com.marklogic.client.type.CtsCircleSeqExpr;
23+
import com.marklogic.client.type.CtsParamExpr;
2324
import com.marklogic.client.type.CtsPeriodExpr;
2425
import com.marklogic.client.type.CtsPeriodSeqExpr;
2526
import com.marklogic.client.type.CtsPointExpr;
@@ -2555,7 +2556,7 @@ public interface CtsExpr {
25552556
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_anyAtomicType.html">xs:anyAtomicType</a> server data type
25562557
* @since 8.2.0
25572558
*/
2558-
public ServerExpression param(String name);
2559+
public CtsParamExpr param(String name);
25592560
/**
25602561
* Returns a parameter placeholder for a cts expression.
25612562
*
@@ -2565,7 +2566,7 @@ public interface CtsExpr {
25652566
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_anyAtomicType.html">xs:anyAtomicType</a> server data type
25662567
* @since 8.2.0
25672568
*/
2568-
public ServerExpression param(XsStringVal name);
2569+
public CtsParamExpr param(XsStringVal name);
25692570
/**
25702571
* Returns the part of speech for a cts:token, if any.
25712572
*

‎marklogic-client-api/src/main/java/com/marklogic/client/expression/PlanBuilderBase.java‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -674,6 +674,28 @@ interface PlanBase {
674674
* @return a new instance of the Plan object with the parameter binding
675675
*/
676676
PlanBuilder.Plan bindParam(PlanParamExpr param, String literal);
677+
/**
678+
* Specifies a CTS query expression to replace a placeholder parameter during this
679+
* execution of the plan in all expressions in which the parameter appears.
680+
* <p>As when building a plan, binding a parameter constructs a new instance
681+
* of the plan with the binding instead of mutating the existing instance
682+
* of the plan.</p>
683+
* @param paramName the name of a placeholder parameter as defined by cts:param()
684+
* @param query the CTS query expression to replace the parameter
685+
* @return a new instance of the Plan object with the parameter binding
686+
*/
687+
PlanBuilder.Plan bindParam(String paramName, CtsQueryExpr query);
688+
/**
689+
* Specifies a CTS query expression to replace a placeholder parameter during this
690+
* execution of the plan in all expressions in which the parameter appears.
691+
* <p>As when building a plan, binding a parameter constructs a new instance
692+
* of the plan with the binding instead of mutating the existing instance
693+
* of the plan.</p>
694+
* @param param a placeholder parameter as constructed by cts:param()
695+
* @param query the CTS query expression to replace the parameter
696+
* @return a new instance of the Plan object with the parameter binding
697+
*/
698+
PlanBuilder.Plan bindParam(CtsParamExpr param, CtsQueryExpr query);
677699
/**
678700
* Specifies a set of documents to replace a placeholder parameter during this
679701
* execution of the plan in all expressions in which the parameter appears.

‎marklogic-client-api/src/main/java/com/marklogic/client/impl/BaseTypeImpl.java‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,25 @@
33
*/
44
package com.marklogic.client.impl;
55

6+
import com.fasterxml.jackson.databind.JsonNode;
7+
import com.fasterxml.jackson.databind.ObjectMapper;
8+
import com.fasterxml.jackson.databind.node.ArrayNode;
9+
import com.fasterxml.jackson.databind.node.ObjectNode;
10+
import com.fasterxml.jackson.core.JsonProcessingException;
11+
612
import java.lang.reflect.Array;
713
import java.util.ArrayList;
814
import java.util.Arrays;
15+
import java.util.HashMap;
916
import java.util.List;
1017
import java.util.Map;
1118
import java.util.regex.Pattern;
1219

1320
import com.marklogic.client.type.*;
1421

1522
public class BaseTypeImpl {
23+
private static final ObjectMapper JSON_MAPPER = new ObjectMapper();
24+
1625
public static interface BaseArgImpl {
1726
public StringBuilder exportAst(StringBuilder strb);
1827
}
@@ -434,6 +443,109 @@ static private boolean containsPlanParam(Object value) {
434443
return false;
435444
}
436445

446+
static String getCtsParamName(CtsParamExpr param) {
447+
if (param == null) {
448+
throw new IllegalArgumentException("param for cts query binding cannot be null");
449+
}
450+
if (!(param instanceof BaseCallImpl)) {
451+
throw new IllegalArgumentException("param for cts query binding must be a cts:param() expression");
452+
}
453+
454+
BaseCallImpl<?> paramCall = (BaseCallImpl<?>) param;
455+
if (!"cts".equals(paramCall.fnPrefix) || !"param".equals(paramCall.fnName)) {
456+
throw new IllegalArgumentException("param for cts query binding must be a cts:param() expression");
457+
}
458+
459+
BaseArgImpl[] args = paramCall.getArgsImpl();
460+
if (args == null || args.length != 1 || !(args[0] instanceof XsStringVal)) {
461+
throw new IllegalArgumentException("param for cts query binding must be a cts:param() expression");
462+
}
463+
464+
String paramName = ((XsStringVal) args[0]).getString();
465+
if (paramName == null) {
466+
throw new IllegalArgumentException("param for cts query binding must be a cts:param() expression");
467+
}
468+
469+
return paramName;
470+
}
471+
472+
static String bindCtsQueryParamsInAst(String planAst, Map<String, CtsQueryExpr> queryBindings) {
473+
if (planAst == null || queryBindings == null || queryBindings.isEmpty()) {
474+
return planAst;
475+
}
476+
477+
try {
478+
JsonNode root = JSON_MAPPER.readTree(planAst);
479+
480+
Map<String, JsonNode> bindingNodes = new HashMap<>();
481+
for (Map.Entry<String, CtsQueryExpr> binding : queryBindings.entrySet()) {
482+
String bindingName = binding.getKey();
483+
if (bindingName == null) {
484+
continue;
485+
}
486+
StringBuilder queryAst = new StringBuilder();
487+
((BaseArgImpl) binding.getValue()).exportAst(queryAst);
488+
JsonNode queryNode = JSON_MAPPER.readTree(queryAst.toString());
489+
bindingNodes.put(bindingName, queryNode);
490+
}
491+
492+
JsonNode replacedRoot = replaceCtsParamNodes(root, bindingNodes);
493+
return JSON_MAPPER.writeValueAsString(replacedRoot);
494+
} catch (JsonProcessingException ex) {
495+
throw new IllegalArgumentException("Unable to bind cts:param() query placeholder", ex);
496+
}
497+
}
498+
499+
private static JsonNode replaceCtsParamNodes(JsonNode node, Map<String, JsonNode> bindingNodes) {
500+
if (node == null) {
501+
return null;
502+
}
503+
504+
if (node.isObject()) {
505+
ObjectNode objectNode = (ObjectNode) node;
506+
507+
if (isCtsParamNode(objectNode)) {
508+
String paramName = getCtsParamNameFromAst(objectNode);
509+
JsonNode replacement = bindingNodes.get(paramName);
510+
if (replacement != null) {
511+
return replacement.deepCopy();
512+
}
513+
}
514+
515+
objectNode.fieldNames().forEachRemaining(fieldName -> {
516+
JsonNode child = objectNode.get(fieldName);
517+
JsonNode replacedChild = replaceCtsParamNodes(child, bindingNodes);
518+
if (replacedChild != child) {
519+
objectNode.set(fieldName, replacedChild);
520+
}
521+
});
522+
return objectNode;
523+
}
524+
525+
if (node.isArray()) {
526+
ArrayNode arrayNode = (ArrayNode) node;
527+
for (int i = 0; i < arrayNode.size(); i++) {
528+
JsonNode child = arrayNode.get(i);
529+
JsonNode replacedChild = replaceCtsParamNodes(child, bindingNodes);
530+
if (replacedChild != child) {
531+
arrayNode.set(i, replacedChild);
532+
}
533+
}
534+
return arrayNode;
535+
}
536+
537+
return node;
538+
}
539+
540+
private static boolean isCtsParamNode(ObjectNode node) {
541+
return "cts".equals(node.path("ns").asText()) && "param".equals(node.path("fn").asText());
542+
}
543+
544+
private static String getCtsParamNameFromAst(ObjectNode node) {
545+
JsonNode nameNode = node.path("args").path(0).path("args").path(0);
546+
return nameNode.isTextual() ? nameNode.asText() : null;
547+
}
548+
437549
static BaseArgImpl[] convertList(Object[] items) {
438550
return convertList(items, BaseArgImpl.class);
439551
}

‎marklogic-client-api/src/main/java/com/marklogic/client/impl/CtsExprImpl.java‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import com.marklogic.client.type.CtsBoxSeqExpr;
2121
import com.marklogic.client.type.CtsCircleExpr;
2222
import com.marklogic.client.type.CtsCircleSeqExpr;
23+
import com.marklogic.client.type.CtsParamExpr;
2324
import com.marklogic.client.type.CtsPeriodExpr;
2425
import com.marklogic.client.type.CtsPeriodSeqExpr;
2526
import com.marklogic.client.type.CtsPointExpr;
@@ -1686,7 +1687,7 @@ public CtsQueryExpr orQuery(ServerExpression queries, XsStringSeqVal options) {
16861687

16871688

16881689
@Override
1689-
public ServerExpression param(String name) {
1690+
public CtsParamExpr param(String name) {
16901691
if (name == null) {
16911692
throw new IllegalArgumentException("name parameter for param() cannot be null");
16921693
}
@@ -1695,11 +1696,11 @@ public ServerExpression param(String name) {
16951696

16961697

16971698
@Override
1698-
public ServerExpression param(XsStringVal name) {
1699+
public CtsParamExpr param(XsStringVal name) {
16991700
if (name == null) {
17001701
throw new IllegalArgumentException("name parameter for param() cannot be null");
17011702
}
1702-
return new XsExprImpl.AnyAtomicTypeCallImpl("cts", "param", new Object[]{ name });
1703+
return new ParamCallImpl("cts", "param", new Object[]{ name });
17031704
}
17041705

17051706

@@ -2339,6 +2340,11 @@ static class QueryCallImpl extends BaseTypeImpl.ServerExpressionCallImpl impleme
23392340
super(fnPrefix, fnName, fnArgs);
23402341
}
23412342
}
2343+
static class ParamCallImpl extends BaseTypeImpl.ServerExpressionCallImpl implements CtsParamExpr {
2344+
ParamCallImpl(String fnPrefix, String fnName, Object[] fnArgs) {
2345+
super(fnPrefix, fnName, fnArgs);
2346+
}
2347+
}
23422348

23432349
@Override
23442350
public CtsReferenceSeqExpr referenceSeq(CtsReferenceExpr... items) {

‎marklogic-client-api/src/main/java/com/marklogic/client/impl/PlanBuilderSubImpl.java‎

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
import com.fasterxml.jackson.databind.node.ObjectNode;
1111
import com.marklogic.client.document.DocumentWriteOperation;
1212
import com.marklogic.client.document.DocumentWriteSet;
13+
import com.marklogic.client.io.Format;
14+
import com.marklogic.client.io.StringHandle;
1315
import com.marklogic.client.expression.*;
1416
import com.marklogic.client.impl.BaseTypeImpl.BaseArgImpl;
1517
import com.marklogic.client.io.marker.AbstractWriteHandle;
@@ -843,6 +845,7 @@ static class PlanSubImpl
843845

844846
private Map<PlanParamBase,BaseTypeImpl.ParamBinder> params = null;
845847
private List<ContentParam> contentParams;
848+
private Map<String,CtsQueryExpr> queryBindings;
846849

847850
PlanSubImpl(PlanBuilderBaseImpl.PlanBaseImpl prior, String fnPrefix, String fnName, Object[] fnArgs) {
848851
super(prior, fnPrefix, fnName, fnArgs);
@@ -854,10 +857,12 @@ static class PlanSubImpl
854857
private PlanSubImpl(
855858
PlanBuilderBaseImpl.PlanBaseImpl prior, String fnPrefix, String fnName, Object[] fnArgs,
856859
Map<PlanParamBase,BaseTypeImpl.ParamBinder> params,
857-
List<ContentParam> contentParams) {
860+
List<ContentParam> contentParams,
861+
Map<String,CtsQueryExpr> queryBindings) {
858862
this(prior, fnPrefix, fnName, fnArgs);
859863
this.params = params;
860864
this.contentParams = contentParams;
865+
this.queryBindings = queryBindings;
861866
}
862867

863868
@Override
@@ -930,6 +935,30 @@ public Plan bindParam(PlanParamExpr param, String literal) {
930935
return bindParam(param, new XsValueImpl.StringValImpl(literal));
931936
}
932937
@Override
938+
public Plan bindParam(String paramName, CtsQueryExpr query) {
939+
if (paramName == null) {
940+
throw new IllegalArgumentException("paramName for cts query binding cannot be null");
941+
}
942+
if (query == null) {
943+
throw new IllegalArgumentException("query for cts query binding cannot be null");
944+
}
945+
946+
Map<String,CtsQueryExpr> nextQueryBindings = new HashMap<>();
947+
if (this.queryBindings != null) {
948+
nextQueryBindings.putAll(this.queryBindings);
949+
}
950+
nextQueryBindings.put(paramName, query);
951+
952+
return new PlanSubImpl(
953+
this.prior, this.fnPrefix, this.fnName, this.fnArgs,
954+
this.params, this.contentParams, nextQueryBindings
955+
);
956+
}
957+
@Override
958+
public Plan bindParam(CtsParamExpr param, CtsQueryExpr query) {
959+
return bindParam(BaseTypeImpl.getCtsParamName(param), query);
960+
}
961+
@Override
933962
public Plan bindParam(PlanParamExpr param, PlanParamBindingVal literal) {
934963
if (!(param instanceof PlanParamBase)) {
935964
throw new IllegalArgumentException("param must be an instance of PlanParamBase");
@@ -950,7 +979,7 @@ public Plan bindParam(PlanParamExpr param, PlanParamBindingVal literal) {
950979
throw new IllegalArgumentException("cannot set value with unknown implementation");
951980
}
952981

953-
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, nextParams, this.contentParams);
982+
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, nextParams, this.contentParams, this.queryBindings);
954983
}
955984

956985
@Override
@@ -968,7 +997,7 @@ public Plan bindParam(PlanParamExpr param, DocumentWriteSet writeSet) {
968997
nextContentParams.addAll(this.contentParams);
969998
}
970999
nextContentParams.add(ContentParam.fromDocumentWriteSet((PlanParamBase) param, writeSet));
971-
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, this.params, nextContentParams);
1000+
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, this.params, nextContentParams, this.queryBindings);
9721001
}
9731002

9741003
@Override
@@ -992,7 +1021,17 @@ public Plan bindParam(PlanParamExpr param, AbstractWriteHandle content, Map<Stri
9921021
nextContentParams.addAll(this.contentParams);
9931022
}
9941023
nextContentParams.add(new ContentParam(baseParam, content, columnAttachments));
995-
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, this.params, nextContentParams);
1024+
return new PlanSubImpl(this.prior, this.fnPrefix, this.fnName, this.fnArgs, this.params, nextContentParams, this.queryBindings);
1025+
}
1026+
1027+
@Override
1028+
public AbstractWriteHandle getHandle() {
1029+
if (queryBindings == null || queryBindings.isEmpty()) {
1030+
return super.getHandle();
1031+
}
1032+
1033+
String boundAst = BaseTypeImpl.bindCtsQueryParamsInAst(getAst(), queryBindings);
1034+
return new StringHandle(boundAst).withFormat(Format.JSON);
9961035
}
9971036
@Override
9981037
public List<ContentParam> getContentParams() {

‎marklogic-client-api/src/main/java/com/marklogic/client/impl/RowManagerImpl.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2010-2025 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
2+
* Copyright (c) 2010-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
33
*/
44
package com.marklogic.client.impl;
55

@@ -32,6 +32,8 @@
3232
import com.marklogic.client.io.*;
3333
import com.marklogic.client.io.marker.*;
3434
import com.marklogic.client.row.*;
35+
import com.marklogic.client.type.CtsQueryExpr;
36+
import com.marklogic.client.type.CtsParamExpr;
3537
import com.marklogic.client.type.PlanExprCol;
3638
import com.marklogic.client.type.PlanParamBindingVal;
3739
import com.marklogic.client.type.PlanParamExpr;
@@ -1718,6 +1720,18 @@ public Plan bindParam(PlanParamExpr param, String literal) {
17181720
return bindParam(param, new XsValueImpl.StringValImpl(literal));
17191721
}
17201722
@Override
1723+
public Plan bindParam(String paramName, CtsQueryExpr query) {
1724+
throw new UnsupportedOperationException(
1725+
"Binding cts:param() query placeholders is not supported for raw plans; use a built plan from PlanBuilder"
1726+
);
1727+
}
1728+
@Override
1729+
public Plan bindParam(CtsParamExpr param, CtsQueryExpr query) {
1730+
throw new UnsupportedOperationException(
1731+
"Binding cts:param() query placeholders is not supported for raw plans; use a built plan from PlanBuilder"
1732+
);
1733+
}
1734+
@Override
17211735
public Plan bindParam(PlanParamExpr param, PlanParamBindingVal literal) {
17221736
if (!(param instanceof PlanBuilderBaseImpl.PlanParamBase)) {
17231737
throw new IllegalArgumentException("cannot set parameter that doesn't extend base");

‎marklogic-client-api/src/main/java/com/marklogic/client/type/CtsParamExpr.java‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
/*
2+
* Copyright (c) 2010-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
3+
*/
4+
package com.marklogic.client.type;
5+
6+
// IMPORTANT: Do not edit. This file is generated.
7+
8+
/**
9+
* An instance of a placeholder parameter returned by a call
10+
* to cts:param() that can represent a cts expression
11+
* and can be passed on a bind() call to be assigned a
12+
* cts query expression when invoking a row pipeline.
13+
*/
14+
public interface CtsParamExpr extends ServerExpression {
15+
}

0 commit comments

Comments
 (0)