### Compile and Run Cookbook Examples

Source: https://github.com/marklogic/java-client-api/wiki/Running-the-Examples

Compiles all Cookbook examples and then runs the DocumentWrite example. Ensure you are in the correct directory and have the necessary libraries on the classpath.

```bash
cd java-client-3.0.1/example
javac -cp "../lib/*" com/marklogic/client/example/cookbook/*.java
java -cp ".:../lib/*" com.marklogic.client.example.cookbook.DocumentWrite
```

--------------------------------

### Start MarkLogic Instance with Docker Compose

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Use Docker Compose to start a MarkLogic instance for testing. Ensure you are in the project root directory.

```bash
docker-compose up -d --build
```

--------------------------------

### fn:starts-with

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Checks if a string starts with a specified prefix, optionally using a specified collation.

```APIDOC
## fn:starts-with

### Description
Checks if a string starts with a specified prefix, optionally using a specified collation.

### Method
Not applicable (XQuery Function)

### Endpoint
Not applicable (XQuery Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **return value** (xs:string) - 'true' if the string starts with the prefix, 'false' otherwise.

#### Response Example
None
```

--------------------------------

### Run Reverse Proxy Server

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/README.md

Execute this Gradle task to start the reverse proxy server using Undertow. This is useful for testing the 'base path' parameter with the Java Client.

```bash
./gradlew runBlockingReverseProxyServer
```

--------------------------------

### Get Database Name

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Retrieves the name of the current database. Returns a string.

```XQuery
xdmp:database-name(xdmp:database());
```

--------------------------------

### Run Tests with Reverse Proxy

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/README.md

Start the reverse proxy server, run specified tests, and then stop the server. This is useful for end-to-end testing scenarios.

```bash
./gradlew -PtestUseReverseProxyServer=true runReverseProxyServer marklogic-client-api:test --tests ReadDocumentPageTest
```

--------------------------------

### Run Reverse Proxy with HTTPS on Port 443

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/README.md

Start the reverse proxy server listening for HTTPS requests on port 443. 'sudo' is required as it listens on a privileged port. This emulates Progress Data Cloud behavior.

```bash
sudo ./gradlew runBlock -PrpsHttpsPort=443
```

--------------------------------

### Run Reverse Proxy with Custom Mappings

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/README.md

Configure custom path mappings for the reverse proxy server. This example associates the path '/my/custom/server' with a MarkLogic app server on port 8123.

```bash
./gradlew runBlock -PrpsCustomMappings=/my/custom/server,8123
```

--------------------------------

### Get Function Name

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Retrieves the QName of a given function. Returns a QNAME.

```XQuery
xdmp:function-name(xdmp:function(xs:QName("fn:empty")));
```

--------------------------------

### sql:strpos

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_integer.html

Finds the starting position of a substring within a string, optionally using a collation.

```APIDOC
## sql:strpos

### Description
Finds the starting position of a substring within a string, optionally using a collation.

### Method
XQuery Function

### Parameters
#### Path Parameters
- _target_ (xs:string?) - The string to search within.
- _test_ (xs:string?) - The substring to search for.
- _collation_ (xs:string?) - The collation to use for the search.

### Response
#### Success Response
- Returns an xs:integer representing the starting position of the substring, or 0 if not found.
```

--------------------------------

### Concise Read Operation with Fluent Interface

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Demonstrates a single-line read operation using the fluent interface pattern. This method retrieves a document and gets its content as a DOM Document.

```Java
org.w3c.dom.Document document = 
    client.newXMLDocumentManager().read(
        client.newDocId("/db/path/to/myDoc.xml"),
        new DOMHandle()
        ).get();
```

--------------------------------

### Search Documents and Get Results as SearchHandle

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Executes a search using specified query options and criteria, retrieving the results as a SearchHandle. This provides a convenient Java data structure for manipulating search results.

```Java
QueryManager queryMgr = client.newQueryManager();

StringQueryDefinition querydef = queryMgr.newStringDefinition("shipments");
querydef.setCriteria("electronics port:Lisbon");

SearchHandle results = new SearchHandle();

queryMgr.search(querydef, results);
```

