Migration Guide from 2.x to 3.x

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

Review dependencies

升级到 Spring Data Cassandra 需要升级到 DataStax Driver 版本 4。升级到新驱动程序会带来瞬态依赖项更改，最明显的是，Google Guava 已被驱动程序捆绑并遮蔽。有关与驱动程序相关的更改的详细信息，请查看 DataStax Java Driver for Apache Cassandra 4 Upgrade Guide。

Adapt Configuration

DataStax Java Driver 4 将 Cluster 和 Session 对象合并成单个 CqlSession 对象，因此已删除所有与 Cluster 相关的 API。配置已通过移除大多数已移至 DriverConfigLoader（主要基于文件）中的配置项进行了大范围修订。这意味着现在通过其他方式配置了 SocketOptions、AddressTranslator 和更多选项。

如果你使用基于 XML 的配置，请务必将所有配置文件从 cql`名称空间 (`http://www.springframework.org/schema/cql [role="bare"]https://www.springframework.org/schema/cql/spring-cql.xsd) 迁移到 cassandra`名称空间 (`http://www.springframework.org/schema/data/cassandra [role="bare"]https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd)。

为了反映配置构建器的变更，ClusterBuilderConfigurer 已重命名为 SessionBuilderConfigurer，现在接受 CqlSessionBuilder 而不是 Cluster.Builder。请务必在配置中提供本地数据中心，因为它对于正确配置负载平衡是必需的。

Connectivity

Cluster（cassandra:cluster）和 Session（cassandra:session）的配置元素已合并到一个 CqlSession（cassandra:session）元素中，该元素配置了键空间和端点。

在升级时，架构支持已移至新的命名空间元素：cassandra:session-factory，该元素提供了 SessionFactory Bean。

Example 1. Cluster, Session and Schema Configuration in version 2:
<cassandra:cluster contact-points="localhost" port="9042">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:cluster>

<cassandra:session keyspace-name="mykeyspace" schema-action="CREATE">
  <cassandra:startup-cql>CREATE TABLE …</cassandra:startup-cql>
</cassandra:session>
Example 2. Session and Schema Configuration in version 3:
<cassandra:session contact-points="localhost" port="9042" keyspace="mykeyspace" local-datacenter="datacenter1">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:session>

<cassandra:session-factory schema-action="CREATE">
  <cassandra:script location="classpath:/schema.cql"/>
</cassandra:session-factory>

在使用 XML 命名空间配置时，Spring Data Cassandra 3.0 不再注册默认映射上下文、上下文和模板 API bean。应在应用程序或 Spring Boot 级别上应用默认值。

Template API

如果你应用程序主要与映射实体或原始 Java 类型进行交互，那么用于 Apache Cassandra 的 Spring Data 封装了大多数随 Driver 升级而来的更改，如 Template API 和存储库支持。

我们通常建议使用 SessionFactory 创建 CqlTemplate 和 CassandraTemplate 对象，因为工厂用法允许同步以创建架构，并在处理多个数据库时引入了一定程度的灵活性。

Example 3. Template API configuration in version 2:
<cql:template session-ref="…" />

<cassandra:template session-ref="…" cassandra-converter-ref="…"/>
Example 4. Template API configuration in version 3:
<cassandra:session-factory />

<cassandra:cql-template session-factory-ref="…" />

<cassandra:template session-factory-ref="…" cassandra-converter-ref="…"/>

在所有使用 DataStax Driver API 的地方都必须调整你的代码。典型情况包括：

  • Implementations of ResultSetExtractor

  • Implementations of RowCallbackHandler

  • Implementations of RowMapper

  • 实现 PreparedStatementCreator，包括异步和反应式变体

  • Calls to CqlTemplate.queryForResultSet(…)

  • 调用接受 Statement 的方法

Changes in AsyncCqlTemplate

DataStax Driver 4 已更改了异步运行的查询的结果类型。为了反映这些更改，你需要调整你的代码，以提供：

  • Implementations of AsyncSessionCallback

  • Implementations of AsyncPreparedStatementCreator

结果集提取需要一个新接口，用于 DataStax 的 AsyncResultSet。现 AsyncCqlTemplate 在它以前使用 ResultSetExtractor 的位置使用 AsyncResultSetExtractor。请注意，AsyncResultSetExtractor.extractData(…) 返回 Future 而不是标量对象，因此代码迁移为提取器使用完全非阻塞代码提供了可能性。

Data model migrations

如果使用以下功能，则你的数据模型可能需要更新：

  • @CassandraType

  • forceQuote 中的 @Table、@Column、@PrimaryKeyColumn、@PrimaryKey 和 @UserDefinedType

  • Properties using java.lang.Date

  • 使用 UDTValue 或 TupleValue 的属性

@CassandraType

DataStax Driver 4 不再使用 Name 枚举来描述 Cassandra 类型。我们决定使用 CassandraType.Name 重新引入枚举。请务必更新你的导入以使用新引入的替换类型。

