從 2.x 遷移到 3.x 指南

Spring Data for Apache Cassandra 3.0 在從早期版本升級時引入了一系列重大變更。

檢視依賴項

升級到 Spring Data Cassandra 需要升級到 DataStax Driver 4 版本。升級到新驅動程式會帶來傳遞性依賴項變更，最值得注意的是，Google Guava 被驅動程式捆綁和混淆（shaded）。請查閱 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) 元素，該元素同時配置 keyspace 和 endpoints。

隨著升級，schema 支援已移至一個新的名稱空間元素：cassandra:session-factory，它提供了一個 SessionFactory bean。

示例 1. 版本 2 中的 Cluster、Session 和 Schema 配置
<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 中的 Session 和 Schema 配置
<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 名稱空間配置時不再註冊預設的 Mapping Context、Context 和 Template API bean。預設設定應在應用程式或 Spring Boot 層面應用。

Template API

如果您的應用程式主要與對映實體或 Java 基本型別互動，Spring Data for Apache Cassandra 會將驅動程序升級帶來的大多數變化封裝在 Template API 和 repository 支援中。

我們通常建議使用 SessionFactory 來建立 CqlTemplate 和 CassandraTemplate 物件，因為工廠的使用允許 schema 建立的同步，並在使用多個數據庫時引入了一定程度的靈活性。

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

<cassandra:template session-ref="…" cassandra-converter-ref="…"/>
示例 4. 版本 3 中的 Template 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 driver 4 改變了非同步執行查詢的結果型別。為了反映這些變化，您需要調整提供以下功能的程式碼

  • AsyncSessionCallback 的實現

  • AsyncPreparedStatementCreator 的實現

結果集提取需要 DataStax 的 AsyncResultSet 的新介面。AsyncCqlTemplate 現在在使用之前使用 ResultSetExtractor 的地方使用 AsyncResultSetExtractor。請注意，AsyncResultSetExtractor.extractData(…) 返回一個 Future 而不是標量物件，因此程式碼遷移帶來了在提取器中使用完全非阻塞程式碼的可能性。

資料模型遷移

如果您使用以下特性，您的資料模型可能需要更新

  • @CassandraType

  • forceQuote 在 @Table, @Column, @PrimaryKeyColumn, @PrimaryKey 和 @UserDefinedType 中

  • 使用 java.lang.Date 的屬性

  • 使用 UDTValue 或 TupleValue 的屬性

@CassandraType

DataStax driver 4 不再附帶用於描述 Cassandra 型別的 Name 列舉。我們決定透過 CassandraType.Name 重新引入該列舉。請確保更新您的匯入以使用新引入的替代型別。

Force Quote

此標誌現已棄用，我們建議不再使用它。Spring Data for Apache Cassandra 內部使用驅動程式的 CqlIdentifier，它確保在需要的地方進行引用（quoting）。

屬性型別

DataStax driver 4 不再使用 java.lang.Date。請升級您的資料模型以使用 java.time.LocalDateTime。請也將原始 UDT 和 tuple 型別遷移到新的驅動程式型別 UdtValue 和 TupleValue。

其他變化

  • 驅動程式的 ConsistencyLevel 常量類已被移除，並作為 DefaultConsistencyLevel 重新引入。@Consistency 已適配 DefaultConsistencyLevel。

  • QueryOptions 和 …CqlTemplate 型別上的 RetryPolicy 已被移除，沒有替代。

  • 驅動程式的 PagingState 型別已被移除。分頁狀態現在使用 ByteBuffer。

  • SimpleUserTypeResolver 現在接受 CqlSession 而不是 Cluster。

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

  • 引入 StatementBuilder 以函式式構建 statements，因為 QueryBuilder API 使用不可變 statement 型別。

  • 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()）。

  • Schema 建立已從 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 屬性，因為不再需要引用（quoting）。CqlIdentifier 會正確轉義保留關鍵字並處理大小寫敏感性。

  • QueryOptions 和 …CqlTemplate 型別上的 fetchSize 已被棄用，請改用 pageSize。

  • CassandraMappingContext.setUserTypeResolver(…), CassandraMappingContext.setCodecRegistry(…), 和 CassandraMappingContext.setCustomConversions(…)：在 CassandraConverter 上配置這些屬性。

  • TupleTypeFactory 和 CassandraMappingContext.setTupleTypeFactory(…)：TupleTypeFactory 不再使用，因為 Cassandra 驅動程式附帶了 DataTypes.tupleOf(…) 工廠方法。

  • 透過 CqlSessionFactoryBean (cassandra:session) 建立 Schema 已被棄用。透過 CqlSessionFactoryBean (cassandra:session) 建立 Keyspace 不受影響。

已移除

配置 API

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer（請改用 SessionBuilderConfigurer）

工具類

  • GuavaListenableFutureAdapter

  • 接受 ConsistencyLevel 和 RetryPolicy 引數的 QueryOptions 和 WriteOptions 建構函式。請結合執行配置檔案使用構建器作為替代。

  • CassandraAccessor.setRetryPolicy(…) 和 ReactiveCqlTemplate.setRetryPolicy(…) 方法。請使用執行配置檔案作為替代。

名稱空間支援

新增內容

配置 API

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean，包括透過 KeyspacePopulator 建立 schema

  • KeyspacePopulator 和 SessionFactoryInitializer 用於初始化 keyspace

名稱空間支援

  • cassandra:cluster（endpoint 屬性已合併到 cassandra:session）

  • cassandra:initialize-keyspace 名稱空間支援

  • cassandra:session-factory，支援 cassandra:script