A newer version of this documentation is available.

View Latest

Release notes

Release notes for the 2.2 version of the Java SDK.

Couchbase Java Client 2.2.8 GA (8 June 2016)

Version 2.2.8 is the eighth bugfix release of the 2.2 series. It brings bug fixes and enhancements.

New features

This release contains the following enhancements:

  • For this release, the associated core-io version is also one patch version ahead with 1.2.9.

  • JCBC-961: In ViewQuery, the isOrderRetained getter is now public.

Fixed Issues

This release fixes the following issues:

  • JVMCBC-340: Fix the keep alive messages not being sent anymore. This issue was due to a 2.2.6 change in Netty usage, saving allocations on writes but not triggering the same kind of idle signals.

  • JVMCBC-339: Flush signals are only sent to non-null endpoints, guarding against potential NPEs.

Couchbase Java Client 2.2.7 GA (6 May 2016)

Version 2.2.7 is the seventh bugfix release of the 2.2 series. It brings bug fixes and enhancements.

New features

This release contains the following enhancements:

  • For this release, the associated core-io version is also one patch version ahead with 1.2.8.

  • JVMCBC-325 , JVMCBC-327: All outgoing HTTP requests now have a HOST header.

  • JCBC-952: The experimental Index Management API now has the "N1ql" word in all methods (like "listN1qlIndexes()") to allow future evolutions with different types of indexes. It can also create a secondary N1QL index with a WHERE clause.

Fixed Issues

This release fixes the following issues:

  • JVMCBC-326: N1QL and View parser fix for json strings ending with 2 backslashes.

Couchbase Java Client 2.2.6 GA (5 April 2016)

Version 2.2.6 is the sixth bugfix release of the 2.2 series. It brings bug fixes, enhancements, and correctness improvements.

New features and behavioral changes

This release contains the following enhancements:

  • For this release, the associated couchbase-jvm-core version is one patch version ahead with 1.2.7.

  • Dependencies: RxJava and Netty dependencies have been bumped to their latest bugfix releases (1.0.17 and 4.0.35).

  • JCBC-928, JCBC-926, JCBC-936, JCBC-925: The Index Management API has been overhauled and improved. You can notably now manage primary indexes with custom names.

  • JCBC-944, JCBC-946, JCBC-948, JVMCBC-324: N1QL improvements. For the adhoc(false) category of N1QL queries, it is now possible to disable sending the prepared_plan with prepared statements to save bandwidth (use with care!), and internal prepared names are correctly escaped if used. N1QL helper to build updateFor clause. In the core, some N1QL requests can be made to target specific nodes.

  • JCBC-931, JCBC-938, JCBC-940: The experimental Subdocument API has been enhanced and slightly streamlined: some array-related methods have been renamed (eg. pushFront to arrayPrepend), array mutation methods now can accept several items to insert in one go, the doLookup() and doMutate() execution methods have both been renamed execute().

  • JVMCBC-313: SCRAM-* is now enabled by default if the server supports it.

  • JVMCBC-317: It is now possible to use the Epoll netty transport for better IO performance on Linux. The library is embedded in the latest Netty distribution.

  • JCBC-875: The Retrybuilder now supports adding an advanced error predicate (allowing for example to only retry on exceptions with a certain message), as well as a doOnRetry hook that you can use to get notified of each retry attempt.

  • JCBC-943, JVMCBC-322: Version information about the SDK is now richer in CoreEnvironment and CouchbaseEnvironment. The former’s packageNameAndVersion method (as well as the user agent) now displays the java-client version, with the core’s version in the details. Getters have been added so you can get the version and build number (a more exact git reference) for both core and java-client.

  • JCBC-937: JsonObject and JsonArray now both accept a size hint at construction.

  • JVMCBC-298: Implement 0x97 DCP protocol command to get last closed checkpoint (OP_GET_LAST_CHECKPOINT).

  • JVMCBC-300, JVMCBC-299, JVMCBC-301, JCBC-935, JVMCBC-310, JVMCBC-303, JVMCBC-308, JVMCBC-302, JVMCBC-306: Many small performance and GC enhancements: avoid unnecessary allocations, avoid redundant encoding of keys, optimize scheduling and selection strategies, better split classes... Allow optional Observable completion on the Event Loops.

Fixed Issues

This release fixes the following issues:

  • JVMCBC-309: Gracefully handle errors during metrics collection.

  • JVMCBC-323: Gracefully handle config completion errors during shutdown.

  • JVMCBC-312, JVMCBC-315, JVMCBC-305, JVMCBC-311: DCP related fixes: use the same logical connection for all DCP nodes, use double for ack threshold in Builder, allow DCP connectors to notify core about processing messages, do not release buffer without copying it.

