最新の安定バージョンについては、Spring Data Cassandra 5.1.0 を使用してください!

Spring で Cassandra に接続する

Apache Cassandra を Spring と併用する場合の最初のタスクの 1 つは、Spring IoC コンテナーを使用して com.datastax.oss.driver.api.core.CqlSession オブジェクトを作成することです。これは、Java ベースの Bean メタデータまたは XML ベースの Bean メタデータを使用して行うことができます。これらについては、次のセクションで説明します。

XML ベースのメタデータの代わりに Java ベースの Bean メタデータを使用して Spring コンテナーを構成する方法に詳しくない方は、こちらのリファレンスドキュメントの概要と、こちらの詳細ドキュメントを参照してください。

Java ベースのメタデータを使用したセッションインスタンスの登録

次の例は、Java ベースの Bean メタデータを使用して com.datastax.oss.driver.api.core.CqlSession のインスタンスを登録する方法を示しています。

例 1: Java ベースの Bean メタデータを使用した com.datastax.oss.driver.api.core.CqlSession オブジェクトの登録
@Configuration
public class AppConfig {

	/*
	 * Use the standard Cassandra driver API to create a com.datastax.oss.driver.api.core.CqlSession instance.
	 */
	public @Bean CqlSession session() {
		return CqlSession.builder().withKeyspace("mykeyspace").build();
	}
}

このアプローチでは、すでにご存知の標準 com.datastax.oss.driver.api.core.CqlSession API を使用できます。

別の方法は、Spring の CqlSessionFactoryBean を使用して、com.datastax.oss.driver.api.core.CqlSession のインスタンスをコンテナーに登録することです。com.datastax.oss.driver.api.core.CqlSession インスタンスを直接インスタンス化する場合と比較して、FactoryBean アプローチには、Cassandra 例外を Spring のポータブル DataAccessException 階層の例外に変換する ExceptionTranslator 実装もコンテナーに提供できるという追加の利点があります。この階層と @Repository の使用については、"Spring の DAO サポート機能" で説明されています。

次の例は、Java ベースのファクトリクラスの使用箇所を示しています。

例 2: Spring の CqlSessionFactoryBean を使用して com.datastax.oss.driver.api.core.CqlSession オブジェクトを登録します。
@Configuration
public class FactoryBeanAppConfig {

	/*
	 * Factory bean that creates the com.datastax.oss.driver.api.core.CqlSession instance
	 */
	@Bean
	public CqlSessionFactoryBean session() {

		CqlSessionFactoryBean session = new CqlSessionFactoryBean();
		session.setContactPoints("localhost");
		session.setKeyspaceName("mykeyspace");

		return session;
	}
}

CassandraTemplate をオブジェクトマッピングおよびリポジトリサポートとともに使用するには、CassandraTemplateCassandraMappingContextCassandraConverter が必要であり、リポジトリサポートを有効にする必要があります。

次の例は、コンポーネントを登録してオブジェクトマッピングとリポジトリサポートを構成する方法を示しています。

例 3: コンポーネントを登録してオブジェクトマッピングとリポジトリサポートを構成する
@Configuration
@EnableCassandraRepositories(basePackages = { "org.springframework.data.cassandra.example" })
public class CassandraConfig {

	@Bean
	public CqlSessionFactoryBean session() {

		CqlSessionFactoryBean session = new CqlSessionFactoryBean();
		session.setContactPoints("localhost");
		session.setKeyspaceName("mykeyspace");

		return session;
	}

	@Bean
	public SessionFactoryFactoryBean sessionFactory(CqlSession session, CassandraConverter converter) {

		SessionFactoryFactoryBean sessionFactory = new SessionFactoryFactoryBean();
		sessionFactory.setSession(session);
		sessionFactory.setConverter(converter);
		sessionFactory.setSchemaAction(SchemaAction.NONE);

		return sessionFactory;
	}

	@Bean
	public CassandraMappingContext mappingContext() {
		return new CassandraMappingContext();
	}

	@Bean
	public CassandraConverter converter(CqlSession cqlSession, CassandraMappingContext mappingContext) {

		MappingCassandraConverter cassandraConverter = new MappingCassandraConverter(mappingContext);
		cassandraConverter.setUserTypeResolver(new SimpleUserTypeResolver(cqlSession));

		return cassandraConverter;
	}

	@Bean
	public CassandraOperations cassandraTemplate(SessionFactory sessionFactory, CassandraConverter converter) {
		return new CassandraTemplate(sessionFactory, converter);
	}
}

Apache Cassandra コンポーネントの Spring Data を登録する構成クラスを作成するのは大変な作業になる可能性があるため、Apache Cassandra の Spring Data には、構築済みの構成サポートクラスが付属しています。AbstractCassandraConfiguration から拡張されたクラスは、Apache Cassandra で使用するために Spring Data の Bean を登録します。AbstractCassandraConfiguration を使用すると、初期エンティティ、デフォルトのクエリオプション、プーリングオプション、ソケットオプションなど、さまざまな構成オプションを提供できます。AbstractCassandraConfiguration は、初期エンティティが指定されている場合、それに基づくスキーマ生成もサポートします。AbstractCassandraConfiguration から拡張するには、少なくとも getKeyspaceName メソッドを実装してキースペース名を指定する必要があります。次の例は、AbstractCassandraConfiguration を使用して Bean を登録する方法を示しています。

