Upgrade guide¶

3.6.0¶

1. ConsistencyLevel.LOCAL_SERIAL.isDCLocal() now returns true. In driver code, isDCLocal() is only used when evaluating a Statement’s ConsistencyLevel (which does not include Serial CLs), but as a matter of correctness this was updated.

2. ReadFailureException and WriteFailureException are now surfaced to RetryPolicy.onRequestError. Consider updating custom RetryPolicy implementations to account for this. In the general case, we recommend using RetryDecision.rethrow(), see JAVA-1944.

3.5.0¶

1. The DowngradingConsistencyRetryPolicy is now deprecated, see JAVA-1752. It will also be removed in the next major release of the driver (4.0.0), see JAVA-1376.

   The main motivation is the agreement that this policy’s behavior should be the application’s concern, not the driver’s.

   We recognize that there are use cases where downgrading is good – for instance, a dashboard application would present the latest information by reading at QUORUM, but it’s acceptable for it to display stale information by reading at ONE sometimes.

   But APIs provided by the driver should instead encourage idiomatic use of a distributed system like Apache Cassandra, and a downgrading policy works against this. It suggests that an anti-pattern such as “try to read at QUORUM, but fall back to ONE if that fails” is a good idea in general use cases, when in reality it provides no better consistency guarantees than working directly at ONE, but with higher latencies.

   We therefore urge users to carefully choose upfront the consistency level that works best for their use cases, and should they decide that the downgrading behavior of DowngradingConsistencyRetryPolicy remains a good fit for certain use cases, they will now have to implement this logic themselves, either at application level, or alternatively at driver level, by rolling out their own downgrading retry policy.

   To help users migrate existing applications that rely on DowngradingConsistencyRetryPolicy, see this online example that illustrates how to implement a downgrading logic at application level.

1. The TokenAwarePolicy now has a new constructor that takes a ReplicaOrdering argument, see JAVA-1448.

   One of the advantages of this feature is the new NEUTRAL ordering strategy, which honors its child policy’s ordering, i.e., replicas are returned in the same relative order as in the child policy’s query plan.

   For example, if the child policy returns the plan [A, B, C, D], and the replicas for the query being routed are [D, A, B], then the token aware policy would return the plan [A, B, D, C].

   As a consequence, the constructor taking a boolean parameter shuffleReplicas is now deprecated and will be removed in the next major release.

3.4.0¶

QueryBuilder methods in, lt, lte, eq, gt, and gte now accept Iterable as input rather than just List. This should have no impact unless you were accessing these methods using reflection in which case you need to account for these new parameter types.

3.3.1¶

Speculative executions can now be scheduled without delay: if SpeculativeExecutionPlan.nextExecution() returns 0, the next execution will be fired immediately. This allows aggressive policies that hit multiple replicas right away, in order to get the fastest response possible. Note that this may break existing policies that used 0 to mean “no execution”; make sure you use a negative value instead.

3.2.0¶

The SSLOptions interface is now deprecated in favor of RemoteEndpointAwareSSLOptions. Similarly, the two existing implementations of that interface, JdkSSLOptions and NettySSLOptions, are now deprecated in favor of RemoteEndpointAwareJdkSSLOptions and RemoteEndpointAwareNettySSLOptions respectively (see JAVA-1364).

In 3.1.0, the driver would log a warning the first time it would skip a retry for a non-idempotent request; this warning has now been removed as users should now have adjusted their applications accordingly.

The caseSensitive field on @Column and @Field annotation now only applies to the name field on the annotation and not the name of the variable / method itself. If you were previously depending on the name of the field, you should add a name field to the annotation, i.e.: @Column(name="userName", caseSensitive=true).

3.1.0¶

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() 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.

3.0.4¶

The connection pool is now fully non-blocking (JAVA-893), which greatly improves asynchronous programming:

• Session.executeAsync won’t ever block the user thread anymore;

• you can now safely run async queries on a session connected to a keyspace.

This new implementation brings a couple of changes:

• pool saturation is no longer handled by a timeout, but instead by a bounded queue. As a consequence, PoolingOptions.setPoolTimeoutMillis has been deprecated, and replaced by setMaxQueueSize;