Couchbase Java Client 2.2.5 GA (1 March 2016)

Version 2.2.5 is the fifth bugfix release of the 2.2 series. It brings bug fixes, enhancements, and correctness improvements.

New features and behavioral changes

This release contains the following enhancements:

  • JCBC-906: (experimental) The index management API on the BucketManager has been revised to match the desired functionality across SDKs.

  • JCBC-921: (experimental) The subdocument API has been rewritten completely to now use a builder-like API that unifies single and multi-path operations significantly. Note that you can only use it against Couchbase Server 4.5 or later.

  • JCBC-804: (experimental) Enhanced "Read Your Writes" capabilities have been added to N1QL queries. If MutationTokens are enabled on the environment, the result of a mutation can be passed in as a query option on a N1QL query, providing better performance in certain use cases. This is a pure optimization on REQUEST_PLUS and should only be considered if that one does not meet the requirements. Note that you can only use it against Couchbase Server 4.5 or later.

  • JCBC-910: Thanks to a community contribution by Kim Intae it is now possible to optionally specify a strict ordering on View queries when includeDocs is used. By default, the rows are returned as the documents arrive, but sometimes it is important to keep the ordering from the original row stream.

  • JVMCBC-280: Client side support for SCRAM-SHA1, SCRAM-SHA256 and SCRAM-SHA512 has been added, but is disabled by default (and can only be enabled through a to-be-removed-soon system property called com.couchbase.scramEnabled). Once the server provides full support (Couchbase Server 4.5 GA), it will be enabled by default.

  • JVMCBC-292: It is now possible to use different powers on the ExponentialDelay in addition to the default power of two. This gives more flexibility in how fast the delay should grow and what pattern it is using.

  • JVMCBC-294: The SDK now passes bucket-level credentials to the FTS service (similar to N1QL and Views).

Fixed Issues

This release fixes the following issues:

  • JVMCBC-293: A bug in the ExponentialDelay has been fixed which makes sure the overflow guard works against 64 bit and not 32 (since it is using a long field internally). This is expanding on earlier fixes in the exponential delay, avoiding it to wrap around and starting with the lowest value again.

Couchbase Java Client 2.2.4 GA (3 February 2016)

Version 2.2.4 is the fourth bugfix release of the 2.2 series. It brings bug fixes, enhancements, and correctness improvements.

New features and behavioral changes

This release contains the following enhancements:

  • JCBC-849: Experimental support for the SubDocument feature has been added. Subdocument allows you to transmit only the specific part of a JSON document that you want.

  • JCBC-850: Experimental support for Full Text Search (FTS), a new type of index in Couchbase Server 4.5 that allows you to do, for example, the fuzzy text search queries.

  • JCBC-869: N1QL row values can now be deserialized by a custom library since they expose the raw value as a byte[] through byteValue(). The JsonObject value() is deserialized lazily from this byte array, so never invoking it will completely avoid the overhead of JsonObject deserialization if you don’t need it.

  • JVMCBC-279: The bucket’s name has been added to the MutationToken produced when enhanced durability is activated.

  • JVMCBC-282: When a node is being reconnected, a notification is sent through the EventBus.

  • JVMCBC-281, JVMCBC-284, JVMCBC-285, JVMCBC-287: Various allocating and caching changes for performance improvements.

Fixed Issues

This release fixes the following issues:

  • JVMCBC-278: A socket timeout on a Netty endpoint would prevent any further attempt at reconnecting the client altogether. A message in the logs stating that "Socket connect took longer than specified timeout" would appear and the client wouldn’t reconnect to the node when it would come back online.

  • JVMCBC-288: Various Locators now correctly only locate a Node that has the proper service enabled.

  • JCBC-903: Some CouchbaseFeature enums were referencing wrong Couchbase Server version.

  • JCBC-904: The socketConnectTimeout tuning can now properly be set on the CouchbaseEnvironment.

  • JVMCBC-277: Netty sources are now properly relocated in the source jar to match the shaded classes in the main jar (looking at sources and entering the Netty shaded classes should now work).

  • JVMCBC-286: Build process now checks both in core and client that only classes and methods that are available in a Java 6 JRE/JDK are used.

Couchbase Java Client 2.2.3 GA (5 January 2016)

Version 2.2.3 is the third bug fix release of the 2.2 series. It brings bug fixes, enhancements, and correctness improvements.

