sirius.db.mixing

Class BaseMapper<B extends BaseEntity<?>,C extends Constraint,Q extends Query<?,? extends B,C>>

java.lang.Object

sirius.db.mixing.BaseMapper<B,C,Q>

Type Parameters:

B - the type of entities supported by this mapper

C - the type of constraints supported by this mapper

Q - the type of queries supported by this mapper

Direct Known Subclasses:

Elastic, Mango, OMA

public abstract class BaseMapper<B extends BaseEntity<?>,C extends Constraint,Q extends Query<?,? extends B,C>>
extends Object

Declares the common functionality of a mapper which is responsible for storing and loading entities to and from a database.

Field Summary

Fields

Modifier and Type	Field and Description
protected Mixing	mixing
static String	VERSION Contains the name of the version column used for optimistic locking.

Constructor Summary

Constructors

Constructor and Description
BaseMapper()

Method Summary

Modifier and Type	Method and Description
protected abstract void	createEntity(B entity, EntityDescriptor ed) Creates a new entity in the underlying database.
<E extends B> void	delete(E entity) Deletes the given entity from the database.
protected abstract void	deleteEntity(B entity, boolean force, EntityDescriptor ed) Deletes the give entity from the database.
abstract FilterFactory<C>	filters() Returns the filter factory which is used by this mapper.
<E extends B> Optional<E>	find(Class<E> type, Object id, ContextInfo... info) Performs a database lookup to select the entity of the given type with the given id.
protected abstract <E extends B> Optional<E>	findEntity(E entity)
protected abstract <E extends B> Optional<E>	findEntity(Object id, EntityDescriptor ed, Function<String,sirius.kernel.commons.Value> context) Tries to find the entity with the given id.
<E extends B> E	findOrFail(Class<E> type, Object id, ContextInfo... info) Tries to find(Class, Object, ContextInfo...) the entity with the given id.
<E extends B> void	forceDelete(E entity) Deletes the given entity from the database even if it is Versioned and was concurrently modified.
boolean	hasValidationWarnings(B entity) Determines if the given entity has validation warnings.
<E extends B> void	override(E entity) Performs an update(BaseEntity) of the entity, without checking for concurrent modifications.
protected <E extends B> void	performDelete(E entity, boolean force)
protected <E extends B> void	performUpdate(E entity, boolean force)
<E extends B> E	refreshOrFail(E entity) Tries to fetch a fresh (updated) instance of the given entity from the database.
<E extends B> Optional<E>	resolve(String name, ContextInfo... info) Tries to resolve the BaseEntity.getUniqueName() into an entity.
B	resolveOrFail(String name, ContextInfo... info) Tries to resolve(String, ContextInfo...) the given name into an entity.
abstract <E extends B> Q	select(Class<E> type) Creates a query for the given type.
<E extends B> void	tryDelete(E entity) Tries to delete the entity from the database.
<E extends B> E	tryRefresh(E entity) Tries to fetch a fresh (updated) instance of the given entity from the database.
<E extends B> void	tryUpdate(E entity) Tries to perform an update(BaseEntity) of the given entity.
<E extends B> void	update(E entity) Writes the contents of the given entity to the database.
protected abstract void	updateEntity(B entity, boolean force, EntityDescriptor ed) Updates an existing entity in the underlying database.
List<String>	validate(B entity) Executes all validation handlers on the given entity.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final String VERSION

Contains the name of the version column used for optimistic locking.

See Also:

Constant Field Values

mixing

protected Mixing mixing

Constructor Detail

BaseMapper

public BaseMapper()

Method Detail

update

public <E extends B> void update(E entity)

Writes the contents of the given entity to the database.

If the entity is not persisted yet, we perform an insert. If the entity does exist, we only update those fields, which were changed since they were last read from the database.

While this provides the best performance and circumvents update conflicts, it does not guarantee strong consistency as the fields in the database might have partially changes. If this behaviour is unwanted, Versioned can be used which will turn on Optimistic Locking and prevent these conditions.

Type Parameters:

E - the generic type of the entity

Parameters:

entity - the entity to write to the database

tryUpdate

public <E extends B> void tryUpdate(E entity)
                             throws OptimisticLockException

Tries to perform an update(BaseEntity) of the given entity.

If the entity is Versioned and the entity was modified already elsewhere, an OptimisticLockException will be thrown, which can be used to trigger a retry.

Type Parameters:

E - the generic type of the entity

Parameters:

entity - the entity to update

Throws:

OptimisticLockException - in case of a concurrent modification

override

public <E extends B> void override(E entity)

Performs an update(BaseEntity) of the entity, without checking for concurrent modifications.

Concurrent modifications by other users will simply be ignored and overridden.

Type Parameters:

E - the generic type of the entity

Parameters:

entity - the entity to update

performUpdate

protected <E extends B> void performUpdate(E entity,
                                           boolean force)
                                    throws OptimisticLockException

Throws:

OptimisticLockException

createEntity

protected abstract void createEntity(B entity,
                                     EntityDescriptor ed)
                              throws Exception

Creates a new entity in the underlying database.

Parameters:

entity - the entity to create

ed - the descriptor of the entity

Throws:

Exception - in case of an database error

updateEntity

protected abstract void updateEntity(B entity,
                                     boolean force,
                                     EntityDescriptor ed)
                              throws Exception

Updates an existing entity in the underlying database.

Parameters:

entity - the entity to update

force - ture if the update is forced and optimistic locking must be disabled

