Upgrade guide

The purpose of this guide is to detail changes made by successive versions of the Java driver.

1.8.0

1. This version now supports Apache TinkerPop 3.4.0. Because of breaking changes in TinkerPop, at least TinkerPop 3.2.4 is required when using the dse-java-driver-graph module.

1.7.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.

1.6.5

1. The DowngradingConsistencyRetryPolicy is now deprecated, see JAVA-1752. It will also be removed in the next major release of the driver (2.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 DSE, 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.

2. 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.

1.5.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.

1.4.0

GraphResultSet#getAvailableWithoutFetching() is now considered deprecated as it may return incorrect values in cases where the server returns bulking information (such as in the barrier() step). For a reliable count, use GraphResultSet#all().

1.3.0

The driver will now offer the possibility to use the GraphSON2 sub protocol for the Graph driver with string Gremlin queries (JAVA-1329).

The sub protocol used by default stays GraphSON1. However GraphSON1 may cause problems of type conversion happening during the serialization of the query to the DSE Graph server, or the deserialization of the responses back from a string Gremlin query. GraphSON2 offers better support for the complex data types handled by DSE Graph (for an exhaustive list of the data types supported by the driver and DSE Graph see this documentation.

Activating GraphSON2 can be done via GraphOptions#setGraphSubprotocol(GraphProtocol) however it may bring significant behavioral change at runtime. Some GraphNode methods allow to extract nested fields from a result in an agnostic manner such as the GraphNode#isValue(), GraphNode#isObject(), GraphNode#isArray(), … methods. The behaviour of these methods may change as a side effect of using GraphSON2, since it is a more strictly typed sub protocol:

• The isObject() method will return false whenever the property to retrieve is not a Map. With GraphSON1 this method would return true for any Graph object such as mainly Vertex, Edge, VertexProperty,Property and Path.

• The isValue() method will return true for any Graph data type contained in the GraphNode that is not a Map or a List, including Graph types such as mainly Vertex, Edge, VertexProperty,Property and Path. With GraphSON1 this method would return false for the Graph types cited previously.

Using GraphSON2 shouldn’t have an impact at runtime with regards to the GraphNode#asXXXX() methods if the user is already following the data type compatibilities guide in association with their DSE Graph schema.

It is generally recommended to switch to GraphSON2 as it brings more consistent support for complex data types in the Graph driver and will be activated by default in the next major version (i.e. DSE Java driver 2.0).

1.2.0

The coordinates of the driver artifacts have changed:

• core DSE driver: com.datastax.dse:dse-java-driver-core
• Apache Tinkerpop integration: com.datastax.dse:dse-java-driver-graph

DSE-specific versions of the mapper and extras are now published:

• com.datastax.dse:dse-java-driver-mapping
• com.datastax.dse:dse-java-driver-extras

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 1.1, 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).

cassandra-driver-dse-* to dse-driver-1.0.0

For previous versions of DSE, the driver extensions were published as a module of the core driver, under the coordinates com.datastax.cassandra:cassandra-driver-dse. Starting with DSE 5, they become a standalone project: com.datastax.cassandra:dse-driver. By separating the two projects, our goal is to allow separate lifecycles (for example, we can release a patch version only for dse-driver if no core changes are needed).

In addition, we are switching to semantic versioning for the new project: each release number will now clearly express the nature of the changes it contains (patches, new features or breaking changes). Since version numbers are strictly codified by semver, following DSE server versioning is not possible; to make it clear that the two versioning schemes are independent, we start the new driver project at 1.0.0.

From an API perspective, dse-driver brings the following changes:

Dedicated cluster and session wrappers

The DSE driver now uses dedicated extensions of the core driver types: DseCluster and DseSession. Their main advantage is to allow direct execution of graph statements.

See the root section of the manual for more details.

Retries of idempotent statements

Historically, the driver retried failed queries indiscriminately. In recent versions of the core driver, the Statement#isIdempotent flag was introduced, to mark statements that are unsafe to retry when there is a chance that they might have been applied already by a replica. To keep backward compatibility with previous versions, the driver still retried these statements by default, and you had to configure a special retry policy to avoid retrying them.

Starting with dse-driver-1.0.0, it is now the default behavior to not retry non-idempotent statements on write timeouts or request errors. To help with the transition, a warning will be logged when the driver initializes, and the first time a retry is aborted because of the isIdempotent flag (this warning will be removed in a future version).

Note that the driver does not position the isIdempotent flag automatically. Because it does not parse query strings, it cannot determine if a particular query is idempotent or not. Therefore it takes a cautious approach and marks all statements as non-idempotent by default. It is up to you to set the flag in your code if you know that your queries are safe to retry.

Note that this behavior will also become the default in version 3.1.0 of the core driver.