• a saturated pool will now throw BusyPoolException instead of TimeoutException (note that this exception is not rethrown directly to the client, but wrapped in NoHostAvailableException.getErrors()).

3.0.0¶

This version brings parity with Cassandra 2.2 and 3.0.

It is not binary compatible with the driver’s 2.1 branch. The main changes were introduced by the custom codecs feature (see below). We’ve also seized the opportunity to remove code that was deprecated in 2.1.

1. The default consistency level in QueryOptions is now LOCAL_ONE.

2. Custom codecs (JAVA-721) introduce several breaking changes and also modify a few runtime behaviors.

   Here is a detailed list of breaking API changes:

   • TypeCodec was package-private before and is now public.

   • DataType has no more references to TypeCodec, so methods that dealt with serialization and deserialization of data types have been removed:

     • ByteBuffer serialize(Object value, ProtocolVersion protocolVersion)

     • ByteBuffer serializeValue(Object value, ProtocolVersion protocolVersion)

     • Object deserialize(ByteBuffer bytes, ProtocolVersion protocolVersion)

     • Object deserialize(ByteBuffer bytes, int protocolVersion)

     • Object parse(String value)

     • String format(Object value)

     • Class<?> asJavaClass()

     These methods must now be invoked on TypeCodec directly. To resolve the TypeCodec instance for a particular data type, use CodecRegistry#codecFor.

   • GettableByIndexData (affects Row, BoundStatement, TupleValue and UDTValue). The following public methods were added:

     • <T> T get(int i, Class<T> targetClass)

     • <T> T get(int i, TypeToken<T> targetType)

     • <T> T get(int i, TypeCodec<T> codec)

   • GettableByNameData (affects Row, BoundStatement and UDTValue). The following public methods were added:

     • <T> T get(String name, Class<T> targetClass)

     • <T> T get(String name, TypeToken<T> targetType)

     • <T> T get(String name, TypeCodec<T> codec)

   • SettableByIndexData (affects Row, BoundStatement, TupleValue and UDTValue). The following public methods were added:

     • <V> T set(int i, V v, Class<V> targetClass)

     • <V> T set(int i, V v, TypeToken<V> targetType)

     • <V> T set(int i, V v, TypeCodec<V> codec)

   • SettableByNameData (affects Row, BoundStatement and UDTValue). The following public methods were added:

     • <V> T set(String name, V v, Class<V> targetClass)

     • <V> T set(String name, V v, TypeToken<V> targetType)

     • <V> T set(String name, V v, TypeCodec<V> codec)

   • Statement. The following public methods were modified:

     • getRoutingKey(ProtocolVersion, CodecRegistry): both parameters added.

   • RegularStatement. The following public methods were modified:

     • getValues(ProtocolVersion, CodecRegistry): second parameter added.

     • getQueryString(CodecRegistry) and hasValues(CodecRegistry): parameter added. No-arg versions are still present and use the default codec registry; refer to the Javadocs for guidance on which version to use.

   • PreparedStatement. The following public method was added:

     • CodecRegistry getCodecRegistry().

   • TupleType. The following public method was deleted:

     • TupleType of(DataType... types); users should now use Metadata.newTupleType(DataType...).

   The driver runtime behavior changes in the following situations:

   * By default, the driver now returns _mutable_, _non thread-safe_ instances for CQL collection types; This affects methods `getList`, `getSet`, `getMap`, `getObject` and `get` for all instances of `GettableByIndexData` and `GettableByNameData` (`Row`, `BoundStatement`, `TupleValue` and `UDTValue`) * `RuntimeException`s thrown during serialization or deserialization might not be the same ones as before, due to the newly-introduced `CodecNotFoundException` and to the dynamic nature of codec search introduced by JAVA-721. * `TypeCodec.format(Object)` now returns the CQL keyword `"NULL"` instead of a `null` reference for `null` inputs.

3. The driver now depends on Guava 16.0.1 (instead of 14.0.1). This update has been mainly motivated by Guava’s Issue #1635, which affects TypeToken, and hence all TypeCodec implementations handling parameterized types.