--------------------------------

### Writing and Reading POJOs using Shortcut Methods

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Demonstrates writing a POJO to a document and then reading it back using shortcut methods after registering the appropriate handle factory. Assumes JAXBHandle is registered.

```Java
// ... _create a database client_ ...

XMLDocumentManager docMgr = client.newXMLDocumentManager();
String docId = "/db/path/to/myPOJO.xml";

Product product = ... _create or modify the POJO_ ...;

docMgr.writeAs(docId, product);

// ... _at some other time_ ...

Product product = docMgr.readAs(docId, Product.class);
```

--------------------------------

### map:get

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Retrieves the value associated with a key from a map.

```APIDOC
## map:get

### Description
Retrieves the value associated with a key from a map.

### Method
Not applicable (XQuery function)

### Endpoint
Not applicable (XQuery function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **return value** (xs:anyAtomicType) - The value associated with the key, if found.

#### Response Example
None
```

--------------------------------

### Deploy Test Application

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/README.md

Run this command from the root directory of the repository to deploy the test application to MarkLogic.

```bash
./gradlew -i mlDeploy
```

--------------------------------

### Write Query Options as XML String (Shortcut)

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Writes new query options to the server using the shortcut method, specifying the format as XML. This is a more concise way to write query options.

```Java
QueryOptionsManager optionsMgr = client.newQueryOptionsManager();

String options = new StringBuilder()
            .append("<search:options>")
            .append(    "<search:constraint name=\"port\">")
            .append(        "<search:value>")
            .append(            "<search:element name=\"port\" ns=\""/>")
            .append(        "</search:value>")
            .append("</search:constraint>")
            .append("</search:options>")
            .toString();

optionsMgr.writeOptionsAs("shipments", Format.XML, options);
```

--------------------------------

### geo:destination

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/cts_point.html

Calculates a destination point given a starting point, bearing, and distance.

```APIDOC
## geo:destination

### Description
Calculates a destination point given a starting point, bearing, and distance.

### Method
N/A (Server-side function)

### Endpoint
N/A (Server-side function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (cts:point) - The calculated destination point.

#### Response Example
N/A
```

--------------------------------

### Get Day from Date

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Extracts the day component from a date value. Returns an INTEGER.

```XQuery
fn:day-from-date(xs:date("1999-05-31-05:00"));
```

--------------------------------

### Get Timezone from Date

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Extracts the timezone component from a date value. Returns a DURATION.

```XQuery
fn:timezone-from-date(xs:date("2000-06-12Z"));
```

--------------------------------

### Run All Tests for Java Client API

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Execute all tests for the `marklogic-client-api` module using Gradle. This command uses the connection properties defined in `gradle-local.properties`.

```bash
./gradlew marklogic-client-api:test
```

--------------------------------

### Get Seconds from Time

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Extracts the seconds component from a time value. Returns a DECIMAL.

```XQuery
fn:seconds-from-time(xs:time("13:20:10.5"));
```

--------------------------------

### Run Tests for ml-development-tools Plugin

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Execute tests specifically for the `ml-development-tools` Gradle plugin.

```bash
./gradlew ml-development-tools:test
```

--------------------------------

### Get NCName from QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Extracts the NCName (local name without namespace) from a QName. Returns an NCName.

```XQuery
let $qn := fn:QName("http://www.w3.org/XML/1998/namespace", "lang")
return
fn:prefix-from-QName(fn:node-name( attribute {$qn} {"en"}));
```

--------------------------------

### Insert Documents with Different Formats

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Demonstrates inserting documents of various types: XML, JSON, text, and binary.

```XQuery
xdmp:document-insert("test1.xml",<foo attr="attribute"><?processing instruction?><!--comment-->test1</foo>);
```

```XQuery
xdmp:document-insert("test2.json",object-node {"test":"hello"});
```

```XQuery
xdmp:document-insert("/test3.txt",text { "test1" });
```

```XQuery
xdmp:document-insert("test4.bin",binary {"ABCD"});
```