New features and behavioral changes

This release contains the following enhancements:

  • JCBC-777: Experimental Index management on the BucketManager has been added, allowing to create, drop and list GSI indexes.

  • JCBC-883, JCBC-757: The Query Builder API has been greatly extended. Select now supports fromCurrentBucket(). Support for Insert, Upsert, Update, Remove and Merge has been added.

  • JVMCBC-273: Experimental core support for the SubDocument API has been added.

  • JVMCBC-269: DCP core implementation of Get Failover Logs (0x54) command.

Fixed Issues

This release fixes the following issues:

  • JCBC-895: A potential overflow when using MAX_VALUE on the RetryBuilder has been fixed.

  • JCBC-894: Thanks to a community contribution, the BucketManager is now compatible with old Couchbase/Membase releases.

  • JVMCBC-267, JVMCBC-272, JVMCBC-270: DCP related fixes relative to seqno and flow control.

  • JVMCBC-274: The ExponentialDelay grows so large by the 32th attempt that it overflows back to negative values, producing a cycle of short, bursty retries back every 32 attempts (especially if the lower bound and time unit are small). It is now staying at Integer.MAX_VALUE delay duration past the 32th attempt.

Couchbase Java Client 2.2.2 GA (12 November 2015)

Version 2.2.2 is the second bug fix release of the 2.2 series. It brings many bug fixes, stability improvements as well as smaller enhancements.

New features and behavioral changes

This release contains the following enhancements:

  • JCBC-871: The N1qlQueryResult (and async variant) has been extended to now also expose the Status as a string, allowing for more fine-grained matching and reporting on potential errors.

  • JVMCBC-256: In the next minor version, a blocking version of the shutdown method on the Environment will be introduced. To make the smaller impact, the current shutdown method on the CouchbaseEnvironment has been deprecated and explicitly refers to the new shutdownAsync method.

  • JCBC-863, JCBC-870: While it is still best practice and heavily encouraged to cache and reuse Bucket references, an effort has been made to reduce the impact of potential misuse. The client now caches open bucket instances and reuses them where possible if many subsequent openBucket calls are performed.

Fixed issues