4. UDTMapper (the type previously used to convert @UDT-annotated classes to their CQL counterpart) was removed, as well as the corresponding method MappingManager#udtMapper.

   The mapper now uses custom codecs to convert UDTs. See more explanations here.

5. All methods that took the protocol version as an int or assumed a default version have been removed (they were already deprecated in 2.1):

   • AbstractGettableData(int)

   • Cluster.Builder#withProtocolVersion(int)

   • in ProtocolOptions:

     • NEWEST_SUPPORTED_PROTOCOL_VERSION (replaced by ProtocolVersion#NEWEST_SUPPORTED)

     • int getProtocolVersion()

   There are now variants of these methods using the ProtocolVersion enum. In addition, ProtocolOptions#getProtocolVersionEnum has been renamed to ProtocolOptions#getProtocolVersion.

6. All methods related to the “suspected” host state have been removed (they had been deprecated in 2.1.6 when the suspicion mechanism was removed):

   • Host.StateListener#onSuspected() (was inherited by LoadBalancingPolicy)

   • Host#getInitialReconnectionAttemptFuture()

7. PoolingOptions#setMinSimultaneousRequestsPerConnectionThreshold(HostDistance, int) has been removed. The new connection pool resizing algorithm introduced by JAVA-419 does not need this threshold anymore.

8. AddressTranslater has been renamed to AddressTranslator. All related methods and classes have also been renamed.

   In addition, the close() method has been pulled up into AddressTranslator, and CloseableAddressTranslator has been removed. Existing third-party AddressTranslator implementations only need to add an empty close() method.

9. The close() method has been pulled up into LoadBalancingPolicy, and CloseableLoadBalancingPolicy has been removed. Existing third-party LoadBalancingPolicy implementations only need to add an empty close() method.

10. All pluggable components now have callbacks to detect when they get associated with a Cluster instance:

    • ReconnectionPolicy, RetryPolicy, AddressTranslator, and TimestampGenerator:

      • init(Cluster)

      • close()

    • Host.StateListener and LatencyTracker:

      • onRegister(Cluster)

      • onUnregister(Cluster)

    This gives these components the opportunity to perform initialization / cleanup tasks. Existing third-party implementations only need to add empty methods.

11. LoadBalancingPolicy does not extend Host.StateListener anymore: callback methods (onUp, onDown, etc.) have been duplicated. This is unlikely to affect clients.

12. Client-side timestamp generation is now the default (provided that native protocol v3 or higher is in use). The generator used is AtomicMonotonicTimestampGenerator.

13. If a DNS name resolves to multiple A-records, Cluster.Builder#addContactPoint(String) will now use all of these addresses as contact points. This gives you the possibility of maintaining contact points in DNS configuration, and having a single, static contact point in your Java code.

14. The following methods were added for Custom payloads:

    • in PreparedStatement: getIncomingPayload(), getOutgoingPayload() and setOutgoingPayload(Map<String,ByteBuffer>)

    • AbstractSession#prepareAsync(String, Map<String,ByteBuffer>)

    Also, note that AbstractSession#prepareAsync(Statement) does not call AbstractSession#prepareAsync(String) anymore, they now both delegate to a protected method.

    This breaks binary compatibility for these two classes; if you have custom implementations, you will have to adapt them accordingly.

15. Getters and setters have been added to “data-container” classes for new CQL types:

    • getByte/setByte for the TINYINT type

    • getShort/setShort for the SMALLINT type

    • getTime/setTime for the TIME type

    • getDate/setDate for the DATE type

    The methods for the TIMESTAMP CQL type have been renamed to getTimestamp and setTimestamp.

    This affects Row, BoundStatement, TupleValue and UDTValue.

16. New exception types have been added to handle additional server-side errors introduced in Cassandra 2.2:

    • ReadFailureException

    • WriteFailureException

    • FunctionExecutionException

    This is not a breaking change since all driver exceptions are unchecked; but clients might decide to handle these errors in a specific way.

    In addition, QueryTimeoutException has been renamed to QueryExecutionException (this is an intermediary class in our exception hierarchy, it now has new child classes that are not related to timeouts).

17. ResultSet#fetchMoreResults() now returns a ListenableFuture<ResultSet>. This makes the API more friendly if you chain transformations on an async query to process all pages (see AsyncResultSetTest in the sources for an example).

18. Frozen annotations in the mapper are no longer checked at runtime (see JAVA-843 for more explanations). So they become purely informational at this stage. However it is a good idea to keep using these annotations and make sure they match the schema, in anticipation for the schema generation features that will be added in a future version.

19. AsyncInitSession has been removed, initAsync() is now part of the Session interface (the only purpose of the extra interface was to preserve binary compatibility on the 2.1 branch).

20. TableMetadata.Options has been made a top-level class and renamed to TableOptionsMetadata. It is now also used by MaterializedViewMetadata.

21. The mapper annotation @Enumerated has been removed, users should now use the newly-introduced driver-extras module to get automatic enum-to-CQL mappings. Two new codecs provide the same functionality: EnumOrdinalCodec and EnumNameCodec:

    enum Foo {...}
    enum Bar {...}
    
    // register the appropriate codecs
    CodecRegistry.DEFAULT_INSTANCE
        .register(new EnumOrdinalCodec<Foo>(Foo.class))
        .register(new EnumNameCodec<Bar>(Bar.class))
    
    // the following mappings are handled out-of-the-box
    @Table
    public class MyPojo {
        private Foo foo;
        private List<Bar> bars;
        ...
    }
    

22. The interface IdempotenceAwarePreparedStatement has been removed and now the PreparedStatement interface exposes 2 new methods, setIdempotent(Boolean) and isIdempotent().

23. RetryPolicy and ExtendedRetryPolicy (introduced in 2.1.10) were merged together; as a consequence, RetryPolicy now has one more method: onRequestError; see JAVA-819 for more information. Furthermore, FallthroughRetryPolicy now returns RetryDecision.rethrow() when onRequestError is called.

24. DseAuthProvider has been deprecated and is now replaced by DseGSSAPIAuthProvider for Kerberos authentication. DsePlainTextAuthProvider has been introduced to handle plain text authentication with the DseAuthenticator.

25. The constructor of DCAwareRoundRobinPolicy is not accessible anymore. You should use DCAwareRoundRobinPolicy#builder() to create new instances.

26. ColumnMetadata.getTable() has been renamed to ColumnMetadata.getParent(). Also, its return type is now AbstractTableMetadata which can be either a TableMetadata object or a MaterializedViewMetadata object. This change is motivated by the fact that a column can now belong to a table or a materialized view.

27. ColumnMetadata.getIndex() has been removed. This is due to the fact that secondary indexes have been completely redesigned in Cassandra 3.0, and the former one-to-one relationship between a column and its index has been replaced with a one-to-many relationship between a table and its indexes. This is reflected in the driver’s API by the new methods TableMetadata.getIndexes() and TableMetadata.getIndex(String name). See CASSANDRA-9459 and and JAVA-1008 for more details. Unfortunately, there is no easy way to recover the functionality provided by the deleted method, even for Cassandra versions <= 3.0.

28. IndexMetadata is now a top-level class and its structure has been deeply modified. Again, this is due to the fact that secondary indexes have been completely redesigned in Cassandra 3.0.

29. SSLOptions has been refactored to allow the option to choose between JDK and Netty-based SSL implementations. See JAVA-841 and the SSL documentation for more details.

2.1.8¶

2.1.8 is binary-compatible with 2.1.7 but introduces a small change in the driver’s behavior:

1. The list of contact points provided at startup is now shuffled before trying to open the control connection, so that multiple clients with the same contact points don’t all pick the same control host. As a result, you can’t assume that the driver will try contact points in a deterministic order. In particular, if you use the DCAwareRoundRobinPolicy without specifying a primary datacenter name, make sure that you only provide local hosts as contact points.

2.1.7¶

This version brings a few changes in the driver’s behavior; none of them break binary compatibility.

1. The DefaultRetryPolicy’s behaviour has changed in the case of an Unavailable exception received from a request. The new behaviour will cause the driver to process a Retry on a different node at most once, otherwise an exception will be thrown. This change makes sense in the case where the node tried initially for the request happens to be isolated from the rest of the cluster (e.g. because of a network partition) but can still answer to the client normally. In this case, trying another node has a chance of success. The previous behaviour was to always throw an exception.

2. The following properties in PoolingOptions were renamed:

   • MaxSimultaneousRequestsPerConnectionThreshold to NewConnectionThreshold

   • MaxSimultaneousRequestsPerHostThreshold to MaxRequestsPerConnection

   The old getters/setters were deprecated, but they delegate to the new ones.

   Also, note that the connection pool for protocol v3 can now be configured to use multiple connections. See this page for more information.

3. MappingManager(Session) will now force the initialization of the Session if needed. This is a change from 2.1.6, where if you gave it an uninitialized session (created with Cluster#newSession() instead of Cluster#connect()), it would only get initialized on the first request.

   If this is a problem for you, MappingManager(Session, ProtocolVersion) preserves the previous behavior (see the API docs for more details).

4. A BuiltStatement is now considered non-idempotent whenever a fcall() or raw() is used to build a value to be inserted in the database. If you know that the CQL functions or expressions are safe, use setIdempotent(true) on the statement.

2.1.6¶

See 2.0.10.

2.1.2¶

2.1.2 brings important internal changes with native protocol v3 support, but the impact on the public API has been kept as low as possible.

2.1.1¶

2.1.0¶

2.0.11¶

2.0.11 preserves binary compatibility with previous versions. There are a few changes in the driver’s behavior:

1. The DefaultRetryPolicy’s behaviour has changed in the case of an Unavailable exception received from a request. The new behaviour will cause the driver to process a Retry on a different node at most once, otherwise an exception will be thrown. This change makes sense in the case where the node tried initially for the request happens to be isolated from the rest of the cluster (e.g. because of a network partition) but can still answer to the client normally. In this case, trying another node has a chance of success. The previous behaviour was to always throw an exception.

2. A BuiltStatement is now considered non-idempotent whenever a fcall() or raw() is used to build a value to be inserted in the database. If you know that the CQL functions or expressions are safe, use setIdempotent(true) on the statement.

3. The list of contact points provided at startup is now shuffled before trying to open the control connection, so that multiple clients with the same contact points don’t all pick the same control host. As a result, you can’t assume that the driver will try contact points in a deterministic order. In particular, if you use the DCAwareRoundRobinPolicy without specifying a primary datacenter name, make sure that you only provide local hosts as contact points.

2.0.x to 2.0.10¶

We try to avoid breaking changes within a branch (2.0.x to 2.0.y), but 2.0.10 saw a lot of new features and internal improvements. There is one breaking change:

1. LatencyTracker#update now has a different signature and takes two new parameters: the statement that has been executed (never null), and the exception thrown while executing the query (or null, if the query executed successfully). Existing implementations of this interface, once upgraded to the new method signature, should continue to work as before.

The following might also be of interest:

1. SocketOptions#getTcpNoDelay() is now TRUE by default (it was previously undefined). This reflects the new behavior of Netty (which was upgraded from version 3.9.0 to 4.0.27): TCP_NODELAY is now turned on by default, instead of depending on the OS default like in previous versions.

2. Netty is not shaded anymore in the default Maven artifact. However we publish a shaded artifact under a different classifier.

3. The internal initialization sequence of the Cluster object has been slightly changed: some fields that were previously initialized in the constructor are now set when the init() method is called. In particular, Cluster#getMetrics() will return null until the cluster is initialized.

1.0 to 2.0¶

We used the opportunity of a major version bump to incorporate your feedback and improve the API, to fix a number of inconsistencies and remove cruft. Unfortunately this means there are some breaking changes, but the new API should be both simpler and more complete.

The following describes the changes for 2.0 that are breaking changes of the 1.0 API. For ease of use, we distinguish two categories of API changes: the “main” ones and the “other” ones.

The “main” API changes are the ones that are either likely to affect most upgraded apps or are incompatible changes that, even if minor, will not be detected at compile time. Upgraders are highly encouraged to check this list of “main” changes while upgrading their application to 2.0 (even though most applications are likely to be affected by only a handful of changes).

The “other” list is, well, other changes: those that are likely to affect a minor number of applications and will be detected by compile time errors anyway. It is ok to skip those initially and only come back to them if you have trouble compiling your application after an upgrade.