Introduction to Spring Data Cassandra

I usually post about Persistence on Twitter - you can follow me there:

Follow @baeldung

1. Overview

This article is a practical introduction to working with Cassandra with Spring Data.

We’ll start the from the basics and go through the configurations and coding, finally building up a complete Spring Data Cassandra module.

2. Maven Dependencies

Let’s start by defining the dependencies in the pom.xml, with Maven:

<dependency>
    <groupId>com.datastax.cassandra</groupId>
    <artifactId>cassandra-driver-core</artifactId>
    <version>2.1.9</version>
</dependency>

3. Configuration for Cassandra

We’ll use the Java style of configuration throughout this quite to configure the Cassandra integration.

3.1. The Main Config

Let’s start with the main configuration class – of course driven via the class level @Configuration annotation:

@Configuration
public class CassandraConfig extends AbstractCassandraConfiguration {

    @Override
    protected String getKeyspaceName() {
        return "testKeySpace";
    }

    @Bean
    public CassandraClusterFactoryBean cluster() {
        CassandraClusterFactoryBean cluster = 
          new CassandraClusterFactoryBean();
        cluster.setContactPoints("127.0.0.1");
        cluster.setPort(9142);
        return cluster;
    }

    @Bean
    public CassandraMappingContext cassandraMapping() 
      throws ClassNotFoundException {
        return new BasicCassandraMappingContext();
    }
}

Notice the new bean – BasicCassandraMappingContext – with a default implementation. This is required to map the persistent entities between their object and their persistent formats.

And as the default implementation is capable enough, we can use it directly.

3.2. Cassandra Connection Properties

There are three mandatory settings we have to configure to setup the connection for a Cassandra client.

We have to setup the host name that the Cassandra server running as contactPoints. Port is simply the listening port for request in server. KeyspaceName is the namespace that defines the data replication on nodes, which is based on a Cassandra related concept.

4. The Cassandra Repository

We’re going to use a CassandraRepository for data access layer. This follows the Spring Data repository abstraction, which is focused on abstracting out the code required to implement the data access layers across different persistence mechanisms.

4.1. Create the CassandraRepository

Let’s create the CassandraRepository to be used in the configuration:

@Repository
public interface BookRepository extends CassandraRepository<Book> {
    //
}

4.2. Configuration for CassandraRepository

Now, we can extend the configuration in Section 3.1, adding @EnableCassandraRepositories class level annotation to mark our Cassandra Repository created in section 4.1 in CassandraConfig:

@Configuration
@EnableCassandraRepositories(
  basePackages = "org.baeldung.spring.data.cassandra.repository")
public class CassandraConfig extends AbstractCassandraConfiguration {
    //
}

5. The Entity

Let’s have a quick look at the entity – the model class we’re going to be using. The class is annotated and defines additional parameters for the metadata Cassandra data table creation in embedded mode.

Using @Table annotation, the bean is directly mapped to a Cassandra data table. Also each property is defined as a type of primary key or a simple column:

@Table
public class Book {
    @PrimaryKeyColumn(
      name = "isbn", 
      ordinal = 2, 
      type = PrimaryKeyType.CLUSTERED, 
      ordering = Ordering.DESCENDING)
    private UUID id;
    @PrimaryKeyColumn(
      name = "title", ordinal = 0, type = PrimaryKeyType.PARTITIONED)
    private String title;
    @PrimaryKeyColumn(
      name = "publisher", ordinal = 1, type = PrimaryKeyType.PARTITIONED)
    private String publisher;
    @Column
    private Set<String> tags = new HashSet<>();
    // standard getters and setters
}

6. Testing with an Embedded Server

6.1. Maven Dependencies

If you want to run Cassandra in embedded mode (without manually installing a separate Cassandra server), you need to add the cassandra-unit related dependencies to the pom.xml:

<dependency>
    <groupId>org.cassandraunit</groupId>
    <artifactId>cassandra-unit-spring</artifactId>
    <version>2.1.9.2</version>
    <scope>test</scope>
    <exclusions>
        <exclusion>
        <groupId>org.cassandraunit</groupId>
        <artifactId>cassandra-unit</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.cassandraunit</groupId>
    <artifactId>cassandra-unit-shaded</artifactId>
    <version>2.1.9.2</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.hectorclient</groupId>
    <artifactId>hector-core</artifactId>
    <version>2.0-0</version>
</dependency>

It is possible to use an embedded Cassandra server to test this application. The main advantage is that you don’t want to install Cassandra explicitly.