Force Quote

此标志现已弃用，我们建议不再使用。针对 Apache Cassandra 的 Spring Data 在内部使用驱动程序的 CqlIdentifier，它确保在需要时加上引号。

Property Types

DataStax 驱动程序 4 不再使用 java.lang.Date。请升级你的数据模型，使用 java.time.LocalDateTime。请还将原始 UDT 和元祖类型迁移到新的驱动程序类型 UdtValue 和 TupleValue。

Other changes

  • 驱动程序的 ConsistencyLevel 常量类已被删除并重新引入为 DefaultConsistencyLevel。@Consistency 已调整为 DefaultConsistencyLevel。

  • RetryPolicy 中 QueryOptions 和 …CqlTemplate 类型的类型已被删除，未替换。

  • 驱动程序的 PagingState 类型已删除。分页状态现在使用 ByteBuffer。

  • SimpleUserTypeResolver 接受 CqlSession 而不是 Cluster。

  • SimpleTupleTypeFactory 已迁移到 enum。SimpleTupleTypeFactory.INSTANCE 不再需要 Cluster/CqlSession 上下文。

  • 引入 StatementBuilder 来构建函数式语句，因为 QueryBuilder API 使用不可变语句类型。

  • Session bean 从 session 重命名为 cassandraSession，SessionFactory bean 从 sessionFactory 重命名为 cassandraSessionFactory。

  • ReactiveSession bean 从 reactiveSession 重命名为 reactiveCassandraSession，ReactiveSessionFactory bean 从 reactiveSessionFactory 重命名为 reactiveCassandraSessionFactory。

  • ReactiveSessionFactory.getSession() 现在返回 Mono&lt;ReactiveSession&gt;。以前它只返回 ReactiveSession。

  • 数据类型解析已移入 ColumnTypeResolver，因此所有 DataType 相关方法都从 CassandraPersistentEntity/CassandraPersistentProperty 移动到 ColumnTypeResolver（受影响方法为 MappingContext.getDataType(…)、CassandraPersistentProperty.getDataType()、CassandraPersistentEntity.getUserType() 和 CassandraPersistentEntity.getTupleType()）。

  • 架构创建已从 MappingContext 移动到 SchemaFactory（受影响方法为 CassandraMappingContext.getCreateTableSpecificationFor(…)、CassandraMappingContext.getCreateIndexSpecificationsFor(…) 和 CassandraMappingContext.getCreateUserTypeSpecificationFor(…)）。

Deprecations

  • CassandraCqlSessionFactoryBean, use CqlSessionFactoryBean instead.

  • KeyspaceIdentifier 和 CqlIdentifier，改为使用 com.datastax.oss.driver.api.core.CqlIdentifier。

  • CassandraSessionFactoryBean, use CqlSessionFactoryBean instead.

  • AbstractCqlTemplateConfiguration, use AbstractSessionConfiguration instead.

  • AbstractSessionConfiguration.getClusterName(), use AbstractSessionConfiguration.getSessionName() instead.

  • CodecRegistryTupleTypeFactory, use SimpleTupleTypeFactory instead.

  • Spring Data 的 CqlIdentifier，改为使用驱动程序 CqlIdentifier。

  • forceQuote 属性因为引用不再是必需的。CqlIdentifier 正确转义保留的关键字并注意大小写敏感性。

  • fetchSize in QueryOptions 和 …CqlTemplate 类型已弃用，请使用 pageSize

  • CassandraMappingContext.setUserTypeResolver(…)、CassandraMappingContext.setCodecRegistry(…) 和 CassandraMappingContext.setCustomConversions(…)：在 CassandraConverter 上配置这些属性。

  • TupleTypeFactory 和 CassandraMappingContext.setTupleTypeFactory(…)：TupleTypeFactory 不再使用，因为 Cassandra 驱动程序提供了一个 DataTypes.tupleOf(…) 工厂方法。

  • 通过 CqlSessionFactoryBean (cassandra:session）创建 Schema 已弃用而通过 CqlSessionFactoryBean (cassandra:session）创建 Keyspace 不会受到影响。

Removals

Configuration API

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer (use SessionBuilderConfigurer instead

Utilities

  • GuavaListenableFutureAdapter

  • QueryOptions 和 WriteOptions 构造函数获取 ConsistencyLevel 和 RetryPolicy 参数。使用构建器结合执行配置文件作为替换。

  • CassandraAccessor.setRetryPolicy(…) 和 ReactiveCqlTemplate.setRetryPolicy(…) 方法。使用执行配置文件作为替换。

Namespace support

Additions

Configuration API

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean（包括通过 KeyspacePopulator 创建 Schema）

  • KeyspacePopulator 和 SessionFactoryInitializer 来初始化一个键空间

Namespace support

  • cassandra:cluster（端点属性合并到 cassandra:session）

  • cassandra:initialize-keyspace namespace support

  • cassandra:session-factory with cassandra:script support