Migration Guide from 1.x to 2.x

用于 Apache Cassandra 的 Spring Data 2.0 在从早期的版本升级时引入了一组重大更改：

Spring Data for Apache Cassandra 2.0 introduces a set of breaking changes when upgrading from earlier versions:

  • Merged the spring-cql and spring-data-cassandra modules into a single module.

  • Separated asynchronous and synchronous operations in CqlOperations and CassandraOperations into dedicated interfaces and templates.

  • Revised the CqlTemplate API to align with JdbcTemplate.

  • Removed the CassandraOperations.selectBySimpleIds method.

  • Used better names for CassandraRepository.

  • Removed SD Cassandra ConsistencyLevel and RetryPolicy types in favor of DataStax ConsistencyLevel and RetryPolicy types.

  • Refactored CQL specifications to value objects and configurators.

  • Refactored QueryOptions to be immutable objects.

  • Refactored CassandraPersistentProperty to single-column.

Deprecations

  • Deprecated QueryOptionsBuilder.readTimeout(long, TimeUnit) in favor of QueryOptionsBuilder.readTimeout(Duration).

  • Deprecated CustomConversions in favor of CassandraCustomConversions.

  • Deprecated BasicCassandraMappingContext in favor of CassandraMappingContext.

  • Deprecated o.s.d.c.core.cql.CachedPreparedStatementCreator in favor of o.s.d.c.core.cql.support.CachedPreparedStatementCreator.

  • Deprecated CqlTemplate.getSession() in favor of getSessionFactory().

  • Deprecated CqlIdentifier.cqlId(…) and KeyspaceIdentifier.ksId(…) in favor of the .of(…) methods.

  • Deprecated constructors of QueryOptions in favor of their builders.

  • Deprecated TypedIdCassandraRepository in favor of CassandraRepository

Merged Spring CQL and Spring Data Cassandra Modules

Spring CQL 和 Spring Data Cassandra 现已合并到单个模块中。独立的 spring-cql 模块不再可用。你可以在 spring-data-cassandra 中找到合并所有类型。以下清单展示如何在 Maven 依赖项中包含 spring-data-cassandra：

Spring CQL and Spring Data Cassandra are now merged into a single module. The standalone spring-cql module is no longer available. You can find all types merged into spring-data-cassandra. The following listing shows how to include spring-data-cassandra in your maven dependencies:

<dependencies>

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-cassandra</artifactId>
    <version>{version}</version>
  </dependency>

</dependencies>

通过合并，我们将所有 CQL 包合并到 Spring Data Cassandra 中：

With the merge, we merged all CQL packages into Spring Data Cassandra:

  • Moved o.s.d.cql into o.s.d.cassandra.core.cql.

  • Merged o.s.d.cql with o.s.d.cassandra.config and flattened the XML and Java subpackages.

  • Moved CassandraExceptionTranslator and CqlExceptionTranslator to o.s.d.c.core.cql.

  • Moved Cassandra exceptions o.s.d.c.support.exception to o.s.d.cassandra.

  • Moved o.s.d.c.convert to o.s.d.c.core.convert (affects converters).

  • Moved o.s.d.c.mapping to o.s.d.c.core.mapping (affects mapping annotations).

  • Moved MapId from o.s.d.c.repository to o.s.d.c.core.mapping.

[[revised-cqltemplate/cassandratemplate]]== 已修改的 CqlTemplate/CassandraTemplate

[[revised-cqltemplate/cassandratemplate]] == Revised CqlTemplate/CassandraTemplate

我们以三种方式分隔 CqlTemplate 和 CassandraTemplate：

We split CqlTemplate and CassandraTemplate in three ways:

  • CassandraTemplate is no longer a CqlTemplate but uses an instance that allows reuse and fine-grained control over fetch size, consistency levels, and retry policies. You can obtain the CqlOperations through CassandraTemplate.getCqlOperations(). Because of the change, dependency injection of CqlTemplate requires additional bean setup.

  • CqlTemplate now reflects basic CQL operations instead of mixing high-level and low-level API calls (such as count(…) versus execute(…)) and the reduced method set is aligned with Spring Frameworks’s JdbcTemplate with its convenient callback interfaces.

  • Asynchronous methods are re-implemented on AsyncCqlTemplate and AsyncCassandraTemplate by using ListenableFuture. We removed Cancellable and the various async callback listeners. ListenableFuture is a flexible approach and allows transition into a CompletableFuture.