This embedded server is compatible with Spring JUnit Tests as well. Here we can set SpringJUnit4ClassRunner using @RunWith annotation together with the embedded server. So it is possible to implement a complete test suite without having an external Cassandra service running.

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = CassandraConfig.class)
public class BookRepositoryIntegrationTest {
    //
}

6.2. Starting and Stopping the Server

We have to start the server once for the whole test suite, so server start method is marked with @BeforeClass annotation:

@BeforeClass
public static void startCassandraEmbedded() { 
    EmbeddedCassandraServerHelper.startEmbeddedCassandra(); 
    Cluster cluster = Cluster.builder()
      .addContactPoints("127.0.0.1").withPort(9142).build();
    Session session = cluster.connect(); 
}

Next we have to make sure the server is stopped after the completion of the test suite execution:

@AfterClass
public static void stopCassandraEmbedded() {
    EmbeddedCassandraServerHelper.cleanEmbeddedCassandra();
}

6.3. Clean Data Table

It is good practice to drop and create the data table before every test execution, to avoid unexpected results due to the manipulated data in earlier test executions.

Now we can create the data table as the server is started:

@Before
public void createTable() {
    adminTemplate.createTable(
      true, CqlIdentifier.cqlId(DATA_TABLE_NAME), 
      Book.class, new HashMap<String, Object>());
}

and drop after every single test case execution:

@After
public void dropTable() {
    adminTemplate.dropTable(CqlIdentifier.cqlId(DATA_TABLE_NAME));
}

7. Data Access using CassandraRepository

We can directly use the BookRepository we created above to persist, manipulate and fetch the data in Cassandra data base.

7.1. Save a New Book

We can save a new book to our book store:

Book javaBook = new Book(
  UUIDs.timeBased(), "Head First Java", "O'Reilly Media", 
  ImmutableSet.of("Computer", "Software"));
bookRepository.save(ImmutableSet.of(javaBook));

Then we can check the availability of the inserted book in the database:

Iterable<Book> books = bookRepository.findByTitleAndPublisher(
  "Head First Java", "O'Reilly Media");
assertEquals(javaBook.getId(), books.iterator().next().getId());

7.2. Update an Existing Book

Lat’s start by inserting a new book:

Book javaBook = new Book(
  UUIDs.timeBased(), "Head First Java", "O'Reilly Media", 
  ImmutableSet.of("Computer", "Software"));
bookRepository.save(ImmutableSet.of(javaBook));

Let’s fetch the book by the title:

Iterable<Book> books = bookRepository.findByTitleAndPublisher(
  "Head First Java", "O'Reilly Media");

 Then let’s change the title of the book:

javaBook.setTitle("Head First Java Second Edition");
bookRepository.save(ImmutableSet.of(javaBook));

Finally let’s check the whether the title is updated in the database:

Iterable<Book> books = bookRepository.findByTitleAndPublisher(
  "Head First Java Second Edition", "O'Reilly Media");
assertEquals(
  javaBook.getTitle(), updateBooks.iterator().next().getTitle());

7.3. Delete the Existing Book

Insert a new book:

Book javaBook = new Book(
  UUIDs.timeBased(), "Head First Java", "O'Reilly Media",
  ImmutableSet.of("Computer", "Software"));
bookRepository.save(ImmutableSet.of(javaBook));

Then delete the newly entered book:

bookRepository.delete(javaBook);

Now we can check for the deletion:

Iterable<Book> books = bookRepository.findByTitleAndPublisher(
  "Head First Java", "O'Reilly Media");
assertNotEquals(javaBook.getId(), books.iterator().next().getId());

This will cause to throw a NoSuchElementException from the code making sure the book is deleted.

7.4. Find All Books

Insert a new books first:

Book javaBook = new Book(
  UUIDs.timeBased(), "Head First Java", "O'Reilly Media", 
  ImmutableSet.of("Computer", "Software"));
Book dPatternBook = new Book(
  UUIDs.timeBased(), "Head Design Patterns","O'Reilly Media",
  ImmutableSet.of("Computer", "Software"));
bookRepository.save(ImmutableSet.of(javaBook));
bookRepository.save(ImmutableSet.of(dPatternBook));

Find all books:

Iterable<Book> books = bookRepository.findAll();

Then we can check he number of available books in the database:

int bookCount = 0;
for (Book book : books) bookCount++;
assertEquals(bookCount, 2);

8. Conclusion

We went through a basic hands-on introduction to the Cassandra with Spring data using the most common approach using CassandraRepository data access mechanism.

The implementation of the above code snippets and examples can be found in my github project – this is an Eclipse based project, so it should be easy to import and run as it is.