MLE-27881 Add cts.param support to Java Client API#1936
MLE-27881 Add cts.param support to Java Client API#1936rjdew-progress wants to merge 1 commit intodevelopfrom
Conversation
rjdew-progress
requested review from
BillFarber,
rjrudin and
stevebio
as code owners
There was a problem hiding this comment.
Pull request overview
Adds Java Optic API support for cts:param() so callers can place placeholders inside cts expressions, and adds a client-side guard to reject op:param() when it is passed into cts calls.
Changes:
- Added
cts:param(...)to the publicCtsExprAPI and its implementation. - Added validation in the shared expression-call path to reject
op:param()insidects:*calls with a targeted error. - Added a new unit test covering AST export for
cts:param()and the new rejection path, plus repository copilot instructions.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
marklogic-client-api/src/test/java/com/marklogic/client/impl/CtsParamExprTest.java |
Adds unit coverage for exported cts:param() AST and the new op:param() rejection. |
marklogic-client-api/src/main/java/com/marklogic/client/impl/PlanBuilderSubImpl.java |
No behavioral change; whitespace-only edit near existing op:param() implementation. |
marklogic-client-api/src/main/java/com/marklogic/client/impl/CtsExprImpl.java |
Implements new cts:param(...) overloads and adds a new helper class at the end of the file. |
marklogic-client-api/src/main/java/com/marklogic/client/impl/BaseTypeImpl.java |
Adds centralized validation to block op:param() from being nested inside cts calls. |
marklogic-client-api/src/main/java/com/marklogic/client/expression/CtsExpr.java |
Exposes cts:param(...) in the public Java API. |
.github/copilot-instructions.md |
Adds repository-specific Copilot/build/test guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // 2023-10-24 Exception: Manual changes have been made to this to expose the string constructors for cts.point and | ||
| // cts.polygon. These changes can be removed once optic-defs.json in the xdmp repository is updated to define these | ||
| // constructors. | ||
| // 2026-04-15 Exception: Manual changes have been made to expose cts:param prior to generator support. |
There was a problem hiding this comment.
I wouldn't bother with tracking this, the train left the station years ago in terms of making manual edits to generated files.
| * Provides a client interface to the <a href="http://docs.marklogic.com/cts:param" target="mlserverdoc">cts:param</a> server function. | ||
| * @param name The parameter name. (of <a href="{@docRoot}/doc-files/types/xs_string.html">xs:string</a>) | ||
| * @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_anyAtomicType.html">xs:anyAtomicType</a> server data type | ||
| */ |
There was a problem hiding this comment.
These additions are part of the public API so I recommend putting @since annotations on them. Specifying the required MarkLogic version is a nice-to-have but can be a maintenance burden (e.g. if the a feature is backfilled to MarkLogic 11). I'd rather the release notes / docs mention the required markLogic version and the "since" annotation then guides the user to the release notes.
The commit adds cts:param() support to the Optic Java API — a new way to pass parameter placeholders in the cts namespace — and adds a guard to reject misuse of op:param() inside cts expressions.