ed - the descriptor of the entity

Throws:

Exception - in case of an database error

delete

public <E extends B> void delete(E entity)

Deletes the given entity from the database.

If the entity is Versioned and concurrently modified elsewhere, an exception is thrown.

Type Parameters:

E - the generic entity type

Parameters:

entity - the entity to delete

tryDelete

public <E extends B> void tryDelete(E entity)
                             throws OptimisticLockException

Tries to delete the entity from the database.

If the entity is Versioned and concurrently modified elsewhere, an OptimisticLockException is thrown.

Type Parameters:

E - the generic entity type

Parameters:

entity - the entity to delete

Throws:

OptimisticLockException - if the entity was concurrently modified

forceDelete

public <E extends B> void forceDelete(E entity)

Deletes the given entity from the database even if it is Versioned and was concurrently modified.

Type Parameters:

E - the generic entity type

Parameters:

entity - the entity to delete

performDelete

protected <E extends B> void performDelete(E entity,
                                           boolean force)
                                    throws OptimisticLockException

Throws:

OptimisticLockException

deleteEntity

protected abstract void deleteEntity(B entity,
                                     boolean force,
                                     EntityDescriptor ed)
                              throws Exception

Deletes the give entity from the database.

Parameters:

entity - the entity to delete

force - true if the delete is forced and optimistic locking must be disabled

ed - the descriptor of the entity

Throws:

Exception - in case of an database error

hasValidationWarnings

public boolean hasValidationWarnings(B entity)

Determines if the given entity has validation warnings.

Parameters:

entity - the entity to check

Returns:

true if there are validation warnings, false otherwise

validate

public List<String> validate(B entity)

Executes all validation handlers on the given entity.

Parameters:

entity - the entity to validate

Returns:

a list of all validation warnings

find

public <E extends B> Optional<E> find(Class<E> type,
                                      Object id,
                                      ContextInfo... info)

Performs a database lookup to select the entity of the given type with the given id.

Type Parameters:

E - the generic type of the entity to select

Parameters:

type - the type of entity to select

id - the id (which can be either a long, Long or String) to select

info - info provided as context (e.g. routing infos for Elasticsearch)

Returns:

the entity wrapped as Optional or an empty optional if no entity with the given id exists

findEntity

protected abstract <E extends B> Optional<E> findEntity(Object id,
                                                        EntityDescriptor ed,
                                                        Function<String,sirius.kernel.commons.Value> context)
                                                 throws Exception

Tries to find the entity with the given id.

Type Parameters:

E - the effective type of the entity

Parameters:

id - the id of the entity to find

ed - the descriptor of the entity to find

context - the advanced search context which can be populated using ContextInfo in find(Class, Object, ContextInfo...)

Returns:

the entity wrapped as optional or an empty optional if the entity was not found

Throws:

Exception - in case of a database error

findOrFail

public <E extends B> E findOrFail(Class<E> type,
                                  Object id,
                                  ContextInfo... info)

Tries to find(Class, Object, ContextInfo...) the entity with the given id.

If no entity is found, an exception is thrown.

Type Parameters:

E - the generic type of the entity to select

Parameters:

type - the type of entity to select

id - the id (which can be either a long, Long or String) to select

info - info provided as context (e.g. routing infos for Elasticsearch)

Returns:

the entity with the given id

Throws:

sirius.kernel.health.HandledException - if no entity with the given ID was present

resolve

public <E extends B> Optional<E> resolve(String name,
                                         ContextInfo... info)

Tries to resolve the BaseEntity.getUniqueName() into an entity.

Type Parameters:

E - the generic parameter of the entity to resolve

Parameters:

name - the name of the entity to resolve

info - info provided as context (e.g. routing infos for Elasticsearch)

Returns:

the resolved entity wrapped as Optional or an empty optional if no such entity exists

resolveOrFail

public B resolveOrFail(String name,
                       ContextInfo... info)

Tries to resolve(String, ContextInfo...) the given name into an entity.

Parameters:

name - the name of the entity to resolve

info - info provided as context (e.g. routing infos for Elasticsearch)

Returns:

the resolved entity

Throws:

sirius.kernel.health.HandledException - if the given name cannot be resolved into an entity

tryRefresh

public <E extends B> E tryRefresh(E entity)

Tries to fetch a fresh (updated) instance of the given entity from the database.

If the entity does no longer exist, the given instance is returned.

Type Parameters:

E - the generic type of the entity

Parameters:

entity - the entity to refresh

Returns:

a new instance of the given entity with the most current data from the database or the original entity, if the entity does no longer exist in the database.

findEntity

protected abstract <E extends B> Optional<E> findEntity(E entity)

refreshOrFail

public <E extends B> E refreshOrFail(E entity)

Tries to fetch a fresh (updated) instance of the given entity from the database.

If the entity does no longer exist, an exception will be thrown.

Type Parameters:

E - the generic type of the entity

Parameters:

entity - the entity to refresh

Returns:

a new instance of the given entity with the most current data from the database.

Throws:

sirius.kernel.health.HandledException - if the entity no longer exists in the database.

select

public abstract <E extends B> Q select(Class<E> type)

Creates a query for the given type.

Type Parameters:

E - the generic type of entities to be returned

Parameters:

type - the type of entities to query for.

Returns:

a query used to search for entities of the given type

filters

public abstract FilterFactory<C> filters()

Returns the filter factory which is used by this mapper.

Returns:

the filter factory used by this mapper