Release notes

Release notes for the 2.1 version of the Java SDK.

Couchbase Java Client 2.1.6 GA (2 December 2015)

Version 2.1.6 is the sixth bug fix release of the 2.1 series. It contains bug fixes and stability improvements in bootstrapping, configuration management, view queries and remove with CAS.

Important: A newer version of this software with updated documentation is available. Visit the Couchbase Developer Portal for more information.

Fixed issues

This release fixes the following issues:

  • JCBC-864: When used with the durability requirements, the remove operation 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 was performed without optimistic concurrency checks.
  • JVMCBC-263: A bug in the view query parser has been uncovered which would make the parser hang when the key, in particular, includes a closing } but no opening { inside a string.
  • JVMCBC-262: The logic that performs a 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 multi-dimensional scaling (MDS) scenarios so that it doesn't address the 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 many bugs around initial bootstrapping. This improvement especially affects the case where one of the nodes was not responding and opening a memcached type bucket. It now works correctly, which 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 or cleaning up the state properly. The proactive configuration loading approach was also optimized 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.

Couchbase Java Client 2.1.5 GA (13 October 2015)

Version 2.1.5 is the fifth bug fix release of the 2.1 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-229: In various forum questions we've identified DNS issues as a common problem for timeouts during the open bucket phase. To help with easier debugging, we now proactively perform the DNS lookup in advance and print a WARNING log if it takes much longer than it should (over 1 second).
  • JVMCBC-222: Multi Dimensional Scaling (MDS) support for Memcached buckets has been introduced to be forward compatible with Couchbase Server 4.0 and later.
  • 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.

Fixed issues

This release fixes the following issues:

  • JCBC-834: The query(SpatialView) method was using the wrong timeout setting (N1qlQuery instead of ViewQuery). This has been fixed and it is now using the proper view timeout.
  • JVMCBC-239: A bug in the N1QL response parser has been fixed which was sometimes triggered during server node restarts. The parser would not be able to move on and be stuck in an invalid state of the stream parsing phase, resulting in consistent and non-recovering timeouts on subsequent queries.
  • JVMCBC-231: A race condition in the reconfiguration logic during shutdown has been fixed which makes this part of the phase much more resilient.
  • JVMCBC-251: Full cleanup of SDK-owned threads during full shutdown, diagnostics have been made easier through new logs, and cb-io threads are more aggressively cleaned up, leading to more correct behaviour 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.

Couchbase Java Client 2.1.4 GA (7 July 2015)

Version 2.1.4 is the fourth bug fix release of the 2.1 series. It contains bug fixes and correctness improvements, especially during node failures when durability requirements and/or replica read operations are used. Also, reported stuck threads after shutdown have been fixed.

Fixed issues

This release fixes the following issues:

  • JCBC-766, JVMCBC-197: If the list of keys passed in for a view query exceeds the limit allowed for a HTTP GET request, it will fail. For that reason, the keys are now transparently delivered in the body of the HTTP request, allowing it to work with an unbounded number of keys.
  • JCBC-790, JVMCBC-211: When ReplicaMode.ALL is used to perform a replica read on the blocking API, the client now transparently drops all partitions which are not available, returning the partial responses much more quickly. During a failover transition phase, the behavior still depends on the failure mode used. By default it will retry based on the timeout before the results are returned, if the fail fast mode is used the results will return more quickly. While we are planning to add a blocking Iterator API in the future, right now you can easily fallback to the asynchronous API to fetch the responding items as they come along. See the documentation for the getFromReplica for more information.
  • JVMCBC-202, JVMCBC-204: When durability requirements are used, the underlying observe poll mechanism is now more resilient to node failures. Previously, it was possible that those observe poll cycles got stuck, either because the underlying operations were timing out (and made the whole batch to time out as well), or the logic suffered from a condition where the operations were written, but not flushed (which caused them to be stuck in the write queue and not transmissioned to NIO/the networking subsystem).
  • JVMCBC-201: During shutdown, all the Couchbase-owned threads are now properly terminated. They were always daemon-threads, but in some environments they need to be explicitly closed so that redeploy works without issues. With this change the core scheduler threads are properly terminated, but this only works if no other scheduler is passed in manually. If this is done, the termination of the threads is up to the user, because the client can't control where it is needed as well.
  • JVMCBC-209: A race condition between a socket disconnect and its automated reconnect logic could lead to a pathological situation where, even if properly instructed to disconnect, the socket will be reestablished over and over again. This race condition has been fixed and additional guards for the shutdown state transition have been put in place to override any other potential race conditions permanently.
  • JCBC-778: A small change in the DCP code avoids a false alarm triggered by an unknown message in the flow. More DCP enhancements are in the pipeline and are likely to ship in the 2.2 branch.

Couchbase Java Client 2.1.3 GA (4 May 2015)

Version 2.1.3 is the third bug fix release of the 2.1 series. It contains bug fixes and correctness improvements, especially when multiple buckets are open or streaming connections are used to grab configuration changes (that is for all memcached buckets and Couchbase buckets on Server 2.2 and older).

New features and behavioral changes

This release contains the following enhancements:

  • JVMCBC-188: Authentication headers are now sent to the remote node when the Query service is used, and as a result password-protected buckets can now also be used for N1QL queries.
  • JVMCBC-191: If the server returns unknown status codes, they are logged for easier debuggability in support tickets.
  • JVMCBC-192: When KeyValue endpoints are idle (that is, no key/value traffic is going through to a specific node for the configured time), in addition to heartbeats, the client now also proactively fetches a new cluster configuration. This avoids undetected cluster topology changes during idle load scenarios.

Fixed issues

This release fixes the following issues:

  • JVMCBC-187: Document IDs with special characters (that is, when a character takes more than one byte) are now properly encoded and decoded. Previously they were not stored correctly and as a result corrupted the wire protocol and the IDs ended up in a bad state on the node.
  • JVMCBC-195, JVMCBC-185: Multiple issues around HTTP config streaming have been fixed. The code now properly restores a new HTTP streaming connection when the old one gets closed. This is important for all memcached buckets, as well as couchbase buckets on Couchbase Server 2.2 and older.
  • JVMCBC-184, JVMCBC-194: Multiple issues around configuration management when multiple buckets are open at the same time have been fixed. Multiple configurations were racing each other in special cases which lead to pathological situations where no new config was picked up as a result. This has been fixed.
  • JVMCBC-186: When some of the nodes in the bootstrap list are not discoverable through the Java InetAddr, the code now ignores (and logs) the error and keeps moving forward. If at least one of the other nodes in the list is correct, the bootstrap wil continue. If all of them fail, the bootstrap process will be aborted as before.
  • JVMCBC-193: All internal RxJava Subjects that can be written from more than one thread are now properly serialized, ensuring that no updates are lost. This is especially important for the internal configuration stream to not loose any new configurations at any point in time or raise errors.

Couchbase Java Client 2.1.2 GA (3 April 2015)

Version 2.1.2 is the second bug fix release of the 2.1 series. It contains bug fixes and correctness improvements, especially related to durability requirements, streaming parsers and unstable cluster behavior.

New features and behavioral changes

This release contains the following enhancements:

  • JCBC-729: Decoding JSON long numbers has been made more performant because it does not go through a catch block on parsing an int value anymore.
  • JCBC-724: The environment configuration dump on startup now also includes the settings from the CouchbaseEnvironment, not just the CoreEnvironment.
  • JCBC-725: The N1QL metrics are now exposed as a strongly typed QueryMetrics object instead of the more generic JsonObject object. It provides direct method access to parameters like executionTime, resultSize and many more.
  • JCBC-735: The signature field returned by the server can be more than just a JsonObject, so the parsing has been modified and it is now exposed as a more generic Object type.
  • JVMCBC-168: Nagle's algorithm is now disabled by default, providing slightly better performance especially when lots of small packets are sent (for example, under get-heavy workloads).
  • JVMCBC-170: A hard minimum pool size for both the I/) and computation pools of 3 is now enforced to avoid resource starvation if either the operating system returns a very small CPU count or it is configured lower than the boundary. An INFO level message is logged as well.
  • JVMCBC-167: An environment configuration option has been added that allows you to disable the buffer pooling. While not recommended in general, it can be a helpful switch if there is an indication that the SDK is leaking memory. If pooling is disabled, a higher garbage collection pressure is expected. It can be disabled like this:
    CouchbaseEnvironment env = DefaultCouchbaseEnvironment
        .builder()
        .bufferPoolingEnabled(false)
        .build();
  • JCBC-554: A new experimental utility class is provided that greatly simplifies asynchronous retry logic. By using this class, you can specify in a builder-like fashion the type of exceptions to retry and the retry interval. The following example configures the application to retry BackpressureException exceptions at 10 millisecond intervals with a maximum of 8 retries allowed, but lets all other exceptions pass through without being retried:
    import static com.couchbase.client.java.util.retry.RetryBuilder.anyOf;
    
    Observable
        .from(ids)
        .flatMap(id -> bucket.upsert(JsonDocument.create(id, JsonObject.empty())))
        .retryWhen(anyOf(BackpressureException.class).delay(Delay.fixed(10, TimeUnit.MILLISECONDS)).max(8).build())
        .subscribe();

