Compatibility of Couchbase Features, Couchbase Versions and the Couchbase Java SDK

Couchbase Version/SDK Version Matrix

Couchbase SDKs are tested against a variety of different environments to ensure both backward and forward compatibility with different versions of Couchbase Server. The matrix below denotes the version of Couchbase Server, the version of the Java SDK, and whether the SDK is:

✖ Unsupported: This combination is not tested, and is not within the scope of technical support if you have purchased a support agreement.
◎ Compatible: This combination has been tested previously, and should be compatible. This combination is not recommended by our technical support organization. It is best to upgrade either the SDK or the Couchbase version you are using.
✔ Supported:This combination is subject to ongoing quality assurance, and is fully supported by our technical support organization.

Table 1. Recommended SDK per Server Version Matrix
	SDK 2.0	SDK 2.1	SDK 2.2, 2.3, 2.4	SDK 2.5
Server 3.1	◎	◎	◎	✖
Server 4.0-4.6	◎	◎	✔	✔
Server 5.0-5.1	◎	◎	✔	✔

Note the End of Life dates for Couchbase Server and SDK versions. See the notes there for Support details.

To take advantage of all features offered by Couchbase Server, you need to know what version of the Java SDK provides compatibility for the features you want to use. The following matrix shows which versions of the Couchbase Java SDK support the major features of each version of Couchbase Server.

Table 2. Couchbase Server and SDK Supported Version Matrix
	Server 1.8	Server 2.0	Server 2.5	Server 3.0, 3.1	Server 4.0, 4.1	Server 4.5, 4.6	Server 5.0
Basic Features
CRUD Operations	Since 1.0
View Querying APIs	Since 1.1
Geospatial Views	Not Supported	1.1 - 1.4		Since 2.1
Advanced Features
Durability Requirements	Since 1.1
Carrier Publication Configuration	Not Supported		Since 1.4
SSL Connectivity	Not Supported			Since 2.0
Bulk Operations	Since 1.0
N1QL Querying	Since 2.0 (experimental)				Since 2.2
Multi-Dimensional Scaling	Not Supported				Since 2.2
Sub-document API	Not Supported					Since 2.3
Full Text Search	Not Supported					Since 2.3 (Experimental)	Since 2.4
Administrative Features
Datastructures	Not Supported					Since 2.3
Extended Attributes	Not Supported						Since 2.4
Administrative API	Since 1.0
RBAC	Not Supported						Since 2.4

With RBAC, in Couchbase Server 5.0, authentication will depend upon access privileges, and upgrading to 5.0 with existing buckets, or upgrading Server, will require taking these changes into account.

JDK Version Compatibility

The Java SDK is tested with the Oracle JDK which should be used for best experience and supportability. Other JDK implementations might work but are not tested and are unsupported.

The following Oracle JDKs are supported for Java SDK 1.4 and 2.0 - 2.5:

Oracle JDK 1.6
Oracle JDK 1.7
Oracle JDK 1.8 (recommended)

Please make sure you run on one of the latest patch releases, since they provide stability improvements and security fixes in general.

Spring Data Couchbase Compatibility

Spring Data Couchbase uses the Java SDK underneath and as a result is also provides different compatibilities with Couchbase Server. The following table provides an overview.

Table 3. Recommended Spring Data Couchbase per Server Version Matrix
	SDC 2.1.x	SDC 2.2 & 3.0
Status >	Bug fixes only	New Features, Active Development
Server 3.1	Compatible	Recommended
Server 4.0-4.6	Compatible	Recommended
Server 5.0	Compatible	Recommended

Migrating from Java SDK 1.4.x to 2.x

Couchbase recommends that you migrate to the Java 2.x SDK to take advantage of enhancements to the SDK as well as new features available in Couchbase Server.

The 2.x Java SDK is based on the reactive programming model and has a different architecture that uses a core I/O layer and a Java client layer. It’s asynchronous by design and offers performance, scalability, and durability enhancements.

