MLE-32111 Add annotation support to StructuredQueryBuilder (#1648)

[rjdew-progress]

Adds StructuredQueryBuilder.annotation(String...) so callers can attach one or more elements to a structured query. The server turns these into cts:annotation elements; they are ignored during evaluation and are useful for documenting or marking parts of a query.

Annotation content may be arbitrary XML (including namespaced elements) or plain text. Content is parsed and copied into the query via DOMWriter, with a plain-text fallback for non-XML content. Annotations are serialized after the query elements to satisfy the search schema's ordering requirement.

[Copilot]

Pull request overview

Adds first-class support for emitting <annotation> elements in structured queries via StructuredQueryBuilder.annotation(String...), enabling callers to embed arbitrary XML fragments (including namespaced elements) or plain text as query annotations. This fits into marklogic-client-api as an extension to the Structured Query Builder’s XML serialization capabilities, along with accompanying schema-validating tests.

Changes:

• Added StructuredQueryBuilder.annotation(String...) and an AnnotationQuery implementation that parses XML fragments (with plain-text fallback) and serializes annotations as <annotation> elements.
• Updated structured query XML serialization to always emit annotation elements after all query elements to satisfy search.xsd ordering.
• Added unit tests validating namespaced XML annotations, plain-text annotations, multiple annotations, and enforced ordering.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
marklogic-client-api/src/main/java/com/marklogic/client/query/StructuredQueryBuilder.java	Adds annotation query type, XML-fragment parsing + DOM serialization, and enforces annotation ordering at the top-level query serialization stage.
marklogic-client-api/src/test/java/com/marklogic/client/test/StructuredQueryBuilderTest.java	Adds schema-validating tests for annotation serialization (XML + text), multiplicity, and ordering guarantees.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.