The MarkLogic Java Client API

The API makes it easy to write, read, delete, and find documents in a MarkLogic database.

For example:

// write a text, binary, XML, or JSON document from any source with ACID guarantees
documentManager.write(uri, new FileHandle()
  .with(new File("file1234.json"))
  .withFormat(JSON));

// read and directly parse to your preferred type, even your own POJOs!
JsonNode jsonDocContents = documentManager.readAs(uri, JsonNode.class);

// get matches super-fast using full-featured search
JsonNode results = queryManager.search(
  new StructuredQueryBuilder().term("quick", "brown", "fox"),
  new JacksonHandle()).get();

The Java API supports the following core features of the MarkLogic database:

• Write and read binary, JSON, text, and XML documents.
• Query data structure trees, marked-up text, and all the hybrids in between those extremes.
• Project values, tuples, and triples from hierarchical documents and aggregate over them.
• Patch documents with partial updates.
• Use Optimistic Locking to detect contention without creating locks on the server.
• Execute ACID modifications so the change either succeeds or throws an exception.
• Execute multi-statement transactions so changes to multiple documents succeed or fail together.
• Call Data Services by means of a Java interface on the client for data functionality implemented by an endpoint on the server.

What's New in Java Client API 5

As of 5.3, the Java API was compiled with Java 8 and tested on Java 8 through 11.

Features:

• Splitters for CSV records, for entries in a ZipInputStream, for line-delimited JSON or XML records, and for large JSON or XML files for streaming to WriteBatcher.
• Support for RowBatcher to make it easy to export rows and documents for a view as modified by a plan - see https://github.com/marklogic/java-client-api/wiki/Row-Batcher for more detail.
• Support for Concurrent Bulk IO Data Services to make it easy to implement connectors for dataflow frameworks - see https://github.com/marklogic/java-client-api/wiki/Bulk-Data-Services for more detail.
• Upgrade of dependencies including OkHttp 4.7.2

What's New in Java Client API 4

• Optic API - blends relational with NoSQL by providing joins and aggregates over documents
  • is powered by the new row index and query optimizer
  • uses row, triple, and/or lexicon lenses
  • matches the functionality of the Optic API for XQuery and Javascript, but idiomatic for Java developers
• Data Movement SDK - move large amounts of data into, out of, or within a MarkLogic cluster
  • WriteBatcher distributes writes across many threads and across the entire MarkLogic cluster
  • QueryBatcher enables bulk processing or export of matches to a query by distributing the query across many threads and batch processing to listeners
  • Comes with ApplyTransformListener, DeleteListener, ExportListener, ExportToWriterListener, and UrisToWriterListener
  • With custom listeners you can easily and efficiently apply your business logic to batches of query matches
• Kerberos and Client Certificate Authentication
• Geospatial double precision and queries on region indexes
• Temporal document enhancements
  • protect and wipe
  • more control over version uris
• Support for document metadata values

See also CHANGELOG.md

QuickStart

To use the API in your maven project, include the following in your pom.xml:

<dependency>
    <groupId>com.marklogic</groupId>
    <artifactId>marklogic-client-api</artifactId>
    <version>5.2.0</version>
</dependency>

And add this repository to your pom.xml repositories section:

<repository>
    <id>jcenter</id>
    <url>https://jcenter.bintray.com</url>
</repository>

For gradle projects, include the following:

dependencies {
    compile group: 'com.marklogic', name: 'marklogic-client-api', version: '5.3.0'
}

Use gradle 4.x+ and add this to your build.gradle repositories section:

jcenter()

Read The Java API in Five Minutes

Learning More

The following resources document the Java API:

• Java Application Developer's Guide
• JavaDoc

Installing

To use the Java API, either add Maven or Gradle dependency as explained above or download the jar and its dependencies:

http://developer.marklogic.com/products/java

Of course, you'll also need to install the database -- which you can do for free with the developer license:

https://developer.marklogic.com/free-developer

To obtain verified downloads signed with MarkLogic's PGP key, use maven tools or directly download the .jar and .asc files from maven central. MarkLogic's pgp key ID is 48D4B86E and it is available from pgp.mit.edu by installing gnupg and running the command:

$ gpg --keyserver pgp.mit.edu --recv-key 48D4B86E

Files can be verified with the command:

$ gpg marklogic-client-api-5.3.0.jar.asc

Building and Contributing

You can build the API in the same way as any Gradle project on git:

1. Clone the java-client-api repository on your machine.
2. Choose the appropriate branch (usually develop)
3. Execute a Gradle build in the directory containing the main project's build.gradle file.

You might want to skip the tests until you have configured a test database and REST server:

$ ./gradlew build -x test

See CONTRIBUTING.md for more on contributing to this github project.

Running JUnit Tests

$ ./gradlew java-client-api:compileTestJava
$ ./gradlew testServerInit
$ ./gradlew java-client-api:test

Support

The MarkLogic Java Client API is maintained by MarkLogic Engineering and is made available under the Apache 2.0 license. It is designed for use in production applications with MarkLogic Server. Everyone is encouraged to file bug reports, feature requests, and pull requests through GitHub. This input is critical and will be carefully considered. However, we can’t promise a specific resolution or timeframe for any request. In addition, MarkLogic provides technical support for release tags of the Java Client API to licensed customers under the terms outlined in the MarkLogic Technical Support Handbook. Customers with an active maintenance contract can sign up for MarkLogic Technical Support on our support portal.