--------------------------------

### Get Type of Value

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Determines the XQuery type of a given value. Returns a QNAME representing the type.

```XQuery
xdmp:type(10);
```

--------------------------------

### Undeploy Test Application

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Undeploy the test application from the MarkLogic instance using Gradle. The `-Pconfirm=true` flag bypasses confirmation prompts.

```bash
./gradlew mlUndeploy -i -Pconfirm=true
```

--------------------------------

### Get Base URI of an Element

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Retrieves the base URI of an element within a document. Returns an anyURI.

```XQuery
fn:base-uri(fn:doc()/*[@attr eq "attribute"]);
```

--------------------------------

### Deploy Test Application

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Deploy the test application to the MarkLogic instance using Gradle. This makes resources available for tests.

```bash
./gradlew mlDeploy -i
```

--------------------------------

### String Functions

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

This section covers functions for manipulating xs:string values, such as getting their length, converting them, or extracting substrings.

```APIDOC
## fn:string-length

### Description
Returns the length of an xs:string.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:integer) - The length of the string.

#### Response Example
N/A

## fn:string-to-codepoints

### Description
Converts an xs:string to a sequence of its Unicode codepoints.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:integer) - A sequence of Unicode codepoints.

#### Response Example
N/A

## fn:substring

### Description
Extracts a substring from a source string based on a starting location and length.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string?) - The extracted substring.

#### Response Example
N/A

## fn:substring-after

### Description
Returns the portion of a string that occurs after a specified substring.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string?) - The substring after the specified marker.

#### Response Example
N/A

## fn:substring-before

### Description
Returns the portion of a string that occurs before a specified substring.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string*) - The substring before the specified marker.

#### Response Example
N/A

## fn:tokenize

### Description
Splits a string into a sequence of substrings based on a pattern.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string?) - A sequence of substrings.

#### Response Example
N/A

## fn:translate

### Description
Translates characters in a string according to a mapping.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string?) - The translated string.

#### Response Example
N/A

## fn:upper-case

### Description
Converts a string to its uppercase equivalent.

### Method
N/A (XQuery function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (xs:string?) - The uppercase version of the string.

#### Response Example
N/A
```

--------------------------------

### cts:period

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/cts_period.html

Creates a server expression that returns a value of the cts:period server type. This function takes a start and end dateTime.

```APIDOC
## cts:period

### Description
Creates a server expression that returns a value of the cts:period server type. This function takes a start and end dateTime.

### Server Function
cts:period(xs:dateTime _start_, xs:dateTime _end_)

### Java Doc
[java](../../com/marklogic/client/expression/CtsExpr.html#ml-server-type-period)
```

--------------------------------

### Write Query Options as XML String

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Writes new query options to the server using a StringHandle. This method is useful for defining search constraints and configuring index usage.

```Java
QueryOptionsManager optionsMgr = client.newQueryOptionsManager();

String options = new StringBuilder()
            .append("<search:options>")
            .append(    "<search:constraint name=\"port\">")
            .append(        "<search:value>")
            .append(            "<search:element name=\"port\" ns=\""/>")
            .append(        "</search:value>")
            .append("</search:constraint>")
            .append("</search:options>")
            .toString();

StringHandle handle = new StringHandle(options);

optionsMgr.writeOptions("shipments", handle);
```

--------------------------------

### Concise Write Operation with Fluent Interface

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Shows how to perform a write operation in a single line using the fluent interface. It utilizes a DOMHandle with the document content.

```Java
Document document = ... _create or modify the document_ ...;

client.newXMLDocumentManager().write(
    client.newDocId("/db/path/to/myDoc.xml"),
    new DOMHandle().with(document)
    );
```

--------------------------------

### sql:bucket

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_unsignedLong.html

Creates a bucket for SQL queries. The return type is xs:unsignedLong.

```APIDOC
## sql:bucket

### Description
Creates a bucket for SQL queries.

### Method
N/A (Server-side function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return** (xs:unsignedLong) - The created bucket.

#### Response Example
N/A
```

--------------------------------

