com.datastax.driver.mapping

Class Mapper<T>

java.lang.Object

com.datastax.driver.mapping.Mapper<T>

public class Mapper<T>
extends Object

An object handling the mapping of a particular class.

A Mapper object is obtained from a MappingManager using the MappingManager.mapper(java.lang.Class<T>, java.lang.String) method.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Mapper.Option An option for a mapper operation.

Method Summary

Modifier and Type	Method and Description
void	delete(Object... objects) Deletes an entity based on its primary key.
void	delete(T entity) Deletes an entity mapped by this mapper.
void	delete(T entity, Mapper.Option... options) Deletes an entity mapped by this mapper using provided options.
ListenableFuture<Void>	deleteAsync(Object... objects) Deletes an entity based on its primary key asynchronously.
ListenableFuture<Void>	deleteAsync(T entity) Deletes an entity mapped by this mapper asynchronously.
ListenableFuture<Void>	deleteAsync(T entity, Mapper.Option... options) Deletes an entity mapped by this mapper asynchronously using provided options.
Statement	deleteQuery(Object... objects) Creates a query that can be used to delete an entity given its PRIMARY KEY.
Statement	deleteQuery(T entity) Creates a query that can be used to delete the provided entity.
Statement	deleteQuery(T entity, Mapper.Option... options) Creates a query that can be used to delete the provided entity.
T	get(Object... objects) Fetch an entity based on its primary key.
ListenableFuture<T>	getAsync(Object... objects) Fetch an entity based on its primary key asynchronously.
MappingManager	getManager() The MappingManager managing this mapper.
Statement	getQuery(Object... objects) Creates a query to fetch entity given its PRIMARY KEY.
TableMetadata	getTableMetadata() The TableMetadata for this mapper.
Result<T>	map(ResultSet resultSet) Maps the rows from a ResultSet into the class this is a mapper of.
Result<T>	mapAliased(ResultSet resultSet) Deprecated. you no longer need to specify whether a result set is aliased, it will be detected automatically. Use map(ResultSet) instead of this method.
ListenableFuture<Result<T>>	mapAsync(ResultSetFuture resultSetFuture) Asynchronously maps the rows from a ResultSetFuture into the class this is a mapper of.
void	resetDefaultDeleteOptions() Reset the default delete options for this object mapper.
void	resetDefaultGetOptions() Reset the default save options for this object mapper.
void	resetDefaultSaveOptions() Reset the default save options for this object mapper.
void	save(T entity) Saves an entity mapped by this mapper.
void	save(T entity, Mapper.Option... options) Saves an entity mapped by this mapper and using special options for save.
ListenableFuture<Void>	saveAsync(T entity) Saves an entity mapped by this mapper asynchronously.
ListenableFuture<Void>	saveAsync(T entity, Mapper.Option... options) Save an entity mapped by this mapper asynchronously using special options for save.
Statement	saveQuery(T entity) Creates a query that can be used to save the provided entity.
Statement	saveQuery(T entity, Mapper.Option... options) Creates a query that can be used to save the provided entity.
void	setDefaultDeleteOptions(Mapper.Option... options) Set the default delete Mapper.Option for this object mapper, that will be used in all delete operations unless overridden.
void	setDefaultGetOptions(Mapper.Option... options) Set the default get Mapper.Option for this object mapper, that will be used in all get operations unless overridden.
void	setDefaultSaveOptions(Mapper.Option... options) Set the default save Mapper.Option for this object mapper, that will be used in all save operations unless overridden.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getTableMetadata

public TableMetadata getTableMetadata()

The TableMetadata for this mapper.

Returns:

the TableMetadata for this mapper or null if keyspace is not set.

getManager

public MappingManager getManager()

The MappingManager managing this mapper.

Returns:

the MappingManager managing this mapper.

saveQuery

public Statement saveQuery(T entity)

Creates a query that can be used to save the provided entity.

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually or need access to the ResultSet object after execution (to get the trace, the execution info, ...), but in other cases, calling save(T) or saveAsync(T) is shorter.

Note: this method might block if the query is not prepared yet.

Parameters:

entity - the entity to save.

Returns:

a query that saves entity (based on its defined mapping).

saveQuery

public Statement saveQuery(T entity,
                           Mapper.Option... options)

Creates a query that can be used to save the provided entity.

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually or need access to the ResultSet object after execution (to get the trace, the execution info, ...), but in other cases, calling save(T) or saveAsync(T) is shorter. This method allows you to provide a suite of Mapper.Option to include in the SAVE query. Options currently supported for SAVE are :

• Timestamp
• Time-to-live (ttl)
• Consistency level
• Tracing

Note: this method might block if the query is not prepared yet.

Parameters:

entity - the entity to save.

Returns:

a query that saves entity (based on its defined mapping).

save

public void save(T entity)

Saves an entity mapped by this mapper.

This method is basically equivalent to: getManager().getSession().execute(saveQuery(entity)).

Note: this method will block until the entity is fully saved.

Parameters:

entity - the entity to save.

save

public void save(T entity,
                 Mapper.Option... options)

