Couchbase Java SDK 2.0.0 Beta 2

Originally written by Michael Nitschinger

Shortly after the first beta release, I'm very happy to announce the second beta release of the Java/JVM SDK release train nicknamed Armstrong. It contains both the core package "core-io" 1.0.0-beta2 as well as the Java SDK 2.0.0-beta2.

This is intended to be the last beta release before the final GA, which is scheduled follow shortly afterwards. It contains two major additions and a couple of bugfixes and enhancements. If you are new to the 2.0 SDK in general, please refer to the older blog post announcements (Beta 1, DP 3, DP 2 and DP1) as well as Why we are going reactive.

Here is how you can get it:

<dependencies>
    <dependency>
        <groupId>com.couchbase.client</groupId>
        <artifactId>java-client</artifactId>
        <version>2.0.0-beta2</version>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>couchbase</id>
        <name>couchbase repo</name>
        <url>http://files.couchbase.com/maven2</url>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>

Here is a rundown of the new additions and changes:

Artifact name change

We chose to rename the couchbase-client artifact to java-client for the following reasons:

• First, this allows us to add more language bindings in the future without breaking the naming scheme (thinking of scala-client, jruby-client and so forth).
• Second, it allows you to run both the old and new Java SDK side by side! This has been requested several time by users who want to upgrade slowly and in a controlled manner. Since this is a complete rewrite compared to the old one, there are no clashes which would prevent that from happening.

Make sure to adopt your dependency artifact accordingly when upgrading from beta1 or earlier.

Blocking APIs

This is probably the change with the largest impact, and we chose to break the API one last time before GA for greater good. We got many requests stating that while the asynchronous API is very powerful, very often all that is needed is a simple blocking API. Also, getting accustomed to Observables and the new API are two tasks at the same time and they may slow down adoption.

Therefore, we did put a synchronous wrapper API around the asynchronous one. You now have both APIs available at your fingertips, just use the one which fits your needs. It is especially designed to be used side-by-side, so you can mix and match depending on the operation to perform.

All asynchronous operations are now in the "Async" interface counterparts to the blocking ones. So you can either go from the blocking API to the nonblocking one like this:

// Connect Sync
Cluster cluster = CouchbaseCluster.create();
Bucket bucket = cluster.openBucket("beer-sample");

// Load a Document sync
JsonDocument doc = bucket.get("21st_amendment_brewery_cafe");
System.out.println(doc);

// Get access to the async bucket and load the document async
AsyncBucket asyncBucket = bucket.async();
asyncBucket
    .get("21st_amendment_brewery_cafe")
    .subscribe(System.out::println);

// Disconnect sync
cluster.disconnect();

Or directly instantiate the async client (this mirrors the previous behavior):

// Connect Async
AsyncCluster cluster = CouchbaseAsyncCluster.create();
Observable<AsyncBucket> bucket = cluster.openBucket("beer-sample");

Every interface that provides synchronous access to the data also has a async() method which gives you direct access to the underlying asynchronous implementation. So if you want to migrate your code, just use async() to convert your blocking instance directly into a non-blocking one.

Since this is a interface breaking change, we have adapted the documentation accordingly.

More Document and Transcoder types

More document types (and their corresponding transcoders) have been added to give you a broader range of storable types by default. This list includes (including to the already present JsonDocument for objects and LegacyDocument to interop with the 1.* SDK):

• JsonArrayDocument -> to store Json Arrays as the toplevel value
• JsonBooleanDocument -> to store Json Boolean as the value
• JsonDoubleDocument -> to store Json Number (double/float) as the value
• JsonLongDocument -> to store Json Number (long/int) as the value
• JsonStringDocument -> to store Json String (quoted) as the value

• StringDocument -> to store a raw (non JSON) string unquoted
• SerializableDocument -> to store a POJO which implements Serializable
• BinaryDocument -> to storw raw bytes which are not transcoded in any form.

Here are some examples:

bucket.upsert(JsonArrayDocument.create("array", JsonArray.from("foo", "bar")));
System.out.println(bucket.get("array", JsonArrayDocument.class));

bucket.upsert(JsonBooleanDocument.create("boolean", true));
System.out.println(bucket.get("boolean", JsonBooleanDocument.class));

bucket.upsert(JsonStringDocument.create("jstring", "Hello World"));
System.out.println(bucket.get("jstring", JsonStringDocument.class));

bucket.upsert(StringDocument.create("string", "Hello World"));
System.out.println(bucket.get("string", StringDocument.class));

This prints:

JsonArrayDocument{id='array', cas=9145230438450, expiry=0, content=["foo","bar"]}
JsonBooleanDocument{id='boolean', cas=9105234519913, expiry=0, content=true}
JsonStringDocument{id='jstring', cas=9105238274737, expiry=0, content=Hello World}
StringDocument{id='string', cas=9069020208964, expiry=0, content=Hello World}

Note the difference between a JsonString which will be stored quoted (and browsable from the Couchbase Server UI), while the regular string document will not be quoted and stored as "non JSON" on the server side. Thanks to the new interoperability between 2.0 SDKs, the meta information stored together makes it possible to retrieve or store them with for example .NET or NodeJS.

On the last mile

We are planning to deliver a 2.0.0 GA in the very near future. We consider it stable enough by now so you can start developing your applications and push them into a production environment. While we are doing our best to run lots of scenarios in QE environments, please kick the tires on this release since it is brand new and of course there are bugs hiding. 

If you find them, please raise them at the JCBC bugtracker immediately so we can fix them before the GA release. We also plan on a 2.0.1 bugfix release a few weeks after GA which will contain fixes for some of the release noted tickets.