Removed CassandraOperations.selectBySimpleIds()

此方法已被移除，因为它不支持复杂 ID。新引入的查询 DSL 允许映射和复杂 ID 用于单列 ID，如下面的示例所示：

The method was removed because it did not support complex IDs. The newly introduced query DSL allows mapped and complex id’s for single column Id’s, as the following example shows:

cassandraTemplate.select(Query.query(Criteria.where("id").in(…)), Person.class)

Better names for CassandraRepository

我们重命名了 CassandraRepository 和 TypedIdCassandraRepository，以便将 Spring Data Cassandra 命名与其他 Spring Data 模块对齐：

We renamed CassandraRepository and TypedIdCassandraRepository to align Spring Data Cassandra naming with other Spring Data modules:

  • Renamed CassandraRepository to MapIdCassandraRepository

  • Renamed TypedIdCassandraRepository to CassandraRepository

  • Introduced TypedIdCassandraRepository, extending CassandraRepository as a deprecated type to ease migration

Removed SD Cassandra ConsistencyLevel and RetryPolicy types in favor of DataStax ConsistencyLevel and RetryPolicy types

Spring Data Cassandra ConsistencyLevel 和 RetryPolicy 已被移除。请使用 DataStax 驱动程序提供的类型。

Spring Data Cassandra ConsistencyLevel and RetryPolicy have been removed. Please use the types provided by the DataStax driver.

Spring Data Cassandra 类型限制了 Cassandra 本机驱动程序中提供的和允许的可用功能的使用。结果是，每次驱动程序引入新的功能时，Spring Data Cassandra 的类型都需要更新。

The Spring Data Cassandra types restricted usage of available features provided in and allowed by the Cassandra native driver. As a result, the Spring Data Cassandra’s types required an update each time newer functionality was introduced by the driver.

Refactored CQL Specifications to Value Objects and Configurators

尽可能多地说，CQL 规范类型现在是值类型（例如 FieldSpecification, AlterColumnSpecification），并且对象由静态工厂方法构建。这允许不可变的简单值对象。以强制属性（例如表名或键空间名）进行操作的配置器对象（例如 AlterTableSpecification）最初是通过静态工厂方法构建的，并允许进一步配置，直到创建所需状态。

As much as possible, CQL specification types are now value types (such as FieldSpecification, AlterColumnSpecification), and objects are constructed by static factory methods. This allows immutability for simple value objects. Configurator objects (such as AlterTableSpecification) that operate on mandatory properties (such as a table name or keyspace name) are initially constructed through a a static factory method and allow further configuration until the desired state is created.

Refactored QueryOptions to be Immutable Objects

QueryOptions 和 WriteOptions 现在是不可变的，并且可以通过生成器创建。接受`QueryOptions` 的方法强制使用非空对象，这些对象可从静态 empty() 工厂方法中获取。以下示例展示了如何使用 QueryOptions.builder()：

QueryOptions and WriteOptions are now immutable and can be created through builders. Methods accepting QueryOptions enforce non-null objects, which are available from static empty() factory methods. The following example shows how to use QueryOptions.builder():

QueryOptions queryOptions = QueryOptions.builder()
		.consistencyLevel(ConsistencyLevel.ANY)
		.retryPolicy(FallthroughRetryPolicy.INSTANCE)
		.readTimeout(Duration.ofSeconds(10))
		.fetchSize(10)
		.tracing(true)
		.build();

Refactored CassandraPersistentProperty to Single-column

此更改仅在对映射模型直接操作时会影响你。

This change affects You only if you operate directly on the mapping model.

CassandraPersistentProperty 以前允许绑定多个列名以用于复合主键。CassandraPersistentProperty 的列现在已减少到单列。已解决的复合主键通过 MappingContext.getRequiredPersistentEntity(…) 映射到某个类。

CassandraPersistentProperty allowed previously multiple column names to be bound for composite primary key use. Columns of a CassandraPersistentProperty are now reduced to a single column. Resolved composite primary keys map to a class through MappingContext.getRequiredPersistentEntity(…).