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:

  • 将 spring-cql 和 spring-data-cassandra 模块合并到一个模块。

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

  • 在 CqlOperations 和 CassandraOperations 中将异步操作和同步操作分离到专用的界面和模板。

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

  • 修改 CqlTemplate API 使其与 JdbcTemplate 对齐。

  • Revised the CqlTemplate API to align with JdbcTemplate.

  • Removed the CassandraOperations.selectBySimpleIds method.

  • 为 CassandraRepository 使用更好的名称。

  • Used better names for CassandraRepository.

  • 删除 SD Cassandra ConsistencyLevel 和 RetryPolicy 类型，转而使用 DataStax ConsistencyLevel 和 RetryPolicy 类型。

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

  • 将 CQL 规范重构为值对象和配置器。

  • Refactored CQL specifications to value objects and configurators.

  • 重构 QueryOptions 以使其成为不可变对象。

  • Refactored QueryOptions to be immutable objects.

  • Refactored CassandraPersistentProperty to single-column.

Deprecations

  • 弃用 QueryOptionsBuilder.readTimeout(long, TimeUnit) 转而使用 QueryOptionsBuilder.readTimeout(Duration)。

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

  • 已弃用 CustomConversions，推荐使用 CassandraCustomConversions。

  • Deprecated CustomConversions in favor of CassandraCustomConversions.

  • 已弃用 BasicCassandraMappingContext，推荐使用 CassandraMappingContext。

  • Deprecated BasicCassandraMappingContext in favor of CassandraMappingContext.

  • 已弃用 o.s.d.c.core.cql.CachedPreparedStatementCreator，推荐使用 o.s.d.c.core.cql.support.CachedPreparedStatementCreator。

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

  • 已弃用 CqlTemplate.getSession()，推荐使用 getSessionFactory()。

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

  • 已弃用 CqlIdentifier.cqlId(…) 和 KeyspaceIdentifier.ksId(…)，推荐使用 .of(…) 方法。

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

  • 已弃用 QueryOptions 的构造函数，推荐使用它们的生成器。

  • Deprecated constructors of QueryOptions in favor of their builders.

  • 已弃用 TypedIdCassandraRepository，推荐使用 CassandraRepository

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

  • 将 o.s.d.cql 与 o.s.d.cassandra.config 合并，并简化 XML 和 Java 子包。

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

  • 将 CassandraExceptionTranslator 和 CqlExceptionTranslator 移动至 o.s.d.c.core.cql。

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

  • 将 Cassandra 异常 o.s.d.c.support.exception 移动至 o.s.d.cassandra。

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

  • 将 o.s.d.c.convert 移动至 o.s.d.c.core.convert（影响转换器）。

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

  • 将 o.s.d.c.mapping 移动至 o.s.d.c.core.mapping（影响映射注释）。

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

  • 将 MapId 从 o.s.d.c.repository 移至 o.s.d.c.core.mapping。

  • 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 不再是 CqlTemplate，而是使用允许重复使用和对获取大小、一致性级别和重试策略进行精细控制的实例。您可以通过 CassandraTemplate.getCqlOperations() 获取 CqlOperations。由于该更改，CqlTemplate 的依赖注入需要额外的 bean 设置。

  • 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 现在反映基本 CQL 操作，而不是混合高层次和低层次的 API 调用（例如 count(…) 和 execute(…)），并且精简的方法集与 Spring Framework 的 JdbcTemplate 和其方便的回调接口保持一致。

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

  • 通过使用 ListenableFuture，在 AsyncCqlTemplate 和 AsyncCassandraTemplate 上重新实现异步方法。我们移除了 Cancellable 和各种异步回调侦听器。ListenableFuture 是一种灵活的方法，允许转换为 CompletableFuture。

  • 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

  • 引入 TypedIdCassandraRepository，将 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(…).