Guide to Cassandra Object Mapper with Spring

1. Overview

This article will focus on setting up Spring to store and fetch data from Apache Cassandra to Java Object using Object Mapper.

We'll start with the basics and will go through the configuration of a practical example demonstrating conversion from any Java Object to Apache Cassandra UDT. If this is your first time using Spring with Apache Cassandra, maybe this article will get you up to speed: http://www.baeldung.com/spring-data-cassandratemplate-cqltemplate. And if you need help with Cassandra data modelling: http://www.baeldung.com/cassandra-data-modeling.

2. Maven Dependencies

We'll start by adding maven dependencies in the pom.xml:

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

<dependency><groupId>com.datastax.cassandra</groupId><artifactId>cassandra-driver-mapping</artifactId><version>3.2.0</version>
</dependency>

3. Cassandra User-Defined Types(UDT)

We'll use datastax driver that provides a simple object mapper, handling basic CRUD operations in Cassandra UDT and collections. Here we'll see how to store Java Objects and Collections to Cassandra UDT. You can store nested objects using Cassandra User Defined Type(UDT).

3.1 Declaring a Cassandra Type

Let's start with declaring a Cassandra UDT which we'll use in our main Table. UDT can be nested into another one, given former is declared before latter.

CREATE TYPE gym.owner_info(
    name text,
    phone_number text,
    address text,
)

3.2 Declaring Cassandra Table

Next step we'll define the Table gym_by_city in Cassandra containing information about gyms spread out worldwide. In this example, we'll include UDT shown above as well as a collection. The frozen keyword is used

CREATE TABLE gym.gym_by_city(
     country_code text,
     state text,
     city text,
     gym_name text,
     opening_date timestamp,
     owner frozen<owner_info>,
     revenue_by_year map<int, decimal>,
     PRIMARY KEY((country_code, state, city), opening_date, gym_name))
     WITH CLUSTERING ORDER BY (opening_date DESC, gym_name ASC);

4. The Entity

Let's see how to define the POJO class to store and manipulate Cassandra data. Using annotations, Cassandra tables are mapped to this Java Object. First one is the entity class for UDT and the second one is for 'gym_by_city' table.

@UDT(keyspace = "gym", name = "owner_info")
public class OwnerInfo{

   @Field(name = "name")
   private String name;

   @Field(name = "phone_number")
   private String phoneNumber;

   @Field(name = "address")
   private String address;

   //Standard getters and setters
}

NOTE: Timestamp data type is from java.sql.Timestamp

@Table(keyspace = "gym", name="gym_by_city")
public class GymByCity{
    
    @PartitionKey(0)
    @Column(name = "country_code")
    private String countryCode;

    @PartitionKey(1)
    @Column(name = "state")
    private String state;
 
    @PartitionKey(2)
    @Column(name = "column")
    private String city;

    @ClusteringColum(1)
    @Column(name = "gym_name")
    private String gymName;
    
    @ClusteringColumn(0)
    @Column(name = "opening_date")
    private Timestamp openingDate;

    @Frozen@Column(name = "owner")
    private OwnerInfo owner;
    
    @Frozen@Column(name = "revenue_by_year")
    private HashMap<Integer, Decimal> revenueByYear;

    //Standard getters and setters
}

Frozen serializes UDT and Cassandra collections into a single value and doesn't allow updates to individual fields. Cassandra treats the value of frozen type as a blob.

5. Entity Mapper

We'll use Mapping Manager to query data from Cassandra to Java Objects. Mapping Manager is thread-safe and can be safely shared throughout the application. We'd typically create one instance at startup, right after our session. Each Entity Class is managed by a dedicated Mapper Object. We'll see how to perform basic query operations using Mapper.

public void saveGymByCity(GymByCity gymData){
   MappingManager manager = new MappingManager(cassandraTemplate.getSession());
   Mapper<GymByCity> mapper = manager.mapper(GymByCity.class);
   
   mapper.save(gymData);
}

This will save Java object to Cassandra using Object Mapper.

public List<GymByCity> getGymListGivenCountryAndState(String countryCode, String state){
    MappingManager manager = new MappingManager(cassandraTemplate.getSession());
    Mapper<GymByCity> mapper = manager.mapper(GymByCity.class);

    Select select = QueryBuilder.select.all().from("gym_by_city");
    select.where(QueryBuilder.eq("country_code",countryCode))
    .and(QueryBuilder.eq("state",state));
    select.allowFiltering();

    ResultSet resultSet = cassandraTemplate.getSession().execute(select);
    Result<GymByCity> list = mapper.map(resultSet);

    return list.all();
    //return list.one() in case of unique result.
 }

Result<> is iterable type so accessing will exhaust the data from it. Above example will give List of required entries. Mapper Object provides support for Asynchronous equivalents.

6. Conclusion

This tutorial covered basic steps of utilizing User-Defined Types and Collections using Cassandra database with Spring.