从 2.x 迁移到 3.x 的指南

Spring Data for Apache Cassandra 3.0 在从早期版本升级时引入了一组重大更改。

检查依赖项

升级到 Spring Data Cassandra 需要升级到 DataStax Driver 版本 4。升级到新驱动程序会带来传递依赖项更改，最值得注意的是，Google Guava 由驱动程序捆绑和遮蔽。有关驱动程序相关更改的详细信息，请查看 DataStax Java Driver for Apache Cassandra 4 升级指南。

调整配置

DataStax Java Driver 4 将 Cluster 和 Session 对象合并为单个 CqlSession 对象，因此，所有与 Cluster 相关的 API 都已删除。配置在很大程度上进行了修改，删除了大多数已移至 DriverConfigLoader 的配置项，该配置项主要是基于文件的。这意味着 SocketOptions、AddressTranslator 和许多其他选项现在通过其他方式配置。

如果您使用的是基于 XML 的配置，请确保将所有配置文件从 cql 命名空间（www.springframework.org/schema/cql www.springframework.org/schema/cql/spring-cql.xsd）迁移到 cassandra 命名空间（www.springframework.org/schema/data/cassandra www.springframework.org/schema/data/cassandra/spring-cassandra.xsd）。

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

连接

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

随着升级，模式支持已移至新的命名空间元素：cassandra:session-factory，它提供了一个SessionFactory bean。

示例 1. 版本 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>
示例 2. 版本 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>
Spring Data Cassandra 3.0 在使用 XML 命名空间配置时不再注册默认的映射上下文、上下文和模板 API bean。默认值应在应用程序或 Spring Boot 级别应用。

模板 API

Spring Data for Apache Cassandra 将驱动程序升级带来的大多数更改封装为模板 API 和存储库支持，如果您的应用程序主要与映射的实体或原始 Java 类型交互。

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

示例 3. 版本 2 中的模板 API 配置
<cql:template session-ref="…" />

<cassandra:template session-ref="…" cassandra-converter-ref="…"/>
示例 4. 版本 3 中的模板 API 配置
<cassandra:session-factory />

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

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

您需要在所有使用 DataStax 驱动程序 API 的地方调整代码。典型情况包括

  • ResultSetExtractor的实现

  • RowCallbackHandler的实现

  • RowMapper的实现

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

  • 对CqlTemplate.queryForResultSet(…)的调用

  • 调用接受Statement的方法

AsyncCqlTemplate中的更改

DataStax 驱动程序 4 更改了异步运行的查询的结果类型。为了反映这些更改，您需要调整提供以下内容的代码：

  • AsyncSessionCallback的实现

  • AsyncPreparedStatementCreator的实现

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

数据模型迁移

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

  • @CassandraType

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

  • 使用java.lang.Date的属性

  • 使用UDTValue或TupleValue的属性

@CassandraType

DataStax 驱动程序 4 不再附带用于描述 Cassandra 类型的Name枚举。我们决定使用CassandraType.Name重新引入枚举。请确保更新您的导入以使用新引入的替换类型。

强制引用

此标志现已弃用，我们建议不再使用它。Spring Data for Apache Cassandra 在内部使用驱动程序的CqlIdentifier，该标识符确保在需要的地方进行引用。

属性类型

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

其他更改

  • 驱动程序的ConsistencyLevel常量类已删除，并作为DefaultConsistencyLevel重新引入。@Consistency已适应DefaultConsistencyLevel。

  • QueryOptions和…CqlTemplate类型上的RetryPolicy已删除，没有替换。

  • 驱动程序的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<ReactiveSession>。以前它只返回ReactiveSession。

  • 数据类型解析已移至ColumnTypeResolver，因此所有与DataType相关的函数都已从CassandraPersistentEntity/CassandraPersistentProperty移至ColumnTypeResolver（受影响的函数是MappingContext.getDataType(…)、CassandraPersistentProperty.getDataType()、CassandraPersistentEntity.getUserType()和CassandraPersistentEntity.getTupleType()）。

  • 模式创建已从MappingContext移至SchemaFactory（受影响的函数是CassandraMappingContext.getCreateTableSpecificationFor(…)、CassandraMappingContext.getCreateIndexSpecificationsFor(…)和CassandraMappingContext.getCreateUserTypeSpecificationFor(…)）。

弃用

  • CassandraCqlSessionFactoryBean，请改用CqlSessionFactoryBean。

  • KeyspaceIdentifier 和 CqlIdentifier，请使用 com.datastax.oss.driver.api.core.CqlIdentifier 代替。

  • CassandraSessionFactoryBean，请使用 CqlSessionFactoryBean 代替。

  • AbstractCqlTemplateConfiguration，请使用 AbstractSessionConfiguration 代替。

  • AbstractSessionConfiguration.getClusterName()，请使用 AbstractSessionConfiguration.getSessionName() 代替。

  • CodecRegistryTupleTypeFactory，请使用 SimpleTupleTypeFactory 代替。

  • Spring Data 的 CqlIdentifier，请使用驱动程序 CqlIdentifier 代替。

  • forceQuote 属性，因为不再需要引用。CqlIdentifier 会正确地转义保留关键字并处理大小写敏感问题。

  • QueryOptions 和 …CqlTemplate 类型上的 fetchSize 已弃用，请使用 pageSize 代替。

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

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

  • 通过 CqlSessionFactoryBean（cassandra:session）创建模式已弃用。通过 CqlSessionFactoryBean（cassandra:session）创建键空间不受影响。

移除

配置 API

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer（请使用 SessionBuilderConfigurer 代替

实用程序

  • GuavaListenableFutureAdapter

  • QueryOptions 和 WriteOptions 构造函数，它们接受 ConsistencyLevel 和 RetryPolicy 参数。请使用构建器结合执行配置文件作为替代。

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

命名空间支持

新增

配置 API

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean 包括通过 KeyspacePopulator 创建模式

  • KeyspacePopulator 和 SessionFactoryInitializer 初始化键空间

命名空间支持

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

  • cassandra:initialize-keyspace 命名空间支持

  • cassandra:session-factory 与 cassandra:script 支持