### Configure Classpath for m2e

Source: https://github.com/marklogic/java-client-api/wiki/Eclipse

Replace M2_REPO entries with the MAVEN2_CLASSPATH_CONTAINER in the .classpath file for m2e dynamic classpath management.

```xml
<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER"/>
```

--------------------------------

### Search Documents and Get Results as DOM

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Executes a search using specified query options and criteria, retrieving the results as a DOM document. This is useful for XML-based result processing.

```Java
QueryManager queryMgr = client.newQueryManager();

StringQueryDefinition querydef = queryMgr.newStringDefinition("shipments");
querydef.setCriteria("electronics port:Lisbon");

DOMHandle handle = new DOMHandle();

queryMgr.search(querydef, handle);

Document results = handle.get();
```

--------------------------------

### sql:like

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_boolean.html

Performs a SQL LIKE pattern match. Returns xs:boolean.

```APIDOC
## sql:like

### Description
Performs a SQL LIKE pattern match.

### Method
sql:like

### Parameters
* **input** (xs:string?) - The input string to match against the pattern. Can be null.
* **pattern** (xs:string) - The SQL LIKE pattern to use for matching.
* **escape** (xs:string) - The escape character for the pattern.

### Return Value
* **xs:boolean** - Returns true if the input matches the pattern, false otherwise.
```

--------------------------------

### fn:QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Constructs an xs:QName value from a namespace URI and a local name.

```APIDOC
## fn:QName

### Description
Constructs an xs:QName value from a namespace URI and a local name.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### sql:bucket

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Creates buckets for data. This function is part of the SQL functions.

```APIDOC
## sql:bucket

### Description
Creates buckets based on provided edge values and a search parameter, with an optional collation.

### Method
Not applicable (function call in expression)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **bucketEdgesParam** (xs:anyAtomicType*): The values defining the bucket edges.
* **srchParam** (xs:anyAtomicType): The value to place into a bucket.
* **collationLiteral** (xs:string): The collation to use for comparisons.

### Request Example
```
sql:bucket(10, 20, 30, 25, "http://marklogic.com/collation/")
```

### Response
#### Success Response (200)
Returns the bucket identifier for the srchParam.

#### Response Example
```json
2
```
```

--------------------------------

### Exporting Rows from a View to CSV using RowBatcher

Source: https://github.com/marklogic/java-client-api/wiki/Row-Batcher

This snippet shows how to initialize a DatabaseClient and DataMovementManager, configure a StringHandle for CSV output, and set up a multi-threaded RowBatcher. It details how to configure row managers, build an export plan from a view, and define success and failure handlers for batch processing.

```java
DatabaseClient db =  DatabaseClientFactory.newClient(...);

DataMovementManager moveMgr = db.newDataMovementManager();

StringHandle sampleHandle =
    new StringHandle().withFormat(Format.TEXT)
                      .withMimetype("text/csv");

RowBatcher<String> rowBatcher =
    moveMgr.newRowBatcher(sampleHandle)
           .withBatchSize(30)
           .withThreadCount(threads);

RowManager rowMgr = rowBatcher.getRowManager();
rowMgr.setDatatypeStyle(RowManager.RowSetPart.HEADER);

PlanBuilder planBuilder = rowMgr.newPlanBuilder();
PlanBuilder.ModifyPlan exportPlan =
    planBuilder.fromView(...) 
               .select(/* project index columns and add expression columns */);

rowBatcher.withBatchView(exportPlan)
          .onSuccess(event -> {
              try {
                  BufferedReader reader =
                      new BufferedReader(new StringReader(event.getRowsDoc()));
                      reader.readLine();  // consume the CSV header line
                      reader.lines().forEach(line -> {/*
                          client processing of exported rows
                          */});
              } catch (Throwable e) {
                  // logging for errors during client processing of exported rows
              }})
          .onFailure((event, throwable) -> {
                event.withDisposition(BatchFailureDisposition.SKIP);
                // logging for errors during retrieval of row batches
                });

