Introducing the Couchbase Java SDK 3.0 Alpha

In a collective effort across the SDK team, we have started to roll out completely new SDKs that are faster, have simpler APIs, are future proof for upcoming server features, and ease integration with framework ecosystems.

In addition to improving the Java SDK, we are also releasing a brand-new Scala SDK. It provides first-class support for everyone developing in Scala and makes integration into the Scala ecosystem much easier going forward.

Since all of this is pretty new, here be dragons. We appreciate all feedback and bug reports to make this the best SDK we have ever delivered.

You might also like:  An Overview of JDK Vendors

Highlights

This post groups the highlights in two sections. One discusses the reworked API (across all SDKs), the other covers Java SDK specific enhancements.

Cross-SDK API Improvements

In an effort to improve the usability of the APIs, we've trimmed and refactored them quite heavily. The result is a very cohesive and regular API structure which should make it much easier to use both for newcomers and long Couchbase users.

For a quick comparison, here are some APIs from the 2.x Java SDK:

<D extends Document<?>> D insert(D document, PersistTo persistTo, ReplicateTo replicateTo);
AsyncViewResult query(ViewQuery query);
AsyncN1qlQueryResult query(N1qlQuery query);

And then, of course, there are the timeout overloads:

<D extends Document<?>> D insert(D document, PersistTo persistTo, ReplicateTo replicateTo, long timeout, TimeUnit timeUnit);
ViewResult query(ViewQuery query, long timeout, TimeUnit timeUnit);
N1qlQueryResult query(N1qlQuery query, long timeout, TimeUnit timeUnit);

Compare this to the new API:

MutationResult insert(String id, Object content, InsertOptions options);
QueryResult query(String statement, QueryOptions ptions);
ViewResult viewQuery(String designDoc, String viewName, ViewOptions options);

Each method returns a Result and has an optional block at the end called Options. The old Document concept has been replaced with a simpler and more regular equivalent throughout the API. Optional properties like timeout, durability requirements or CAS have all been moved into the options parameter, leading to fewer overloads and only "one place to look."

Later blog posts will dive deeper into the API rework, but for now, let's move on to the Java-specific improvements.

Java Specific Improvements

The two most visible changes to the user are:

• Java 8 as a baseline java version
• Reactive APIs migrated from RxJava to Reactor

RxJava 1.x has served us well for many years (in fact, we've been one of the first adopters), but since it has been marked as end-of-life we had to look at alternatives. Together with the fact that reactive-streams emerged as the de-facto standard for integration between the different implementations, we had to decide between RxJava 2.x and reactor. While both were head-to-head on performance (mostly), after a long evaluation period, we decided on reactor for the following reasons:

• Native java 8 API
• Slightly better performance in some of our key workloads
• More community traction and growing constantly (also due to being integrated into spring core)

If your application platform is built in RxJava 2, fear not: since both support reactive-streams, you can just plug it in on top of our reactive APIs.

In the 2.x SDK, we had two APIs: a blocking API and an async API exposed through RxJava. In SDK 3, we've added a third API to give you even more control:

• The blocking API remains
• A reactive API exposes Mono and Flux responses from reactor
• The async API exposes CompletableFutures, which can be used as building blocks if the highest level of performance is needed.

Last but not least, one major enhancement for all reactive query APIs is the optional support for backpressure. If you need to read huge results and want to avoid putting them all onto the heap at once, you can now use the reactor backpressure mechanisms, which we are extending down to our internal async IO layer.

Getting Started

If you want to give it a try, you can pick it up from our own pre-release maven repository:

<repositories>
  <repository>
    <id>couchbase</id>
    <name>Couchbase Preview Repository</name>
    <url>http://files.couchbase.com/maven2</url>
  </repository>
</repositories>
 
<dependencies>
  <dependency>
    <groupId>com.couchbase.client</groupId>
    <artifactId>java-client</artifactId>
    <version>3.0.0-alpha.4</version>
  </dependency>
</dependencies>

Once the dependencies are resolved, you can connect to any cluster that is older than Couchbase Server 5.0. Then, open a bucket and use the collection of choice (collection support is already part of the API for an upcoming Couchbase Server release). For older releases, just select the defaultCollection and it will just work:

Cluster cluster = Cluster.connect("localhost", "username", "password");
Bucket bucket = cluster.bucket("bucket-name");
Collection collection = bucket.defaultCollection();

Now you can write and read a document:

// Upsert Document
MutationResult upsertResult = collection.upsert(
    "my-document",
    JsonObject.create().put("name", "mike")
);
 
// Get Document
Optional<GetResult> getResult = collection.get("my-document");

If you want to learn more, you can look into our new documentation, which is currently being written and fleshed out constantly. You can also look for code examples here.