Fixed issues

This release fixes the following issues:

  • JVMCBC-171: The regression introduced in 2.1.1 has been fixed where the SDK tries to connect to localhost, even when the nodes are running on remote servers. The issue only showed up in the combination of SDK 2.1.1 with Couchbase Server 3.0.0, 3.0.1 (all platforms) and 3.0.2 (Windows).
  • JVMCBC-154, JVMCBC-163, JVMCBC-177: Multiple fixes for various rebalance and failure scenarios have been implemented in the core layer to react more deterministically. Especially parallel configuration pulling from various other nodes has been improved as well as continuous configuration polling after every failed reconnect attempt has been added.
  • JCBC-728, JCBC-731: The JsonLongDocument is now fully interoperable when used together on the mutation methods and the counter method. Previously, there were issues when a value written by the counter method was read by get and vice versa. In addition, the counter method now correctly uses the documented default value of 0 as advertised in the Javadocs.
  • JVMCBC-166, JVMCBC-175: Durability constraints (ReplicateTo, PersistTo) internals have been reworked and are now correct. In particular, they take the returned CAS value into account to make sure only success is reported when the document is overwritten on the replica. In addition, the active partition is always polled (even when not explicitly needed) to correctly determine concurrent modifications of the same document.
  • JCBC-723: When a touch operation does not find the document with the given ID, it now properly throws a DocumentDoesNotExistException. Previously, a generic exception was thrown that did not hold the semantical information needed to react properly on the application side.
  • JVMCBC-165: Thanks to a user contribution, the client now never adds line breaks on internal HTTP Basic auth requests against the configuration or view service (and in the future the N1QL service).
  • JVMCBC-176, JCBC-740: In the AsyncViewResponse errors are now exposed as an Observable because they can also come after the emitted rows in the response. The core layer has been modified to take this into account and the java binding reflects the change. The blocking API has not changed.
  • JVMCBC-172, JVMCBC-174: Two parsing issues have been fixed in the N1QL streaming parser. It now correctly decodes all possible JSON ways of a signature and also it properly waits for the actual last chunk of the query response before accepting a new request. This mitigates some errors and a form of a race condition that was showing up in continuous N1QL requests.
  • JVMCBC-173: Internal DCP compatibility has been restored which was broken in the last versions. It now uses a special form of a transient endpoint and works again.