moveMgr.startJob(rowBatcher);
rowBatcher.awaitCompletion();
```

--------------------------------

### xdmp:QName-from-key

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Constructs an xs:QName value from a key.

```APIDOC
## xdmp:QName-from-key

### Description
Constructs an xs:QName value from a key.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### map:entry

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Creates a map entry with a given key and value.

```APIDOC
## map:entry

### Description
Creates a map entry with a given key and value.

### Method
Not applicable (XQuery function)

### Endpoint
Not applicable (XQuery function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **return value** (item) - The created map entry.

#### Response Example
None
```

--------------------------------

### Concise Search Operation with Fluent Interface

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Illustrates a single-line search operation using the fluent interface. It defines a string query with criteria and a location, returning results as a DOM Document.

```Java
Document results = client.newQueryManager().search(
    queryMgr.newStringDefinition("shipments").withCriteria("electronics port:Lisbon"),
    new DOMHandle()
    ).get();
```

--------------------------------

### Write DOM Document Content using Shortcut Method

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Writes a DOM document to the database as an XML document using a shortcut method. This is a more concise way to write content compared to using explicit handles.

```Java
Document document = ... _create or modify the document_ ...;

XMLDocumentManager docMgr = client.newXMLDocumentManager();
String docId = "/db/path/to/myDoc.xml";

docMgr.writeAs(docId, document);
```

--------------------------------

### xdmp:describe

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/item.html

Returns a string describing an item, with options to limit sequence and item length.

```APIDOC
## xdmp:describe

### Description
Returns a string describing an item, with options to limit sequence and item length.

### Method
N/A (Function Signature)

### Parameters
#### Path Parameters
- **_item_** (item) - Required - The item to describe.
- **_max-sequence-length_?** (xs:unsignedInt) - Optional - Maximum length of sequences to describe.
- **_max-item-length_?** (xs:unsignedInt) - Optional - Maximum length of items to describe.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **return value** (xs:string) - A string representation of the item.

#### Response Example
None
```

--------------------------------

### Include JAXB API and Runtime for Older Java Client Versions (Gradle)

Source: https://github.com/marklogic/java-client-api/blob/master/README.md

For Java Client 6.x or older with Java 11+, add these Gradle implementations to use JAXB.

```gradle
implementation "javax.xml.bind:jaxb-api:2.3.1"
        implementation "org.glassfish.jaxb:jaxb-runtime:2.3.2"
        implementation "org.glassfish.jaxb:jaxb-core:2.3.0.1"
```

--------------------------------

### xdmp:key-from-QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Generates a key from an xs:QName value.

```APIDOC
## xdmp:key-from-QName

### Description
Generates a key from an xs:QName value.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Import Self-Signed Certificate to JVM Truststore

Source: https://github.com/marklogic/java-client-api/blob/master/test-app/src/main/resources/README.md

Use this command to import the self-signed certificate into your JVM's truststore. Ensure you replace 'changeit' with the correct password for your truststore file (jssecacerts or cacerts).

```bash
keytool -importcert -file selfsigned-cert.pem -alias selfsigned -storepass changeit
```

--------------------------------

### fn:namespace-uri-from-QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Extracts the namespace URI from an xs:QName value.

```APIDOC
## fn:namespace-uri-from-QName

### Description
Extracts the namespace URI from an xs:QName value.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Retrieve All Documents

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Retrieves all documents in the current database. Useful for initial data exploration.

```XQuery
fn:doc();
```

--------------------------------

### xdmp:path

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Returns the path to a node.

```APIDOC
## xdmp:path

### Description
Returns the path to a node.

### Method
xdmp:path

### Parameters
#### Path Parameters
- **_node_** (node) - The node for which to get the path.
- **_include-document_** (xs:boolean?) - Whether to include the document URI in the path. Optional.

### Response
#### Success Response (200)
- **return value** (xs:string) - The path to the node.

### Request Example
```
xdmp:path(/some/node, true())
```

### Response Example
```
"/documents/mydoc.xml/some/node"
```
```

--------------------------------

### Create Base64Binary Value

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Creates a base64Binary value from a string. Returns BASE64BINARY.

