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:

What's New in Java Client API 5

What's New in Java Client API 4

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>http://jcenter.bintray.com</url>
</repository>

For gradle projects, include the following:

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

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:

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.2.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.