CQL Template API

CqlTemplate 类（及其反应式变体 ReactiveCqlTemplate）是核心 CQL 包中的核心类。它处理资源的创建和释放。它执行核心 CQL 工作流的基本任务，例如语句创建和执行，并留待应用程序代码提供 CQL 并提取结果。 CqlTemplate 类执行 CQL 查询和更新语句，对 ResultSet 实例进行迭代，并提取返回的参数值。它还会捕获 CQL 异常，并将它们转换为在 org.springframework.dao 包中定义的通用、更多的信息性异常层次结构。 当您将 CqlTemplate`用于您的代码时，您只需实现具有明确定义的契约的回调接口。给定 `Connection，PreparedStatementCreator`回调接口将使用提供的 CQL 和任何必需的参数创建一个 prepared statement。`RowCallbackHandler`接口从 `ResultSet`的每一行中提取值。 `CqlTemplate 可在 DAO 实现中直接通过包含 SessionFactory 引用的实例化使用，或者在 Spring 容器中进行配置并作为 Bean 引用提供给 DAO。CqlTemplate 是 CassandraTemplate 的基础构建块。 此类发出的所有 CQL 都在与模板实例的全限定类名（通常为 CqlTemplate，但如果您使用 CqlTemplate 类的自定义子类，可能有所不同）对应的类目下以 DEBUG 级别记录。 您可以通过配置 CQL API 实例（CqlTemplate、AsyncCqlTemplate 和 ReactiveCqlTemplate）上的这些参数来控制获取大小、一致性级别和重试策略的默认值。如果没有设置特定查询选项，则应用默认设置。

CqlTemplate 提供不同的执行模型风格。基本的 CqlTemplate 使用阻塞执行模型。你可以使用 AsyncCqlTemplate 进行异步执行并与 ListenableFuture 实例或 ReactiveCqlTemplate 进行同步，也可以使用它进行响应式执行。

Examples of CqlTemplate Class Usage

此部分提供了一些关于 `CqlTemplate`类在实际使用中的示例。这些示例并非 `CqlTemplate`公开的所有功能的详尽列表。有关该内容，请参见 Javadoc。

Querying (SELECT) with CqlTemplate

下面的查询获取表中的行数：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

以下查询使用绑定变量：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

以下示例查询 String：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

以下示例查询并填充单个域对象：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

以下示例查询并填充多个域对象：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

如果最后两个代码片断实际上存在于同一个应用程序中，那么消除两个 RowMapper 匿名内部类中存在的重复并将其提取到一个可以由 DAO 方法引用的单个类（通常是 static 嵌套类）中是有意义的。

例如，最好将最后一个代码片断写成如下形式：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

INSERT, UPDATE, and DELETE with CqlTemplate

您可以使用 execute(…) 方法执行 INSERT、UPDATE 和 DELETE 操作。参数值通常以可变参数或对象数组的形式提供。

以下示例展示如何使用 CqlTemplate 执行 INSERT 操作：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

以下示例展示如何使用 CqlTemplate 执行 UPDATE 操作：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

下面的示例演示如何使用 CqlTemplate 执行 DELETE 操作：

  • Imperative

  • Reactive

link:example$CqlTemplateExamples.java[role=include]
link:example$ReactiveCqlTemplateExamples.java[role=include]

Other CqlTemplate operations

你可以使用 execute(..) 方法来执行任何任意的 CQL，结果是，该方法通常用于 DDL 语句，它被大量重载，其中使用了采用回调接口、绑定变量阵列等方法的变体。

下面的示例演示如何使用传递给 execute() 方法的所有不同的 API 对象来创建和删除表：

link:example$CqlTemplateExamples.java[role=include]

Controlling Cassandra Connections

应用程序通过使用 CqlSession 对象连接到 Apache Cassandra，Cassandra CqlSession 跟踪跟单个节点的多个连接，旨在成为一个线程安全的长生存期对象，通常，你可以为整个应用程序使用一个单独的 CqlSession。

Spring 通过 SessionFactory 获取一个 Cassandra CqlSession，SessionFactory 是 Spring Data for Apache Cassandra 的一部分，它是一个泛化的连接工厂，它让容器或框架对应用程序代码隐藏连接处理和路由问题。

下面的示例演示如何配置一个默认的 SessionFactory：

  • Imperative

  • Reactive

CqlSession session = … // get a Cassandra Session

CqlTemplate template = new CqlTemplate();

template.setSessionFactory(new DefaultSessionFactory(session));
CqlSession session = … // get a Cassandra Session

ReactiveCqlTemplate template = new ReactiveCqlTemplate(new DefaultBridgedReactiveSession(session));

CqlTemplate 和其他模板 API 实现为每个操作获取一个 CqlSession，由于它们长期存在的性质，在调用所需操作后，会话不会被关闭，正确资源释放的职责在于使用该会话的容器或框架。

你可以在 org.springframework.data.cassandra.core.cql.session 包中找到 diverse SessionFactory 实现。

Exception Translation

Spring Framework 为各种不同的数据库和映射技术提供异常转换，这些技术传统上是 JDBC 和 JPA，Spring Data for Apache Cassandra 通过提供 org.springframework.dao.support.PersistenceExceptionTranslator 接口的实现来将这个特性扩展到 Apache Cassandra。

映射到 Spring 的 一致的数据访问异常层级 的动机是让您编写可移植且描述性的异常处理代码，而无需诉诸于与特定 Cassandra 异常进行编码和处理。Spring 的所有数据访问异常均继承自 DataAccessException 类，因此，您可确保在单个 try-catch 块内捕获所有与数据库相关异常。

ReactiveCqlTemplate 和 ReactiveCassandraTemplate 尽早传播异常，在处理响应式序列期间发生的异常作为错误信号发出。