例 4: AbstractCassandraConfiguration を使用して Apache Cassandra Bean に Spring Data を登録する
@Configuration
public class CassandraConfiguration extends AbstractCassandraConfiguration {

	/*
	 * Provide a contact point to the configuration.
	 */
	@Override
	public String getContactPoints() {
		return "localhost";
	}

	/*
	 * Provide a keyspace name to the configuration.
	 */
	@Override
	public String getKeyspaceName() {
		return "mykeyspace";
	}
}

Abstract … Configuration クラスは、アプリケーションから Cassandra を使用するために必要なすべての Bean を接続します。この構成では、単一の CqlSession を想定し、それを SessionFactory を介して CqlTemplate などの関連コンポーネントに接続します。CqlSession の作成をカスタマイズする場合は、SessionBuilderConfigurer 関数を提供して CqlSessionBuilder をカスタマイズできます。これは、たとえば、Astra のクラウド接続バンドル。

例 5: AbstractCassandraConfiguration を介して Astra に接続する
@Configuration
public class CustomizedCassandraConfiguration extends AbstractCassandraConfiguration {

	/*
	 * Customize the CqlSession through CqlSessionBuilder.
	 */
	@Override
	protected SessionBuilderConfigurer getSessionBuilderConfigurer() {

		Path connectBundlePath = …;

		return builder -> builder
				.withCloudSecureConnectBundle(Path.of(connectBundlePath));
	}

	/*
	 * Provide a keyspace name to the configuration.
	 */
	@Override
	public String getKeyspaceName() {
		return "mykeyspace";
	}

}

XML 構成

このセクションでは、XML を使用して Spring Data Cassandra を構成する方法について説明します。

引き続き名前空間構成をサポートしますが、通常は Java ベースの構成を使用することをお勧めします。

接続プロパティの外部化

接続プロパティを外部化するには、まず、Cassandra への接続に必要な情報を含むプロパティファイルを作成する必要があります。contactpoints および keyspace は必須フィールドです。

次の例は、cassandra.properties というプロパティファイルを示しています。

cassandra.contactpoints=10.1.55.80:9042,10.1.55.81:9042
cassandra.keyspace=showcase

次の 2 つの例では、Spring を使用してこれらのプロパティを Spring コンテキストに読み込みます。

XML ベースのメタデータを使用したセッションインスタンスの登録

Spring の従来の <beans/> XML 名前空間を使用して、com.datastax.oss.driver.api.core.CqlSession のインスタンスをコンテナーに登録できますが、XML は汎用であるため、非常に冗長になる可能性があります。XML 名前空間は、CqlSession インスタンスなどの一般的に使用されるオブジェクトを構成するより良い代替手段です。cassandra 名前空間を使用すると、CqlSession インスタンスを作成できます。

次の例は、cassandra 名前空間を構成する方法を示しています。

例 6: cassandra 名前空間を使用して Cassandra を構成するための XML スキーマ
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
  xsi:schemaLocation="
    http://www.springframework.org/schema/data/cassandra
    https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
    http://www.springframework.org/schema/beans
    https://www.springframework.org/schema/beans/spring-beans.xsd">

  <!-- Default bean name is 'cassandraSession' -->
  <cassandra:session contact-points="localhost" port="9042">
    <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
  </cassandra:session>

  <cassandra:session-factory>
    <cassandra:script
            location="classpath:/org/springframework/data/cassandra/config/schema.cql"/>
  </cassandra:session-factory>
</beans>

より高度な Cassandra 構成の XML 構成要素を以下に示します。これらの要素はすべてデフォルトの Bean 名を使用して、構成コードをクリーンで読みやすい状態に保ちます。

前の例では、Spring を Cassandra に接続するための構成がいかに簡単であるかを示していますが、他にも多くのオプションがあります。基本的に、DataStax Java ドライバーで使用できるオプションはすべて、Apache Cassandra の Spring Data 構成でも使用できます。これには、認証、負荷分散ポリシー、再試行ポリシー、プーリングオプションが含まれますが、これらに限定されません。Spring Data の Apache Cassandra メソッド名と XML 要素はすべて、ドライバーの構成オプションとまったく同じ (または可能な限り近い) 名前が付けられているため、既存のドライバー構成のマッピングは簡単です。次の例は、XML を使用して Spring Data コンポーネントを構成する方法を示しています。

例 7: XML を使用した Spring Data コンポーネントの構成
<!-- Loads the properties into the Spring Context and uses them to fill
in placeholders in the bean definitions -->
<context:property-placeholder location="classpath:cassandra.properties" />

<!-- REQUIRED: The Cassandra Session -->
<cassandra:session contact-points="${cassandra.contactpoints}" keyspace-name="${cassandra.keyspace}" />

<!-- REQUIRED: The default Cassandra mapping context used by `CassandraConverter` -->
<cassandra:mapping>
  <cassandra:user-type-resolver keyspace-name="${cassandra.keyspace}" />
</cassandra:mapping>

<!-- REQUIRED: The default Cassandra converter used by `CassandraTemplate` -->
<cassandra:converter />

<!-- REQUIRED: The Cassandra template is the foundation of all Spring
Data Cassandra -->
<cassandra:template id="cassandraTemplate" />

<!-- OPTIONAL: If you use Spring Data for Apache Cassandra repositories, add
your base packages to scan here -->
<cassandra:repositories base-package="org.spring.cassandra.example.repo" />