This guide helps you migrate from the previous generation of the Java SDK (version 1.4.x) to this new generation SDK (version 2.x).

If you plan on using the synchronous blocking API, you can follow the simple migration path. Or, you can follow the optional migration path to fully reactive and asynchronous code by using the asynchronous API, which provides the best performance.

To get the full benefit of using the asynchronous code with this new generation SDK, you need to understand how to build asynchronous yet expressive code by leveraging the Observable paradigm. The Asynchronous Progamming Using the Java SDK with Couchbase Server has more information on reactive programming with the Java SDK.

1.x-2.x Migration: Getting Started

The 2.x generation of the Java SDK is a complete rewrite of the 1.x SDK. It is layered into core-io and java-client pieces. The java-client layer is more abstract and closer to the client. The core-io layer is purely asynchronous and message-oriented. It makes use of a reactive architecture based on Netty, the LMAX Disruptor, and most importantly RxJava.

The core-io layer is not intended for broad consumption. In general, you should focus on using the java-client layer in your application. For advanced use cases, when you are trying to squeeze out the very last drop of performance working with the raw byte stream or building a client layer in another language, you can use the core-io layer.

The client exposes the server-side concepts of a Cluster and Buckets as first-class citizens that replace the previous CouchbaseClient class. Each class exposes a synchronous API by default, but an asynchronous API (based on RxJava Observable objects) can be accessed simply by calling async() on either one.

This split also allows for much more efficient resource utilization. In the past, each CouchbaseClient (for each bucket) had its resources, but now they are as shared as much as possible, and the Cluster and Bucket references can always be reused.

The Maven artifact has been renamed from couchbase-client to java-client to differentiate this rewrite from the previous generation. It has minimal transitive dependencies (by embedding a few internal dependencies like Netty), most notably RxJava 1.x:

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

After you’ve fully migrated, make sure that old dependencies to couchbase-client or dependencies introduced in your POM because of the couchbase-client have been removed.

You’ll most probably want the SDK to perform some logging, which can easily be activated by adding a logging framework such as log4j to your dependencies. For more information about configuring logging, see Collecting Information and Logging in the Java SDK with Couchbase Server.

1.x-2.x Migration: Cluster Connections

CouchbaseClient is replaced by the Cluster and Bucket classes, bringing real-world concepts of Couchbase into the SDK as first-class citizens. For more information about using these classes, see Managing Connections using the Java SDK with Couchbase Server.

Compared to the 1.4.x SDK, when providing a list of nodes for bootstrapping, you only need hostnames or IP addresses in String form. No need for the URI anymore, and no need for the port and pools path either:

Cluster cluster = CouchbaseCluster.create("192.168.0.1");

The SDK uses the factory method pattern to create the Cluster object. This pattern is heavily used throughout the SDK in place of constructors.

The Cluster and each Bucket reference must be reused as much as possible. Make them singletons, which can be used by multiple threads safely. Here’s an example that uses a naive helper approach:

public class CouchbaseHelper {
    //the IPs / hostnames would be obtained from configuration file
    private static final List<String> SEED_IPS = Arrays.asList("192.168.0.1", "192.168.0.2");
    public static final Cluster CLUSTER = CouchbaseCluster.create(SEED_IPS);
    public static final Bucket EXAMPLEBUCKET = CLUSTER.openBucket("example", "p4ssW0rd");
}

You can customize the connection to the Cluster via the CouchbaseEnvironment interface.

public class CouchbaseHelper {
    //the IPs / hostnames would be obtained from configuration file
    private static final List<String> SEED_IPS = Arrays.asList("192.168.0.1", "192.168.0.2");
    //the environment configuration
    private static final CouchbaseEnvironment ENV = DefaultCouchbaseEnvironment.builder()
        .connectTimeout(8 * 1000) // 8 Seconds in milliseconds
        .keepAliveInterval(3600 * 1000) // 3600 Seconds in milliseconds
        .build();
    public static final Cluster CLUSTER = CouchbaseCluster.create(ENV, SEED_IPS);
    public static final Bucket EXAMPLEBUCKET = CLUSTER.openBucket("example", "p4ssW0rd");
}

