[RELEASE] Java driver 3.1.0

[Olivier Michallat]

We've just released 3.1.0. 

It includes:

- all patches from previous 3.0.x releases;

- a few 2.1.10 tickets that hadn't made it to the 3.x series yet (because they happened after 3.0.0 and were considered more than simple patches);

- some brand new 3.1-specific features.

This version introduces an important change in the default retry behavior: statements that are not idempotent are not always retried automatically anymore.

- prior to 2.1.10, idempotence was not considered for retries. This exposed applications to the risk of applying a non-idempotent statement twice (counter increment, list append...), or to more subtle bugs with lightweight transactions (see JAVA-819).

- in 2.1.10 / 3.0.x, we introduced IdempotenceAwareRetryPolicy, which considers the Statement#isIdempotent() flag in the retry decision process. However, for consistency with previous versions, this policy was not enabled by default (in particular because statements are non-idempotent by default, and we didn't want applications to suddenly stop retrying

queries that were retried before).

- in 3.1.0, the default is now to not retry after a write timeout or request error if the statement is not idempotent. This is handled internally, the retry policy methods are not even invoked in those cases (and therefore IdempotenceAwareRetryPolicy has been deprecated). See the manual section about retries for more information.

In practice, here's what upgrading to 3.1.0 means for you:

- if you were already handling idempotence in your application, there won't be any change, but you can stop wrapping your retry policy with IdempotenceAwareRetryPolicy;

- otherwise, you might want to review how your code positions the setIdempotent flag on statements. In most cases the driver can't compute in automatically (because it doesn't parse query strings), so it takes a conservative approach and sets it to false by default. If you know the query is idempotent, you should set it to true manually. See the query idempotence section of the manual.

The driver logs a warning the first time it ignores a non-idempotent request; this warning will be removed in version 3.2.0.

Here is the full changelog for 3.1.0:

- [new feature] JAVA-1153: Add PER PARTITION LIMIT to Select QueryBuilder.

- [improvement] JAVA-743: Add JSON support to QueryBuilder.

- [improvement] JAVA-1233: Update HdrHistogram to 2.1.9.

- [improvement] JAVA-1233: Update Snappy to 1.1.2.6.

- [bug] JAVA-1161: Preserve full time zone info in ZonedDateTimeCodec and DateTimeCodec.

- [new feature] JAVA-1157: Allow asynchronous paging of Mapper Result.

- [improvement] JAVA-1212: Don't retry non-idempotent statements by default.

- [improvement] JAVA-1192: Make EventDebouncer settings updatable at runtime.

- [new feature] JAVA-541: Add polymorphism support to object mapper.

- [new feature] JAVA-636: Allow @Column annotations on getters/setters as well as fields.

- [new feature] JAVA-984: Allow non-void setters in object mapping.

- [new feature] JAVA-1055: Add ErrorAware load balancing policy.

Merged from 3.0.x branch:

- [bug] JAVA-1179: Request objects should be copied when executed.

- [improvement] JAVA-1182: Throw error when synchronous call made on I/O thread.

- [bug] JAVA-1184: Unwrap StatementWrappers when extracting column definitions.

- [bug] JAVA-1132: Executing bound statement with no variables results in exception with protocol v1.

- [improvement] JAVA-1040: SimpleStatement parameters support in QueryLogger.

- [improvement] JAVA-1151: Fail fast if HdrHistogram is not in the classpath.

- [improvement] JAVA-1154: Allow individual Statement to cancel the read timeout.

- [bug] JAVA-1074: Fix documentation around default timestamp generator.

- [improvement] JAVA-1109: Document SSLOptions changes in upgrade guide.

- [improvement] JAVA-1065: Add method to create token from partition key values.

- [improvement] JAVA-1136: Enable JDK signature check in module driver-extras.

- [improvement] JAVA-866: Support tuple notation in QueryBuilder.eq/in.

- [bug] JAVA-1140: Use same connection to check for schema agreement after a DDL query.

- [improvement] JAVA-1113: Support Cassandra 3.4 LIKE operator in QueryBuilder.

- [improvement] JAVA-1086: Support Cassandra 3.2 CAST function in QueryBuilder.

- [bug] JAVA-1095: Check protocol version for custom payload before sending the query.

- [improvement] JAVA-1133: Add OSGi headers to cassandra-driver-extras.

- [bug] JAVA-1137: Incorrect string returned by DataType.asFunctionParameterString() for collections and tuples.

- [bug] JAVA-1046: (Dynamic)CompositeTypes need to be parsed as string literal, not blob.

- [improvement] JAVA-1164: Clarify documentation on Host.listenAddress and broadcastAddress.

- [improvement] JAVA-1171: Add Host method to determine if DSE Graph is enabled.

- [improvement] JAVA-1069: Bootstrap driver-examples module.

- [documentation] JAVA-1150: Add example and FAQ entry about ByteBuffer/BLOB.

- [improvement] JAVA-1011: Expose PoolingOptions default values.

- [improvement] JAVA-630: Don't process DOWN events for nodes that have active connections.

- [improvement] JAVA-851: Improve UUIDs javadoc with regard to user-provided timestamps.

- [improvement] JAVA-979: Update javadoc for RegularStatement toString() and getQueryString() to indicate that consistency level and other parameters are not maintained in the query string.

- [bug] JAVA-1068: Unwrap StatementWrappers when hashing the paging state.

- [improvement] JAVA-1021: Improve error message when connect() is called with an invalid keyspace name.

- [improvement] JAVA-879: Mapper.map() accepts mapper-generated and user queries.

- [bug] JAVA-1100: Exception when connecting with shaded java driver in OSGI

- [bug] JAVA-1064: getTable create statement doesn't properly handle quotes in primary key.

- [bug] JAVA-1089: Set LWT made from BuiltStatements to non-idempotent.

- [improvement] JAVA-923: Position idempotent flag on object mapper queries.

- [bug] JAVA-1070: The Mapper should not prepare queries synchronously.

- [new feature] JAVA-982: Introduce new method ConsistencyLevel.isSerial().

- [bug] JAVA-764: Retry with the normal consistency level (not the serial one) when a write times out on the Paxos phase.

- [improvement] JAVA-852: Ignore peers with null entries during discovery.

- [bug] JAVA-1005: DowngradingConsistencyRetryPolicy does not work with EACH_QUORUM when 1 DC is down.

- [bug] JAVA-1002: Avoid deadlock when re-preparing a statement on other hosts.

- [bug] JAVA-1072: Ensure defunct connections are properly evicted from the pool.

- [bug] JAVA-1152: Fix NPE at ControlConnection.refreshNodeListAndTokenMap().

Merged from 2.1 branch:

- [improvement] JAVA-1038: Fetch node info by rpc_address if its broadcast_address is not in system.peers.

- [improvement] JAVA-888: Add cluster-wide percentile tracker.

- [improvement] JAVA-963: Automatically register PercentileTracker from components that use it.

- [new feature] JAVA-1019: SchemaBuilder support for CREATE/ALTER/DROP KEYSPACE.

- [bug] JAVA-727: Allow monotonic timestamp generators to drift in the future + use microsecond precision when possible.

- [improvement] JAVA-444: Add Java process information to UUIDs.makeNode() hash.

As usual, the driver is available from Maven and as a binary tarball; see the Getting the driver section in our documentation.

The Javadocs and documentation are available from the DataStax website.

--

The Java driver team