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.
• Match documents against alerting rules expressed as queries.
• 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.

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>4.1.1</version>
</dependency>

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

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

For gradle projects, include the following:

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

Use gradle 1.7+ 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-4.1.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.