1.x-2.x Migration: Document Operations

In the new SDK, a new model of data within Couchbase was introduced: the Document class. It encapsulates both the content itself and the metadata ( id, expiry and cas information). The CRUD Document Operations Using the Java SDK with Couchbase Server page shows more specifics regarding document operations with the 2.x version of the SDK.

The SDK has several implementations of Document. By default, most SDK methods assume the content is JSON and return a JsonDocument. This kind of document use standardized storing flags, which make it compatible with the other second generation SDKs in other languages. If you already deal with JSON transcoding to domain objects, use the RawJsonDocument instead, which exposes the JSON String as content instead of a superfluous JsonObject.

To interact with documents stored by an older Java SDK, use the LegacyDocument class. This class provides 1:1 compatibility with the 1.4 SDK, but consider to migrate to a new implementation after backward compatibility isn’t required anymore.

Concerning optimistic locking—because the CAS is now part of the Document, the SDK picks it up if it is non-zero during mutating operations.

1.x-2.x Migrations: Reactive and Batched Programming

In the 2.x SDK, asynchronous processing is done via RxJava. The asynchronous API is not mixed with the synchronous API, but rather accessible via the async() method on Cluster and Bucket.

The SDK is thread-safe and uses a pool of threads internally for operations (so they are effectively processed in a separate thread). Additionally, some Rx operators use one of the Schedulers provided by RxJava (meaning it could execute in another thread).

The SDK doesn’t use Future objects anymore. For progressive migration purposes, you can convert an Observable into a Future and vice versa. Here’s an example of how to do that:

//converting these to/from Future
Observable<String> myStringObservable;
Future<String> myStringFuture;
//this expects exactly one item emitted
Future<String> f = myStringObservable.toBlocking().toFuture();
//when several items expected, use a List
Future<List<String>> f = myStringObservable.toList().toBlocking().toFuture();
//convert back from a Future<String>
Observable<String> o = Observable.from(myStringFuture)

Interface Stability

Couchbase SDKs indicate the stability of an API through documentation. Since there are different meanings when developers mention stability, we mean interface stability: how likely the interface is to change or be removed entirely. A stable interface is one that is guaranteed not to change between versions, meaning that you may use an API of a given SDK version and be assured that the given API will retain the same parameters and behavior in subsequent versions. An unstable interface is one which may appear to work or behave in a specific way within a given SDK version, but may change in its behavior or arguments in future SDK versions, causing odd application behavior or compiler/API usage errors. Implementation stability is implied to be more reliable at higher levels, but all are tested to the level that is appropriate for their stability.

Couchbase uses three interface stability classifiers. You may find these classifiers appended as annotations or comments within documentation for each API:

Committed: This stability level is used to indicate the most stable interfaces that are guaranteed to be supported and remain stable between SDK versions.
Uncommitted: This level is used to indicate APIs that are unlikely to change, but may still change as final consensus on their behavior has not yet been reached. Uncommitted APIs usually end up becoming stable APIs.
Volatile: This level is used to indicate experimental APIs that are still in flux and may likely be changed. It may also be used to indicate inherently private APIs that may be exposed, but "YMMV" (your mileage may vary) principles apply. Volatile APIs typically end up being promoted to Uncommitted after undergoing some modifications.
Internal: This level is used to indicate you should not rely on this API as it is not intended for use outside the module, even to other Couchbase components.

APIs that are marked as Committed have a stable implementation. Uncommitted and Volatile APIs should be stable within the bounds of any known and often documented issues, but Couchbase has not made a commitment to these APIs and may not respond to reported defects with the same priority.