com.datastax.oss.driver.api.mapper.result

Interface MapperResultProducer

public interface MapperResultProducer

A component that can be plugged into the object mapper, in order to return custom result types from DAO methods.

For example, this could be used to substitute a 3rd-party future implementation for CompletionStage:

 public class CustomFutureProducer implements MapperResultProducer {
   ...
 }
 

Producers are registered via the Java Service Provider mechanism (see MapperResultProducerService). DAO methods can then use the new type:

 @Dao
 public interface ProductDao {
   @Select
   CustomFuture<Product> findById(UUID productId);
 }
 

See the javadocs of the methods in this interface for more explanations.

Method Summary

Modifier and Type	Method and Description
boolean	canProduce(GenericType<?> resultType) Checks if this producer can handle a particular result type.
Object	execute(Statement<?> statement, MapperContext context, EntityHelper<?> entityHelper) Executes the statement generated by the mapper, and converts the result to the expected type.
Object	wrapError(Exception e) Surfaces any error encountered in the DAO method (either in the generated mapper code that builds the statement, or during invocation of execute(com.datastax.oss.driver.api.core.cql.Statement<?>, com.datastax.oss.driver.api.mapper.MapperContext, com.datastax.oss.driver.api.mapper.entity.EntityHelper<?>)).

Method Detail

canProduce

boolean canProduce(@NonNull
                   GenericType<?> resultType)

Checks if this producer can handle a particular result type.

This will be invoked at runtime to select a producer: if a DAO method declares a return type that is not supported natively, then the mapper generates an implementation which, for every invocation, iterates through all the producers in the order that they were registered, and picks the first one where canProduce() returns true.

Parameters:

resultType - the DAO method's declared return type. If checking the top-level type is sufficient, then GenericType.getRawType() should do the trick. If you need to recurse into the type arguments, call GenericType.getType() and use the java.lang.reflect APIs.

execute

@Nullable
Object execute(@NonNull
                         Statement<?> statement,
                         @NonNull
                         MapperContext context,
                         @Nullable
                         EntityHelper<?> entityHelper)

Executes the statement generated by the mapper, and converts the result to the expected type.

This will be executed at runtime, every time the DAO method is called.

Parameters:

statement - the statement, ready to execute: the mapper has already bound all the values, and set all the necessary attributes (consistency, page size, etc).

context - the context in which the DAO method is executed. In particular, this is how you get access to the session.

entityHelper - if the type to produce contains a mapped entity (e.g. ListenableFuture<Product>), an instance of the helper class to manipulate that entity. In particular, entityHelper.get() allows you to convert rows into entity instances. If the type to produce does not contain an entity, this will be null.

Returns:

the object to return from the DAO method. This must match the type that this producer was selected for, there will be an unchecked cast at runtime.

wrapError

@Nullable
Object wrapError(@NonNull
                           Exception e)
                    throws Exception

Surfaces any error encountered in the DAO method (either in the generated mapper code that builds the statement, or during invocation of execute(com.datastax.oss.driver.api.core.cql.Statement<?>, com.datastax.oss.driver.api.mapper.MapperContext, com.datastax.oss.driver.api.mapper.entity.EntityHelper<?>)).

For some result types, it is expected that errors will be wrapped in some sort of container instead of thrown directly; for example a failed future or publisher.

If rethrowing is the right thing to do, then it is perfectly fine to do so from this method. If you throw checked exceptions, they will be propagated directly if the DAO method also declares them, or wrapped into a RuntimeException otherwise.

Throws:

Exception