```XQuery
xs:base64Binary("DEADBEEF");
```

--------------------------------

### Add MarkLogic Java Client API to Gradle Project

Source: https://github.com/marklogic/java-client-api/blob/master/README.md

Add this implementation to your build.gradle file to include the MarkLogic Java Client API in your Gradle project.

```gradle
implementation "com.marklogic:marklogic-client-api:8.0.0"
```

--------------------------------

### fn:prefix-from-QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Extracts the prefix from an xs:QName value.

```APIDOC
## fn:prefix-from-QName

### Description
Extracts the prefix from an xs:QName value.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### cts:point as Parameter

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/cts_point.html

Demonstrates how cts:point is used as a parameter in other server functions.

```APIDOC
## cts:circle(xs:double radius, cts:point center)

### Description
Defines a circular region.

### Method
Server Expression

### Parameters
#### Path Parameters
- **radius** (xs:double) - The radius of the circle.
- **center** (cts:point) - The center point of the circle.

### Response
#### Success Response (cts:circle)
- A cts:circle server expression representing the specified circular region.
```

```APIDOC
## cts:polygon(cts:point vertices*)

### Description
Defines a polygonal region.

### Method
Server Expression

### Parameters
#### Path Parameters
- **vertices** (cts:point*) - An array of points defining the vertices of the polygon.

### Response
#### Success Response (cts:polygon)
- A cts:polygon server expression representing the specified polygonal region.
```

```APIDOC
## cts:point-latitude(cts:point point)

### Description
Extracts the latitude from a cts:point.

### Method
Server Expression

### Parameters
#### Path Parameters
- **point** (cts:point) - The point from which to extract the latitude.

### Response
#### Success Response (xs:numeric)
- The latitude of the point as an xs:numeric value.
```

```APIDOC
## cts:point-longitude(cts:point point)

### Description
Extracts the longitude from a cts:point.

### Method
Server Expression

### Parameters
#### Path Parameters
- **point** (cts:point) - The point from which to extract the longitude.

### Response
#### Success Response (xs:numeric)
- The longitude of the point as an xs:numeric value.
```

```APIDOC
## geo:arc-intersection(cts:point p1, cts:point p2, cts:point q1, cts:point q2, xs:string options*)

### Description
Calculates the intersection points of two arcs.

### Method
Server Expression

### Parameters
#### Path Parameters
- **p1** (cts:point) - The start point of the first arc.
- **p2** (cts:point) - The end point of the first arc.
- **q1** (cts:point) - The start point of the second arc.
- **q2** (cts:point) - The end point of the second arc.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (cts:point*)
- An array of cts:point values representing the intersection points.
```

```APIDOC
## geo:bearing(cts:point p1, cts:point p2, xs:string options*)

### Description
Calculates the bearing between two points.

### Method
Server Expression

### Parameters
#### Path Parameters
- **p1** (cts:point) - The starting point.
- **p2** (cts:point) - The ending point.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (xs:double)
- The bearing between the two points as an xs:double value.
```

```APIDOC
## geo:destination(cts:point p, xs:double bearing, xs:double distance, xs:string options*)

### Description
Calculates the destination point given a starting point, bearing, and distance.

### Method
Server Expression

### Parameters
#### Path Parameters
- **p** (cts:point) - The starting point.
- **bearing** (xs:double) - The bearing in degrees.
- **distance** (xs:double) - The distance to travel.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (cts:point)
- The destination point as a cts:point value.
```

```APIDOC
## geo:distance(cts:point p1, cts:point p2, xs:string options*)

### Description
Calculates the distance between two points.

### Method
Server Expression

### Parameters
#### Path Parameters
- **p1** (cts:point) - The first point.
- **p2** (cts:point) - The second point.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (xs:double)
- The distance between the two points as an xs:double value.
```

```APIDOC
## geo:ellipse-polygon(cts:point center*, xs:double semi-major-axis, xs:double semi-minor-axis, xs:double azimuth, xs:double arc-tolerance, xs:string options*)

### Description
Defines an elliptical region.