Couchbase Java Client 2.1.1 GA (2 March 2015)

Version 2.1.1 is the first bug fix release of the 2.1 series. It contains bug fixes and correctness improvements, especially around PersistTo and ReplicateTo and query handling.

New features and behavioral changes

This release contains the following enhancements:

  • JVMCBC-136: A new underlying subject has been introduced that makes it possible that even if the user does not subscribe to an observable stream (in the view and query cases) the underlying buffers are freed and not accidentally leaked. While the developer is in charge to consume all data that has been asked for, this is a second line of defense that should prevent accidental leaking.

    To properly implement this, a contract has been established that needs to be followed. In general this should never come up, but if you run across them there is a good chance your application logic is doing something odd and you should reconsider it:

    • You need to subscribe to an observable in a specific amount of time. By default, this time is 2 seconds and can (but shouldn't) be modified through the environmental autoreleaseAfter setting. If you tune this to a high value, many buffers might end up in the old generation before being automatically cleaned up, and this will make your garbage collection profile worse.
    • You cannot subscribe more than once to the observable. If you want to do this, use the facilities provided by RxJava (like connect and cache) to do this.
    For now, these rules only apply to all observables exposed in the results from both view and query requests. All other operations are not affected by this, but keep in mind that requesting an operation and not consuming it can always lead to bad situations where data is not properly freed or cleaned up.
  • JCBC-717: The signature field is now exposed on a query result.
  • JCBC-707: We were able to reduce garbage collection (GC) pressure a little bit by not going through the intermediary String representation anymore when using the JsonDocument or the JsonArrayDocument.
  • JCBC-711, JCBC-709, JCBC-711, JCBC-706: In preparation for our upcoming Apache Spark integration, we had to make some classes serializable. This has no impact whatsoever on the interfaces, but is mentioned here in case someone also needs that functionality independently.
  • JCBC-703, JCBC-704, JVMCBC-146, JVMCBC-147, JVMCBC-149: The complete code path used with PersistTo or ReplicateTo overloads has been overhauled and optimized. It also now supports proper fail fast abort mechanisms when the fail fast retry strategy is used, properly channels all errors into a DurabilityException, and raises proper errors when the replica is not configured on the bucket. All in all, the current code is faster and easier to reason about, especially during failure scenarios.
  • JVMCBC-137: The SDK has been equipped with forward-compatible functionality to support a later release of Couchbase Server. Information about those features will be announced separately in the future.

Fixed issues

This release fixes the following issues:

  • JVMCBC-150, JVMCBC-148, JCBC-708: Locking failures are now properly distinguishable from temporary failures. The server does not in all cases send back the semantically correct error message, so the client does some additional guesswork to present the user an accurate error as possible. A new TemporaryLockFailureException has been added that will be thrown on double locking attempts as well as when unlock is called with an invalid cas. Refer to the Javadoc API reference about each method for the full details and error signatures.
  • JCBC-571: Certainly an edge case, but possible: when too many keys are passed into a ViewQuery the code now properly converts the underlying request from GET into POST to not risk HTTP errors from the view server.
  • JVMCBC-144: 2.1.0 introduced source JAR rewriting of dependencies so that breakpoints could be properly set on core-io, but a bug crept in with some of the Netty dependencies. This has been fixed and everything should be properly debuggable now.
  • JVMCBC-138: A fix is in place that prevents node connect/disconnect events from happening more than once, resulting in misleading but harmless double log messages.
  • JVMCBC-145: An important bug has been fixed where the response flags from an Observe call were not correctly parsed, leading to never completing PersistTo/ReplicateTo calls.
  • JCBC-719, JCBC-713: A small leak in the flush() method has been fixed and its internal implementation has been rewritten to be more compliant with RX best practices. Also, it now stores marker documents in all partitions instead of just one and polls them. This reduces the likelihood of prematurely returning to the user that the flush is complete when it isn't yet.
  • JVMCBC-141, JVMCBC-142, JVMCBC-143, JVMCBC-151, JVMCBC-152: Several bugs in the Query streaming handler have been fixed. Also, the keep-alive logic on the Query handler has been enhanced and now uses the correct endpoint on the server side.

Known issues

This release has the following known issues:

  • JVMCBC-154: When a failover is performed and there are operations in the pipeline, it could be that some of them are not properly cleaned up during the cancellation phase. The leak detector might report a leak, but it should not affect a long running application very much. This is going to be fixed in one of the next versions, but should not harm a production application in a blocking fashion.
  • JVMCBC-171: A regression has been introduced in 2.1.1 which manifests in a way that when connected to a 3.0 or higher remote cluster the SDK still wants to contact 127.0.0.1/localhost. Please upgrade to 2.1.2 if you hit the issue.

Couchbase Java Client 2.1.0 GA (3 February 2015)

Version 2.1.0 GA is the first stable release of the 2.1 series. It brings many enhancements and bug fixes over the 2.0 series (since 2.0.3).

New features and behavioral changes

This release contains the following enhancements:

  • Support for N1QL DP4: The query() methods have been reworked to provide closer integration with the new APIs available for N1QL DP4. In particular, the Statement has been introduced and there is no support for raw, parameterized and prepared queries. For more information about using N1QL, see Preview using N1QL DP4 from the Java SDK.
  • Support for spatial view queries: Support for spatial view queries has been added, which work very similar to the regular view queries. Note that at the time of release, the current server version still marks its support as experimental. Also, because the underlying response has changed since Couchbase Server 3.0, it is not backward compatible with the geospatial views on Couchbase Server 2.5 and earlier. For more information about spatial view queries, see Working with views.
  • JVMCBC-92: The poll interval for ReplicateTo and PersistTo can now be configured on the environment through the observeIntervalDelay setting. For information about the options and default settings, see Configuring the environment.
  • Pluggable request retry strategies: Because of popular demand, pluggable retry strategies have been added to the environment. The default strategy is best effort, which mirrors the 2.0 behavior of retrying the operation until it succeeds. This one now also takes the new maximum request lifetime into account.

    In addition, a fail-fast retry strategy has been added that immediately cancels the request if no suitable node in the cluster can be found where the request should be dispatched to. This can happen for a variety of reasons depending on the request type, but it provides a much closer feedback loop to the caller. It can work as a foundation for a user level circuit breaker or anyone who is willing to trade user level code (retry) for tighter control.

    Finally, these strategies are pluggable through a callback, so a custom advanced-user implementation could decide on a request-by-request basis whether it should be retried.

    Here is how to configure the fail-fast strategy:

    CouchbaseEnvironment env = DefaultCouchbaseEnvironment
        .builder()
        .retryStrategy(FailFastRetryStrategy.INSTANCE)
        .build();
  • JVMCBC-134: A configurable maximum request lifetime has been added to the environment, which is used by the best effort retry strategy to determine when it is time to not retry the request anymore. This has been added to avoid operations circling around infinitely because of either a bug or a not stabilizing cluster state. For information about the options and default settings, see Configuring the environment.
  • JVMCBC-21: Keepalive heartbeats are now available again in the Java SDK. By default, every endpoint (socket) sends a heartbeat message to the remote server to keep the connection from going completely idle, which can cause side effects that firewalls shut them down proactively. The default value is set to 30 seconds, but it can be configured on the environment if needed. For information about the options and default settings, see Configuring the environment.
  • Subscribable event bus: an event bus has been added to the environment where the SDK pushes different kinds of events through it. Applications can subscribe to the event bus to receive those notifications and react if they want to. Currently, bucket open or close and node connect or disconnect events are published, but we plan to add much more in the future (especially in the area around profiling and monitoring for enhanced field serviceability).

    Here is a simple example that shows how to subscribe and print certain system events:

    couchbaseEnvironment.eventBus().get().subscribe(System.out::println);

    The example returns data similar to this:

    NodeConnectedEvent{node=localhost/127.0.0.1}
    BucketOpenedEvent{name='beer-sample'}
    BucketClosedEvent{name='beer-sample'}
    NodeDisconnectedEvent{node=localhost/127.0.0.1}
  • Bootstrap through DNS SRV: It is now possible to fetch the list of bootstrap nodes through a DNS SRV record. This allows system administrators to centralize their bootstrap node list configuration in a very easy manner. It needs to be enabled on the environment to make it work. For more information, see Managing connections.
  • JCBC-539: A stateful helper class called NodeLocatorHelper has been introduced. The class provides a cluster-aware way to see which document IDs map to which node in the cluster. Note that this functionality is mainly interesting for users who want to log and/or pass information to different systems for a variety of reasons. One possible scenario is to enrich user level circuit breaker functionality.
  • JCBC-542: The API now throws semantically correct exceptions on nearly all operations affecting the key-value service. This includes exceptions such as tmpfail or out of memory. To get the full list of exceptions thrown by each method, refer to the API Reference.
  • JVMCBC-92: The poll interval for ReplicateTo and PersistTo can now be configured on the environment through the observeIntervalDelay setting. For information about the options and default settings, see Configuring the environment.
  • JVMCBC-129: The delay between reconnect attempts is now configurable. For information about the options and default settings, see Configuring the environment.
  • JVMCBC-83, JVMCBC-84, JVMCBC-128: We've optimized the hot code path quite a bit and you should now see lower latency and higher throughput on most of the workloads. Also, we slightly reduced the allocation rate on the shared buffer pool.
  • JVMCBC-93: The internal pooling of endpoints has been refactored order minimize the time the SDK hooks onto channels. In particular, sockets to port 8091 are now immediately closed if not needed anymore.
  • JCBC-633: The ViewResult now implements the Iterator interface, which allows iterating over the ViewRows with a for-loop instead of having to use the iterator explicitly.
  • JCBC-628: Both JsonArray and JsonObject can now be constructed from raw JSON literals through new factory methods (see the fromJson methods for more details).
  • JVMCBC-127: Similar to spymemcached in the 1.x SDK series, the 2.1 SDK now also sets the opaque identifier on the binary requests in order to make it easier to correlate requests and responses with tools like tcpdump.
  • JCBC-698: The disconnect timeout has been increased to 25 seconds from the quite short 5 seconds by default. Also, the Bucket#close() method now uses this timeout instead of the incorrect management one.
  • JVMCBC-66: Great news for everyone who wants to debug the core-io repackaged dependencies. From now on we also include the repackaged dependencies in the source JAR of the core, which means that IDEs can pick up the full sources and you can set breakpoints in all places.
  • JCBC-689: When an incorrect password is used together with the ClusterManager, it now throws a proper exception (InvalidPasswordException) instead of a cryptic error message failing the observable.

Fixed issues

This release fixes the following issues:

  • JCBC-669: A bug was fixed on both the JsonArray and JsonValue where when toMap or toList was used it did not conver the contained maps and lists. Now proper deep conversion is happening automatically.
  • JVMCBC-122, :JVMCBC-123, JCBC-682, JCBC-684: ByteBuffer leaks have been fixed in various places, especially when on a get request the document is not found, as well as during Observe calls and in the BucketManager.
  • JVMCBC-126: Several IndexOutOfBoundsExceptions in the streaming parsers for both View and Query have been fixed. The code is now more resilient to specific arriving chunk boundaries.

Known issues

This release has the following known issues:

  • JVMCBC-136: Unconsumed ByteBuf Observables are not properly released and will leak memory. To avoid this situation, just make sure to consume all observables that you request from the SDK. In the future, we are going to improve the situation with auto release buffers if no one has subscribed after a specific amount of time.
  • JVMCBC-138: On a multinode cluster, the SDK will report multiple connect and disconnect messages to some nodes in the cluster on startup. This is not harmful, just confusing, and will be resolved in a later bug fix release.
  • JVMCBC-154: When a failover is performed and there are operations in the pipeline, it could be that some of them are not properly cleaned up during the cancellation phase. The leak detector might report a leak, but it should not affect a long running application very much. This is going to be fixed in one of the next versions, but should not harm a production application in a blocking fashion.