com.datastax.oss.driver.api.mapper.annotations.SetEntity Maven / Gradle / Ivy
/*
* Copyright DataStax, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.datastax.oss.driver.api.mapper.annotations;
import com.datastax.oss.driver.api.core.cql.BoundStatement;
import com.datastax.oss.driver.api.core.cql.BoundStatementBuilder;
import com.datastax.oss.driver.api.core.data.SettableByName;
import com.datastax.oss.driver.api.core.data.UdtValue;
import com.datastax.oss.driver.api.mapper.entity.saving.NullSavingStrategy;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Annotates a {@link Dao} method that fills a core driver data structure from an instance of an
* {@link Entity} class.
*
* Example:
*
*
* public interface ProductDao {
* @SetEntity
* BoundStatement bind(Product product, BoundStatement boundStatement);
* }
*
*
* The generated code will set each entity property on the target, such as:
*
*
* boundStatement = boundStatement.set("id", product.getId(), UUID.class);
* boundStatement = boundStatement.set("description", product.getDescription(), String.class);
* ...
*
*
* It does not perform a query. Instead, those methods are intended for cases where you will execute
* the query yourself, and just need the conversion logic.
*
* Parameters
*
* The method must have two parameters: one is the entity instance, the other must be a subtype of
* {@link SettableByName} (the most likely candidates are {@link BoundStatement}, {@link
* BoundStatementBuilder} and {@link UdtValue}). Note that you can't use {@link SettableByName}
* itself.
*
* The order of the parameters does not matter.
*
*
Return type
*
* The method can either be void, or return the exact same type as its settable parameter.
*
*
* @SetEntity
* void bind(Product product, UdtValue udtValue);
*
* @SetEntity
* void bind(Product product, BoundStatementBuilder builder);
*
*
* Note that if the settable parameter is immutable, the method should return a new instance,
* because the generated code won't be able to modify the argument in place. This is the case for
* {@link BoundStatement}, which is immutable in the driver:
*
*
* // Wrong: statement won't be modified
* @SetEntity
* void bind(Product product, BoundStatement statement);
*
* // Do this instead:
* @SetEntity
* BoundStatement bind(Product product, BoundStatement statement);
*
*
* If you use a void method with {@link BoundStatement}, the mapper processor will issue a
* compile-time warning.
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SetEntity {
/**
* How to handle null entity properties.
*
* This defaults either to the {@link DefaultNullSavingStrategy DAO-level strategy} (if set),
* or {@link NullSavingStrategy#DO_NOT_SET}.
*/
NullSavingStrategy nullSavingStrategy() default NullSavingStrategy.DO_NOT_SET;
}