### Method
Server Expression

### Parameters
#### Path Parameters
- **center** (cts:point*) - The center point(s) of the ellipse.
- **semi-major-axis** (xs:double) - The length of the semi-major axis.
- **semi-minor-axis** (xs:double) - The length of the semi-minor axis.
- **azimuth** (xs:double) - The azimuth of the ellipse.
- **arc-tolerance** (xs:double) - The arc tolerance for the ellipse.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (cts:polygon)
- A cts:polygon server expression representing the elliptical region.
```

```APIDOC
## geo:shortest-distance(cts:point p1, cts:region region*, xs:string options*)

### Description
Calculates the shortest distance from a point to a region.

### Method
Server Expression

### Parameters
#### Path Parameters
- **p1** (cts:point) - The point from which to calculate the distance.
- **region** (cts:region*) - The region to measure the distance to.
- **options** (xs:string*) - Optional parameters for the calculation.

### Response
#### Success Response (xs:double)
- The shortest distance as an xs:double value.
```

--------------------------------

### fn:namespace-uri-for-prefix

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Returns the namespace URI associated with a given prefix for a specific element node.

```APIDOC
## fn:namespace-uri-for-prefix

### Description
Returns the namespace URI associated with a given prefix for a specific element node.

### Method
Not applicable (XQuery Function)