Saves an entity mapped by this mapper and using special options for save. This method allows you to provide a suite of Mapper.Option to include in the SAVE query. Options currently supported for SAVE are :

• Timestamp
• Time-to-live (ttl)
• Consistency level
• Tracing

Note: this method will block until the entity is fully saved.

Parameters:

entity - the entity to save.

options - the options object specified defining special options when saving.

saveAsync

public ListenableFuture<Void> saveAsync(T entity)

Saves an entity mapped by this mapper asynchronously.

This method is basically equivalent to: getManager().getSession().executeAsync(saveQuery(entity)).

Parameters:

entity - the entity to save.

Returns:

a future on the completion of the save operation.

saveAsync

public ListenableFuture<Void> saveAsync(T entity,
                                        Mapper.Option... options)

Save an entity mapped by this mapper asynchronously using special options for save.

This method is basically equivalent to: getManager().getSession().executeAsync(saveQuery(entity, options)).

Parameters:

entity - the entity to save.

options - the options object specified defining special options when saving.

Returns:

a future on the completion of the save operation.

getQuery

public Statement getQuery(Object... objects)

Creates a query to fetch entity given its PRIMARY KEY.

The values provided must correspond to the columns composing the PRIMARY KEY (in the order of said primary key).

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually, but in other cases, calling get(java.lang.Object...) or getAsync(java.lang.Object...) is shorter.

This method allows you to provide a suite of Mapper.Option to include in the GET query. Options currently supported for GET are :

• Consistency level
• Tracing

Note: this method might block if the query is not prepared yet.

Parameters:

objects - the primary key of the entity to fetch, or more precisely the values for the columns of said primary key in the order of the primary key. Can be followed by Mapper.Option to include in the DELETE query.

Returns:

a query that fetch the entity of PRIMARY KEY objects.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

get

public T get(Object... objects)

Fetch an entity based on its primary key.

This method is basically equivalent to: map(getManager().getSession().execute(getQuery(objects))).one().

Note: this method will block until the entity is fully fetched.

Parameters:

objects - the primary key of the entity to fetch, or more precisely the values for the columns of said primary key in the order of the primary key. Can be followed by Mapper.Option to include in the DELETE query.

Returns:

the entity fetched or null if it doesn't exist.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

getAsync

public ListenableFuture<T> getAsync(Object... objects)

Fetch an entity based on its primary key asynchronously.

This method is basically equivalent to mapping the result of: getManager().getSession().executeAsync(getQuery(objects)).

Parameters:

objects - the primary key of the entity to fetch, or more precisely the values for the columns of said primary key in the order of the primary key. Can be followed by Mapper.Option to include in the DELETE query.

Returns:

a future on the fetched entity. The return future will yield null if said entity doesn't exist.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

deleteQuery

public Statement deleteQuery(T entity,
                             Mapper.Option... options)

Creates a query that can be used to delete the provided entity.

This method is a shortcut that extract the PRIMARY KEY from the provided entity and call deleteQuery(Object...) with it. This method allows you to provide a suite of Mapper.Option to include in the DELETE query. Note : currently, only Mapper.Option.Timestamp is supported for DELETE queries.

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually or need access to the ResultSet object after execution (to get the trace, the execution info, ...), but in other cases, calling delete(T) or deleteAsync(T) is shorter.

This method allows you to provide a suite of Mapper.Option to include in the DELETE query. Options currently supported for DELETE are :

• Timestamp
• Consistency level
• Tracing

Note: this method might block if the query is not prepared yet.

Parameters:

entity - the entity to delete.

options - the options to add to the DELETE query.

Returns:

a query that delete entity (based on its defined mapping) with provided USING options.

deleteQuery

public Statement deleteQuery(T entity)

Creates a query that can be used to delete the provided entity.

This method is a shortcut that extract the PRIMARY KEY from the provided entity and call deleteQuery(Object...) with it.

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually or need access to the ResultSet object after execution (to get the trace, the execution info, ...), but in other cases, calling delete(T) or deleteAsync(T) is shorter.

Note: this method might block if the query is not prepared yet.

Parameters:

entity - the entity to delete.

Returns:

a query that delete entity (based on its defined mapping).

deleteQuery

public Statement deleteQuery(Object... objects)

Creates a query that can be used to delete an entity given its PRIMARY KEY.

The values provided must correspond to the columns composing the PRIMARY KEY (in the order of said primary key). The values can also contain, after specifying the primary keys columns, a suite of Mapper.Option to include in the DELETE query. Note : currently, only Mapper.Option.Timestamp is supported for DELETE queries.

This method is useful if you want to setup a number of options (tracing, consistency level, ...) of the returned statement before executing it manually or need access to the ResultSet object after execution (to get the trace, the execution info, ...), but in other cases, calling delete(T) or deleteAsync(T) is shorter. This method allows you to provide a suite of Mapper.Option to include in the DELETE query. Options currently supported for DELETE are :

• Timestamp
• Consistency level
• Tracing

Note: this method might block if the query is not prepared yet.

Parameters:

objects - the primary key of the entity to delete, or more precisely the values for the columns of said primary key in the order of the primary key. Can be followed by Mapper.Option to include in the DELETE query.

Returns:

a query that delete the entity of PRIMARY KEY primaryKey.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

delete

public void delete(T entity)

Deletes an entity mapped by this mapper.

This method is basically equivalent to: getManager().getSession().execute(deleteQuery(entity)).

Note: this method will block until the entity is fully deleted.

Parameters:

entity - the entity to delete.

delete

public void delete(T entity,
                   Mapper.Option... options)

Deletes an entity mapped by this mapper using provided options.

This method is basically equivalent to: getManager().getSession().execute(deleteQuery(entity, options)).

Note: this method will block until the entity is fully deleted.

Parameters:

entity - the entity to delete.

options - the options to add to the DELETE query.

deleteAsync

public ListenableFuture<Void> deleteAsync(T entity)

Deletes an entity mapped by this mapper asynchronously.

This method is basically equivalent to: getManager().getSession().executeAsync(deleteQuery(entity)).

Parameters:

entity - the entity to delete.

Returns:

a future on the completion of the deletion.

deleteAsync

public ListenableFuture<Void> deleteAsync(T entity,
                                          Mapper.Option... options)

Deletes an entity mapped by this mapper asynchronously using provided options.

This method is basically equivalent to: getManager().getSession().executeAsync(deleteQuery(entity, options)).

Parameters:

entity - the entity to delete.

options - the options to add to the DELETE query.

Returns:

a future on the completion of the deletion.

delete

public void delete(Object... objects)

Deletes an entity based on its primary key.

This method is basically equivalent to: getManager().getSession().execute(deleteQuery(objects)).

Note: this method will block until the entity is fully deleted.

Parameters:

objects - the primary key of the entity to delete, or more precisely the values for the columns of said primary key in the order of the primary key.Can be followed by Mapper.Option to include in the DELETE query.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

deleteAsync

public ListenableFuture<Void> deleteAsync(Object... objects)

Deletes an entity based on its primary key asynchronously.

This method is basically equivalent to: getManager().getSession().executeAsync(deleteQuery(objects)).

Parameters:

objects - the primary key of the entity to delete, or more precisely the values for the columns of said primary key in the order of the primary key. Can be followed by Mapper.Option to include in the DELETE query.

Throws:

IllegalArgumentException - if the number of value provided differ from the number of columns composing the PRIMARY KEY of the mapped class, or if at least one of those values is null.

map

public Result<T> map(ResultSet resultSet)

Maps the rows from a ResultSet into the class this is a mapper of.

If the query was user-generated (that is, passed directly to session.execute() or configured with @Query in an @Accessor-annotated interface), then only the columns present in the result set will be mapped to the corresponding fields, and Computed fields will not be populated.

If the query was generated by the mapper (for example with getQuery(Object...)), all fields will be mapped, as if the object came from a direct get(Object...) call.

Parameters:

resultSet - the ResultSet to map.

Returns:

the mapped result set. Note that the returned mapped result set will encapsulate resultSet and so consuming results from this returned mapped result set will consume results from resultSet and vice-versa.

mapAsync

public ListenableFuture<Result<T>> mapAsync(ResultSetFuture resultSetFuture)

Asynchronously maps the rows from a ResultSetFuture into the class this is a mapper of.

Use this method to map a ResultSetFuture that was not generated by the mapper (e.g. a ResultSetFuture coming from a manual query or an Accessor method). It expects that the result set contains all column mapped in the target class, and that they are not aliased. Computed fields will not be filled in mapped objects.

Parameters:

resultSetFuture - the ResultSetFuture to map.

Returns:

the mapped result set future. Note that the returned mapped result set will encapsulate the result set returned by resultSetFuture and so consuming results from this returned mapped result set will consume results from that result set and vice-versa.

mapAliased

@Deprecated
public Result<T> mapAliased(ResultSet resultSet)

Deprecated. you no longer need to specify whether a result set is aliased, it will be detected automatically. Use map(ResultSet) instead of this method.

setDefaultSaveOptions

public void setDefaultSaveOptions(Mapper.Option... options)

Set the default save Mapper.Option for this object mapper, that will be used in all save operations unless overridden. Refer to save(Object, Option...))} to check available save options.

Parameters:

options - the options to set. To reset, use resetDefaultSaveOptions().

resetDefaultSaveOptions

public void resetDefaultSaveOptions()

Reset the default save options for this object mapper.

setDefaultGetOptions

public void setDefaultGetOptions(Mapper.Option... options)

Set the default get Mapper.Option for this object mapper, that will be used in all get operations unless overridden. Refer to get(Object...) )} to check available get options.

Parameters:

options - the options to set. To reset, use resetDefaultGetOptions().

resetDefaultGetOptions

public void resetDefaultGetOptions()

Reset the default save options for this object mapper.

setDefaultDeleteOptions

public void setDefaultDeleteOptions(Mapper.Option... options)

Set the default delete Mapper.Option for this object mapper, that will be used in all delete operations unless overridden. Refer to delete(Object...) )} to check available delete options.

Parameters:

options - the options to set. To reset, use resetDefaultDeleteOptions().

resetDefaultDeleteOptions

public void resetDefaultDeleteOptions()

Reset the default delete options for this object mapper.