This release fixes the following issues:

  • RxJava has been upgraded to 1.0.15 to address shutdown-cleanup related issues. In-depth discussion of this topic can be read here.

  • JCBC-864: The remove operation, when used with the durability requirements now properly honors the CAS when provided inside the Document. It now correctly throws CASMismatchExceptions when the CAS does not match with the server. Previously, the supplied CAS was ignored, and the remove operation performed without optimistic concurrency checks.

  • JVMCBC-263: A bug in the view query parser has been uncovered, which would make it hang particularly when the key includes a closing }, but no opening { inside a string.

  • JVMCBC-262: The logic that performs the proactive load of new configurations through the "Carrier Publication" mechanism now only targets nodes where the KV-Service is enabled. Such targeting is important in MDS scenarios so that it doesn’t ask nodes where only the query or indexing services are enabled.

  • JVMCBC-102: The initial bootstrap process has been made more resilient to individual node failures, fixing a bunch of bugs around initial bootstrapping. Especially the case where one of the nodes is not responding and opening a memcached type bucket now works correctly (this involves internally skipping over not responding nodes as well as falling back from carrier publication to the http bootstrapping approach).

  • JVMCBC-257, JVMCBC-265: The configuration management logic has been improved in various places, making it more resilient to failed bucket open attempts (cleaning up the state properly) as well as optimizing the proactive config loading approach when no buckets are open or are currently being closed. In particular, one issue has been resolved where an asynchronous open bucket attempt with a fallback to a good one did not work previously.

  • JVMCBC-266: The client now proactively checks if the document ID is null, empty or too large where it can be directly passed in. Previously, the operation would fail with the server responding INVALID_ARGUMENTS where now it is very clear what the root cause of the issue is. The client now fails the Observable right away with an IllegalArgumentException explaining what the problem is.

  • JCBC-865: In the N1QL builder API, the an invalid query was generated when multiple WHEN blocks are used in the CASE statement, leading to query errors. This issue has been fixed; the client now emits correct N1QL statements in those cases.

Couchbase Java Client 2.2.1 GA (13 October 2015)

Version 2.2.1 is the first bug fix release of the 2.2 series. It contains bug fixes and correctness improvements, especially during bootstrap, shutdown and when SSL is enabled.

New features and behavioral changes

This release contains the following enhancements:

  • JVMCBC-250: An explicit, lower (configurable) socket connect timeout is now always used when connections are established. This provides more reliable semantics during the socket open phase and allows for faster-retrying mechanisms inside the core layer.

  • JVMCBC-242, JVMCBC-247: The internal dependencies for Jackson and Netty have been bumped to their latest bugfix releases for increased stability.

  • JVMCBC-241, JVMCBC-253: Experimental Support for DCP has been improved. ERANGE and ROLLBACK during the stream open phase are now handled properly. Also, it is now possible to partially initialize streams (for example to only get the streams for a specific number of partitions).

  • JVMCBC-246: The KeyValue STAT command is now implemented in the core layer, allowing for more flexibility in the future to grab key or cluster statistics. Note that STATS are not exposed to the java-client at this point, but might be in the future as encapsulated APIs.

  • JVMCBC-245: When latency metric events are emitted, the original time unit is now included, so later analysis does not need to reference back to the source code for the time unit used.

  • JCBC-854: Encoding for all string-based document types has been made faster by a factor of 2 and more, this also includes the RawJsonDocument.

Fixed issues

This release fixes the following issues:

  • JVMCBC-251: The full cleanup of SDK-owned threads during full shutdown has been improved across the board, allowing diagnostics through logs and fixing behavior especially when performing redeployments in an application container.

  • JVMCBC-248: SSL Handshake failures during the connect phase are now more explicitly handled and propagate the right error up the call stack.

  • JVMCBC-242: A TranscodingException when decoding JSON arrays has been fixed by upgrading the internal Jackson dependency to 2.6.2.

Couchbase Java Client 2.2.0 GA (2 September 2015)

Version 2.2.0 is the first release of the 2.2 series and brings compatibility with Couchbase Server 4.0 as well as lots of new features and enhancements.

Migration Notes

While the 2.2 release does not bring any breaking changes to stable APIs over 2.1, some APIs have been modified and unstable APIs renamed. The following information provides guidelines on migrating from 2.1.x:

  • The counter(String id, long delta) method and associated overloads (custom timeout or with durability requirements) have been modified so that it throws a DocumentDoesNotExistException if the document does not exist. Previously, the code automatically initialized the document with 0. The 1.x SDK provided a similar feature, so we wanted to bring it back for more flexibility. The new code is simple—just use the overload with an initial value of 0:

    // before
    bucket.counter("id", 10);
    // after
    bucket.counter("id", 10, 0);
  • If the CAS is set on the documents used in append/prepend operations and the server CAS does not match, previously a generic CouchbaseException was thrown. Now the code checks for this response status and returns a more correct CASMismatchException.

    Because this exception extends the CouchbaseException, your code might still work although checking for this explicit exception type is recommended.

  • If you have been using the asynchronous API, be aware that all the asynchronous API methods are now returning cold Observables instead of hot Observables. As a result, you don’t need to call Observable.defer() around the bucket calls if you want proper retry semantics. If you are doing that already, you can remove the calls (but don’t have to—it’s just a little more overhead). Also, it has been always recommended, but make sure to subscribe to all of your Observables. Hot Observables``Observable might have been automatically executed, but cold Observables won’t. Not subscribing, in general, goes against the RX contract.

  • If you’ve been implementing your own Document type together with a custom transcoder, you now need to implement a new method if you want to use the document together with the new feature called enhanced durability. The specific change is that you need to add a simple factory method that allows you to pass in the new MutationToken. Your old code will keep working, but for future compatibility we recommend adding this new method.

    As an example here is how the JsonDocument implements the new method. If you want, you can also make the older factory method just forward to the new one:

    // Pre-2.2, can still be used
    public JsonDocument newDocument(String id, int expiry, JsonObject content, long cas) {
        return JsonDocument.create(id, expiry, content, cas);
    // New in 2.2
    public JsonDocument newDocument(String id, int expiry, JsonObject content, long cas,
        MutationToken mutationToken) {
        return JsonDocument.create(id, expiry, content, cas, mutationToken);

    If your document extends from the AbstractDocument, make sure you call the new super method with the token instead of the old one:

    private JsonDocument(String id, int expiry, JsonObject content, long cas, MutationToken mutationToken) {
        super(id, expiry, content, cas, mutationToken);

    Make note of the following:

  • To make the N1QL queries more consistent with the View queries, all exposed N1QL classes have been prefixed with N1QL or been renamed in a slightly different manner to make the intent clear. We did rename Query, QueryResult, QueryRow, their asynchronous counterparts, concrete implementations and related tests by prefixing Query with N1ql. Also, QueryMetrics and QueryParams have been respectively renamed to N1qlMetrics and N1qlParams. Finally, the QueryExecutor has been renamed to N1qlQueryExecutor.

  • Since we are stabilizing the API now, we also had to rename the parametrized query to parameterized. This is to ensure the best possible experience across SDKs and consistent documentation for client and server.

New features and behavioral changes

This release brings the following features and enhancements:

  • JVMCBC-137, JVMCBC-222, JCBC-732, JCBC-761 (and more): Official Couchbase Server 4.0 Support. This includes mainly a stable and tested N1QL API, as well as support for MDS (Multi-Dimensional Scaling). Use 2.2.0 and later as your go-to release when working with CB Server 4.0 and up.

  • JVMCBC-60: System and Latency Metrics are now collected in an "always on" fashion and emitted to the event bus every hour by default. This is all configurable and tunable based on the applications needs. Please consult the documentation on metrics to get all the nitty gritty details.

  • JCBC-826, JVMCBC-190, JVMCBC-205: 4.0 also introduces a new feature called enhanced durability, which allows for more accurate durability requirements (PersistTo and ReplicateTo). All you need to do is enable the mutation tokens on the environment, but keep in mind that there is an increased byte overhead on every mutation.

    // Enable enhanced durability
    CouchbaseEnvironment environment = DefaultCouchbaseEnvironment.builder()
    // Perform an operation as before and benefit from it transparently
    bucket.upsert(doc, PersistTo.MASTER, ReplicateTo.ONE);
  • JCBC-744: Experimental support for POJO mapping capabilities have been added in the form of a repository API. See this blog post for more details. Here is a quick example. Right now you need a no-args constructor to recreate the object again, we’ll make it more flexible with explicit constructors in the future so you can use final fields.

    public static class User {
        private String username;
        private String firstname;
        private String lastname;
        public User(String username, String firstname, String lastname) {
            this.username = username;
            this.firstname = firstname;
            this.lastname = lastname;
        public User() {}
    Repository repository = bucket.repository();
    User user = new User("daschl", "Michael", "N.");
    System.out.println(repository.get("daschl", User.class).content().firstname);
  • JCBC-805: The getFromReplica() method now has an overload that returns an Iterator, making it more flexible on the blocking API to only extract one or two results if needed (and don’t wait for all responses).

  • JCBC-749: includeDocs on the ViewQuery has been re-added (it was there in 1.x) so that the blocking API can benefit from efficient bulk document loading in the background automatically. If you are using the asynchronous API only, you won’t need this query option.

  • JCBC-784: As mentioned in the migration notes above, the counter overload with no default value has been enhanced to throw an exception if the document does not exist. Previously, it was not possible to only use the counter method on documents that exist (they would always be initialized with a default value of 0 instead).

  • JCBC-836: Durability Requirements for append, prepend and counter have been added to the Bucket API. This allows you to observe persistence and replication not only on insert, upsert, replace and remove, but also on append, prepend and counter. Of course, this all plays well with the new enhanced durability feature we’ve added if you work against Couchbase Server 4.0 or later.

  • JCBC-782: All asynchronous API calls are now "cold", which means they are not eagerly run until subscribed by the caller. This won’t affect basic usage, but makes it easier when doing asynchronous retry logic or branching to fallback calls.

  • JCBC-652: When creating or replacing a DesignDocument, you can now specify different options that are configurable on a per design document basis. Please see the documentation for a list of those options.

  • JVMCBC-237: To detect cluster changes in MDS setup more reliably, the SDK now polls for a new configuration every 10 seconds. This is completely transparent, but can be seen when dumping the network traffic. Note that the NOOP heartbeat polling is still in place, only the piggybacked configuration reloading has been superseded with this more general approach.

Fixed issues

This release fixes the following issues:

  • JVMCBC-231: A race condition has been fixed during shutdown (internal reconfigure), when all nodes are removed.

  • JCBC-834: The blocking API for spatial queries was using the default timeout for N1QL queries instead of views. They are set to the same value by default, but can be changed on the environment separately, probably leading to weird behavior if not taken into account.

  • JCBC-815: Do not let the CouchbaseEnvironment.Builder implement the CouchbaseEnvironment. This has lead to confusion during development and is not necessary.

Known issues

This release contains the following known issues to be addressed in subsequent releases:

  • JVMCBC-242: A TranscodingException is thrown when decoding long arrays (for details see the ticket). This has been addressed in 2.2.1.