### Endpoint
Not applicable (XQuery Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **return value** (xs:string?) - The namespace URI for the prefix.

#### Response Example
None
```

--------------------------------

### sql:bucket

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_anyAtomicType.html

Creates buckets for SQL queries based on xs:anyAtomicType values, optionally using a specified collation. This function is available in the MarkLogic server and can be invoked via the Java client API.

```APIDOC
## sql:bucket

### Description
Creates buckets for SQL queries based on xs:anyAtomicType values, optionally using a specified collation.

### Server Function
[server](http://docs.marklogic.com/sql:bucket)

### Java API
[java](../../com/marklogic/client/expression/SqlExpr.html#ml-server-type-bucket)

### Parameters
* _bucketEdgesParam_ (xs:anyAtomicType*) - The edges of the buckets.
* _srchParam_ (xs:anyAtomicType) - The value to bucket.
* _collationLiteral_ (xs:string?) - The collation to use for comparison.
```

--------------------------------

### Override Default Connection Properties

Source: https://github.com/marklogic/java-client-api/blob/master/CONTRIBUTING.md

Create a `gradle-local.properties` file to override default MarkLogic connection properties like host and password.

```properties
mlHost=changeme
mlPassword=changeme
```

--------------------------------

### sem:QName-to-iri

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Converts an xs:QName value to an IRI (Internationalized Resource Identifier).

```APIDOC
## sem:QName-to-iri

### Description
Converts an xs:QName value to an IRI (Internationalized Resource Identifier).

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### fn:string

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Converts an item to its string representation.

```APIDOC
## fn:string

### Description
Converts an item to its string representation.

### Method
Not applicable (XQuery function)

### Endpoint
Not applicable (XQuery function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **return value** (xs:string) - The string representation of the item.

#### Response Example
None
```

--------------------------------

### sem:store

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Creates or retrieves a semantic store. This function is part of the semantic functions.

```APIDOC
## sem:store

### Description
Creates or retrieves a semantic store, optionally with a query.

### Method
Not applicable (function call in expression)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **options** (xs:string): Optional configuration for the store.
* **query** (cts:query?): An optional query to filter the store contents.

### Request Example
```
sem:store("reindex=exact")
sem:store(fn:true(), "my-query")
```

### Response
#### Success Response (200)
Returns a sem:store object.

#### Response Example
```json
// Returns the sem:store object
```
```

--------------------------------

### Signature for Input-Output Endpoint

Source: https://github.com/marklogic/java-client-api/wiki/Bulk-Data-Services

Defines the signature for an endpoint that both accepts input and produces output. Includes optional session, endpointState, and endpointConstants parameters, a required input parameter, and specifies the return document type.

```json
{
  "endpoint": "INPUT_OUTPUT_CALLER_PATH", 
  "params": [
    {"name":"session",           "datatype":"session",       "multiple":false, "nullable":true},
    {"name":"endpointState",     "datatype":"DOCUMENT_TYPE", "multiple":false, "nullable":true},
    {"name":"endpointConstants", "datatype":"DOCUMENT_TYPE", "multiple":false, "nullable":true},
    {"name":"input",             "datatype":"DOCUMENT_TYPE", "multiple":true,  "nullable":true}
    ],
  "return": {"datatype":"DOCUMENT_TYPE", "multiple":true, "nullable":true}
  }
```

--------------------------------

### fn:string-join

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Concatenates the strings in a sequence, separated by a specified separator string.

```APIDOC
## fn:string-join

### Description
Concatenates the strings in a sequence, separated by a specified separator string.

### Method
Not applicable (XQuery Function)

### Endpoint
Not applicable (XQuery Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **return value** (xs:integer?) - The concatenated string.

#### Response Example
None
```

--------------------------------

### Registering JAXB Handle Factory for POJO Support

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/overview.html

Registers a factory for the JAXBHandle to enable shortcut methods for reading and writing POJO classes as database documents. This configuration should be done once before creating a client.

```Java
// configure once before creating a client
DatabaseClientFactory.getHandleRegistry().register(
	JAXBHandle.newFactory(Product.class, ... _other POJO classes_ ...)
	);
```

--------------------------------

### Construct InputCaller Instance

Source: https://github.com/marklogic/java-client-api/wiki/Data-Services-for-IO

Constructs an InputCaller instance for an endpoint that accepts JSON document input as Java String instances without returning any output. Requires a DatabaseClient, the API declaration, and a StringHandle for input.

```Java
InputCaller<String> caller = InputCaller.on(
    dbClient, apiDeclaration, new StringHandle()
    );
```

--------------------------------

### Return Empty Sequence

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Returns an empty sequence, often used as a placeholder or to signify no result. Returns NULL.

```XQuery
();
```

--------------------------------

### Create GDay Value

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api-functionaltests/src/test/java/com/marklogic/client/functionaltest/data/xqueries.txt

Creates a GDay value representing a day of the month. Returns GDAY.

```XQuery
xs:gDay("---01");
```

--------------------------------

### Include JAXB API and Runtime for Older Java Client Versions (Maven)

Source: https://github.com/marklogic/java-client-api/blob/master/README.md

For Java Client 6.x or older with Java 11+, include these Maven dependencies to use JAXB.

```xml
<dependency>
        <groupId>javax.xml.bind</groupId>
        <artifactId>jaxb-api</artifactId>
        <version>2.3.1</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>2.3.2</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-core</artifactId>
        <version>2.3.0.1</version>
    </dependency>
```

--------------------------------

### sem:iri-to-QName

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_QName.html

Converts an IRI (Internationalized Resource Identifier) to an xs:QName value.

```APIDOC
## sem:iri-to-QName

### Description
Converts an IRI (Internationalized Resource Identifier) to an xs:QName value.

### Method
Not applicable (Server-side function)

### Endpoint
Not applicable (Server-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### sql:trim

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Removes leading and trailing spaces from a string.

```APIDOC
## sql:trim

### Description
Removes leading and trailing spaces from a string.

### Method
Not applicable (XQuery function)

### Endpoint
Not applicable (XQuery function)

### Parameters
#### Path Parameters
Not applicable

#### Query Parameters
Not applicable

#### Request Body
Not applicable

### Parameters
- **_str_** (xs:string) - The input string.

### Return Value
- **xs:string** - The string with leading and trailing spaces removed.
```

--------------------------------

### fn:string-length

Source: https://github.com/marklogic/java-client-api/blob/master/marklogic-client-api/src/main/javadoc/doc-files/types/xs_string.html

Returns the length of a string.

```APIDOC
## fn:string-length

### Description
Returns the length of a string.

### Method
Not applicable (XQuery Function)

### Endpoint
Not applicable (XQuery Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **return value** (xs:string?) - The length of the input string.

#### Response Example
None
```