ScyllaDB Docs Scylla Java Driver Manual Object Mapper Using custom codecs

Caution

You're viewing documentation for a previous version of Scylla Java Driver. Switch to the latest stable version.

Using custom codecs¶

The mapper can take advantage of custom codecs to apply custom conversions to mapped columns and fields.

Declaring codecs¶

Let’s assume you have a table containing a timestamp column:

create table user(id int primary key, birth timestamp);

You’ve created a custom class, and the codec to convert it:

public class MyCustomDate { ... }

public class MyCustomDateCodec extends TypeCodec<MyCustomDate> {
    public MyCustomDate() {
        super(DataType.timestamp(), MyCustomDate.class);
    }
    ...
}

Pre-registered codecs¶

If you register your codec with the mapper’s underlying Cluster, it will be automatically available to the mapper:

Cluster cluster = Cluster.builder()
    .addContactPoint("127.0.0.1")
    .withCodecRegistry(
        new CodecRegistry().register(new MyCustomDateCodec())
    ).build();

MappingManager mappingManager = new MappingManager(cluster.connect());

You can normally create your mapped classes using your custom type, without any additional configuration:

@Table(name = "user")
public class User {
  @PartitionKey
  private int id;
  private MyCustomDate birth;

  ... // getters and setters
}

This also works in accessors:

@Accessor
interface UserAccessor {
  @Query("update user set birth = :b where id = :i")
  void updateBirth(@Param("i") int id,
                   @Param("b") MyCustomDate birth);
}

One-time declaration¶

Sometimes you might want to use your codec only for one particular column/field. In that case you won’t register it when initializing the Cluster:

Cluster cluster = Cluster.builder()
    .addContactPoint("127.0.0.1")
    .build();

MappingManager mappingManager = new MappingManager(cluster.connect());

Instead, reference the codec’s class in the @Column annotation:

@Table(name = "user")
public class User {
  @PartitionKey
  private int id;
  @Column(codec = MyCustomDateCodec.class)
  private MyCustomDate birth;

  ... // getters and setters
}

The class must have a no-arg constructor. The mapper will create an instance (one per column) and cache it for future use.

This also works with @Field and @Param annotations.

Implicit UDT codecs¶

The mapper uses custom codecs internally to handle UDT conversions: when you register an entity, the mapper inspects the type of all fields to find classes annotated with @UDT (this works recursively with nested UDTs and collections). For each class, the mapper creates a codec and registers it with the underlying Cluster.

@UDT(name = "address")
public class Address { ... }

@Entity(name = "user")
public class User {
  ...
  private Address address;
  ...
}

Mapper<User> userMapper = mappingManager.mapper(User.class);

// Codec is now registered for Address <-> CQL address

A nice side-effect is that you can now use the @UDT-annotated class with any driver method, not just mapper methods:

Row row = session.execute("select address from user where id = 1").one();
Address address = row.get("address", Address.class);

If you don’t use entity mappers but still want the convenience of the UDT codec for core driver methods, the mapper provides a way to create it independently:

mappingManager.udtCodec(Address.class);

// Codec is now registered

Was this page helpful?

ScyllaDB Java Driver is available under the Apache v2 License. ScyllaDB Java Driver is a fork of DataStax Java Driver. See Copyright here.