Improve documentation on CassandraTemplate. Explain differences between Spring CQL and Spring Data Cassandra. Add User-Defined-Type mapping example. Fix typos.
Align documentation structure with other Spring Data Modules. Add chapters for mapping and supported data types. Add new features chapter. Merge existing documentation into the aligned structure. Add John Blum and Mark Paluch to pom.xml.
We now support DTO projections for query methods. DTO projection selects records from Cassandra and applies projected results on the DTO. DTOs are plain Java objects that fit to the underlying entity.
@Table
class Person {
@PrimaryKeyColumn(type = PrimaryKeyType.PARTITIONED, ordinal = 0) private String lastname;
@PrimaryKeyColumn(type = PrimaryKeyType.CLUSTERED, ordinal = 1) private String firstname;
private String nickname;
private Date birthDate;
// more columns
}
interface PersonRepository extends CrudRepository<Person, String> {
Collection<PersonDto> findPersonDtoBy();
<T> T findDtoByFirstnameStartsWith(String prefix, Class<T> projectionType);
}
class PersonDto {
public String firstname, lastname;
public PersonDto(String firstname, String lastname) {
this.firstname = firstname;
this.lastname = lastname;
}
}
We no longer require entities to be annotated with @Table for data mapping and CRUD operations.
Entities without @Table can be still mapped in both directions and will be excluded from schema-management to prevent table creation for unwanted classes.
A class annotated with @Table will participate in schema management and be exposed as a table entity. Classes used as entities without @Table can still be used to query Cassandra but schema management will not create any tables for these classes.
@Table // entity qualified for schema management
class Person {
@Id private String id;
private String lastname;
private String firstname;
}
// entity that can be used for
// select/insert/update/delete operations and repository use
class Person {
@Id private String id;
private String lastname;
private String firstname;
}
Previously, query method parameter conversion was handled separately. This was duplicate code and the code additionally converted arguments into property types regardless the further usage. Collection arguments (e.g. for IN query usage) could be converted into the property type (List of String converted into String).
We now handle collection conversion and single element conversion separately so collections are no longer converted into the property's type. Collection elements are now inspected individually regarding their type/simple type conversion.
This change also considers enum types as simple types with a distinct conversion of the enum value into a Cassandra value (numeric, character). The change in enum value handling reduces the scope of the conversion service usage and prevents accidental conversion.
Original pull request: #89.
We now support @AliasFor to build composed annotations with @Table, @UserDefinedType, @PrimaryKey, @PrimaryKeyClass, @PrimaryKeyColumn, @Column, @Query, @CassandraType.
Original pull request: #90.
Revert added features in version 1.0 schema files in favor of version 1.5 schema files. Remove license header. Remove TODOs and fix documentation source names.
We now provide revised CQL and Cassandra templates as central classes to interact with CQL and Cassandra with object mapping. Previously, synchronous and asynchronous methods were exposed inside the same interfaces that made it hard to chose the right method.
The revised Template API consists of:
* CqlTemplate
* AsyncCqlTemplate
* CassandraTemplate
* AsyncCassandraTemplate
CassandraTemplate and AsyncCassandraTemplate reuse CqlTemplate and AsyncCqlTemplate instead of extending from these. This is, to not mix methods using conversion/object mapping with lower level CQL execution methods.
AsyncCqlTemplate and AsyncCassandraTemplate are all new and benefit from ListenableFuture as synchronization aid. They no longer rely on various callback-interfaces.
CassandraTemplate and AsyncCassandraTemplate no longer provide insert/update/delete methods accepting a collection of items. Use CassandraBatchOperations for atomic batches to group operations.
We now use the newly introduced ….useRepositoryConfiguration(…) in the module specific RepositoryConfigurationExtension implementations to distinguish between reactive and non-reactive repositories.
Removed RepositoryType class as it was only used by the previous repository type detection.
Moved to new base class for reactive repository factories.
- Remove version placeholders for reactor and rxjava
- Adopt type migration of ReactiveWrappers
- Adopt RxJava to RxJava1 repository interface renaming
- Use ReactiveQueryMethod in ReactiveMongoQuery.
- Remove trailing whitespaces.
- Use ReflectionUtils for method iteration in ReactiveType.
We now support reactive data access with Spring Data Cassandra by adopting Datastax' asynchronous driver.
ReactiveCqlTemplate and ReactiveCassandraTemplate use Project Reactor wrapper types Mono and Flux to implement Template API and repository support. Reactive template supports common operations such as:
* Query/Execution methods for static CQL and prepared statements
* Insert/Save/Update/Delete methods
* Exists and Count projections
* Reactive Callback methods
Person person = new Person("Dave", 25);
template.insert(person) //
.flatMap(p -> template.update(new Person("Sven", 25))) //
.flatMap(p -> template.selectOneById(person.getId(), Person.class)) //
.subscribeWith(TestSubscriber.create()) //
.await() //
.assertValuesWith(result -> {
assertThat(result.getFirstName(), is(equalTo("Sven")));
});
Reactive Repository support is built on top of ReactiveCassandraTemplate using ReactiveCassandraRepository as the store-specific base repository. Reactive repositories are enabled by using @EnableReactiveCassandraRepositories on a @Configuration class to opt-in for reactive support. Reactive repositories can be composed of a reactive base interface such as
* ReactiveCrudRepository
* ReactiveSortingRepository
* RxJava1CrudRepository
* RxJava1SortingRepository
and are identified as reactive repository if one method uses a reactive wrapper type (such as Flux or Observable). If a reactive repository is discovered, it's not implemented by the blocking repository support but with the reactive repository factory. Blocking methods are not (yet) synchronized when using a reactive repository so each repository method must use a reactive wrapper result type. Reactive repository support with Spring Data allows using RxJava1 and Project Reactor types to declare repository methods. Reactive wrapper types are internally converted so the composition library choice on repository level is left up to the user.
There's feature parity between Reactive Cassandra repository support and blocking repository support.
Feature overview:
* Query Methods using String queries and Query Derivation
* Projections
@Configuration
@EnableReactiveCassandraRepositories
class ApplicationConfig extends AbstractReactiveCassandraConfiguration {
@Override
protected String getKeyspaceName() {
return "mykeyspace";
}
@Override
protected String getEntityBasePackages() {
return new String[] {"com.springdata.cassandra"};
}
}
public interface PersonRepository extends ReactiveSortingRepository<Person, String> {
Flux<Person> findByFirstname(String firstname);
Flux<Person> findByFirstname(Publisher<String> firstname);
Mono<Person> findByFirstnameAndLastname(String firstname, String lastname);
}
public interface PersonRepository extends RxJava1SortingRepository<Person, String> {
Observable<Person> findByFirstname(String firstname);
Observable<Person> findByFirstname(Single<String> firstname);
Single<Person> findByFirstnameAndLastname(String firstname, String lastname);
}
We now support Cassandra User-defined types. UDTs can be created using CQL generators and used inside of mapped domain classes. User-defined types can be used either raw as UDTValue that is passed through or as mapped object. Mapped UDTs must be annotated with @UserDefinedType. Types are included into schema generation so known and defined UDTs are created before any tables are created. UDTs can be used with set and list collection types and in primary keys. UDTs can also be used in repository query methods as query predicates.
Updating UDTs will update the whole UDT.
@UserDefinedType
public class Address {
String city;
String country;
}
@Table
public class Person {
@Id String id;
Address address;
UDTValue genericUdt;
}
The XML namespace support was extended with new schema versions to support provide a User Type resolver so UDTs can be resolved:
<cassandra:mapping>
<cassandra:user-type-resolver keyspace-name="${cassandra.keyspace}" />
</cassandra:mapping>
We now consider registered custom write converters for top-level collection types (like Map<String, Collection<String>>) to convert properties to Java types. Previously, only collection component types and non-collection top-level types were used to determine a converter.
Methods accepting a List of entities perform batching operations (insert/update/delete).
This can be fine for entities sharing a partition key but leads in most cases to distributed batches across a Cassandra cluster which is an anti-pattern. CassandraTemplate exposes CassandraBatchOperations for batching operations. As of Version 1.5, all methods accepting a List of entities are deprecated because there is no alternative of inserting multiple rows in an atomic way that guarantees not to harm Cassandra performance. These methods will be removed in Version 2.0.
We now support named and expression parameters in String-based repository query methods. Name-based parameters are referenced with :parameter. Expression parameters can reference either parameter names (if provided) with :#{expression}/#{#fieldname} or index-based with ?#{[0]}.
String-based query creation now also serializes parameters using the configured CodecRegistry so escaping and serialization is handled by the driver itself which leads to correct queries.
public interface SampleRepository extends Repository<Person, String> {
@Query("SELECT * FROM person WHERE lastname = ?0;")
Person findByLastname(String lastname);
@Query("SELECT * FROM person WHERE lastname = :lastname;")
Person findByNamedParameter(@Param("lastname") String lastname);
@Query("SELECT * FROM person WHERE lastname = ?#{[0]};")
Person findByIndexExpressionParameter(String lastname);
@Query("SELECT * FROM person WHERE lastnames IN (?0) AND age = ?1;")
Person findByLastNamesAndAge(Collection<String> lastname, int age);
@Query("SELECT * FROM person WHERE lastname = :#{#lastname == 'Matthews' ? 'Admin' : #lastname};")
Person findByConditionalExpressionParameter(@Param("lastname") String lastname);
}
Related tickets: DATACASS-122, DATACASS-240
We provide now two separate verifiers for Table types and PrimaryKey types. Exception messages are aligned between both verifiers and the checks use simplified code instead to perform checks. VerifierMappingExceptions introduces now immutability and methods introducing mutability are deprecated.
We now rely on Row.getObject(…) to retrieve data from a Cassandra Column. CodecRegistry and ProtocolVersion are configured on Cluster so there's no need to use a static configured CodecRegistry and ProtocolVersion that might not fit the configured values.
