MotechDataService

public interface MotechDataService<T>

This is a basic service interface with CRUD operations. Mainly it is used as super interface to create service interface related with the given entity schema in org.motechproject.mds.builder.EntityInfrastructureBuilder but it can be also used by other service interfaces inside this package.

Parameters:

• <T> – the type of entity schema.

Methods

count

long count()

Gets the total number of instances.

Returns:number of instances

countForFilters

long countForFilters(Filters filters)

Gets a total number of instances, after being filtered by the given filter.

Parameters:

• filters – filters to use

Returns:

number of filtered instances

create

T create(T object)

Creates the given instance in MDS.

Parameters:

• object – instance to create

Returns:

created instance

createOrUpdate

T createOrUpdate(T object)

Updates the given instance in MDS if it exists (checks the presence of the instances id to verify that) or creates a new one if it doesn’t.

Parameters:

• object – instance to update or create

Returns:

updated or created instance

delete

void delete(T object)

Deletes given instance from MDS.

Parameters:

• object – instance to delete

delete

void delete(String primaryKeyName, Object value)

Deletes instance from MDS, by its primary key value.

Parameters:

• primaryKeyName – datastore primary key name
• value – value of the primary key

deleteAll

void deleteAll()

Removes all instances of type {@param } from MDS.

deleteById

void deleteById(long id)

Deletes instance from MDS, by its id.

Parameters:

• id – id of the instance to delete.

detachedCopy

T detachedCopy(T object)

Returns detached copy of the given object

Parameters:

• object – the object to be detached

Returns:

the detached copy of the given object

detachedCopyAll

List<T> detachedCopyAll(List<T> objects)

Returns detached copies list of the given objects

Parameters:

• objects – the objects to be detached

Returns:

the detached copies list of the given objects

doInTransaction

<R> R doInTransaction(TransactionCallback<R> transactionCallback)

Allows to wrap several instructions into a single transaction. Developers should implement the TransactionCallback interface and override the TransactionCallback.doInTransaction(org.springframework.transaction.TransactionStatus) method with whatever should be done in the transaction.

Parameters:

• transactionCallback – implementation of the TransactionCallback
• <R> – type that should be returned from the transaction

Returns:

anything of type {@param }. Left to the developer, implementing the transaction

evictAllCache

void evictAllCache()

Evicts all cached entities. This affects all entities.

evictCacheForInstance

void evictCacheForInstance(T instance)

Evicts cache for a single entity instance.

Parameters:

• instance – the instance to clear the cache for

evictEntityCache

void evictEntityCache(boolean withSubclasses)

Evicts cache for the entity class of this data service.

Parameters:

• withSubclasses – if true, the cache for subclasses of the entity will be also cleared

executeQuery

<R> R executeQuery(QueryExecution<R> queryExecution)

Allows to execute custom query in MDS. Users are supposed to implement the QueryExecution interface and override its QueryExecution.execute(javax.jdo.Query,org.motechproject.mds.util.InstanceSecurityRestriction) method with their custom behaviour.

Parameters:

• queryExecution – implementation of the QueryExecution, with custom behaviour
• <R> – type that should be returned from the custom query

Returns:

anything of type {@param }. Left to the developer, implementing the custom query.

executeSQLQuery

<R> R executeSQLQuery(SqlQueryExecution<R> queryExecution)

Allows to execute custom SQL query in MDS. Users should implement the SqlQueryExecution interface and override its methods, defining their custom query.

Parameters:

• queryExecution – implementation of the SqlQueryExecution
• <R> – type that should be returned by the custom sql query

Returns:

anything of type {@param }, left to the developer, implementing the custom sql query.

filter

List<T> filter(Filters filters, QueryParams queryParams)

Retrieves all instances of type {@param } from MDS, filtered using specified filters and query params.

Parameters:

• filters – filters to use filtering instances
• queryParams – query parameters to use filtering instances

Returns:

a list of instances, filtered using specified parameters

findById

T findById(Long id)

Retrieves instance of type {@param } and given id from MDS.

Parameters:

• id – id of the instance

Returns:

instance with the given id

findByIds

List<T> findByIds(Collection<Long> ids)

Retrieves multiple instances of type {@param } and given ids from MDS. It will not fail if it is unable to find an instance for one or more IDs and will return a collection of these instances that could be found. If null is passed as keys, it will return an empty list.

Parameters:

• ids – a collection of ids to find

Returns:

a collection of instances with the given ids

findTrashInstanceById

Object findTrashInstanceById(Long trashId)

Finds a trash instance for the entity by ID.

Parameters:

• trashId – the id of the trash instance

Returns:

the instance from trash

getClassType

Class<T> getClassType()

Returns class type assigned to this service.

Returns:class type

getDetachedField

Object getDetachedField(T instance, String fieldName)

Makes instance persistent and retrieves field values from that persisted instance.

Parameters:

• instance – instance to retrieve field value from
• fieldName – name of the field to retrieve

Returns:

value from the field

getSchemaVersion

Long getSchemaVersion()

Returns the schema version for this service’s entity.

Returns:the schema version

getVersionFieldName

String getVersionFieldName()

Returns the name of the version field for this entity.

Returns:the name of the version field

recordHistory

boolean recordHistory()

Checks whether the entity for this service has history recording enabled.

Returns:true if the entity has history recording enabled, false otherwise

retrieve

T retrieve(String primaryKeyName, Object value)

Retrieves instance from MDS based on the value of the given primary key.

Parameters:

• primaryKeyName – datastore primary key name
• value – value of the primary key

Returns:

instance with the given value for the specified primary key

retrieveAll

List<T> retrieveAll()

Retrieves all instances of the {@param } type.

Returns:all instances

retrieveAll

List<T> retrieveAll(QueryParams queryParams)

Retrieves all instances of the {@param } type, that match the provided parameters.

Parameters:

• queryParams – query parameters to be used retrieving instances

Returns:

all isntances matching query parameters

revertFromTrash

T revertFromTrash(Long trashId)

Brings an instance back from trash.

Parameters:

• trashId – the id of the trash instance

Throws:

• TrashInstanceNotFoundException – if the trash instance with the given id was not found

Returns:

the brought back instance

revertToHistoricalRevision

T revertToHistoricalRevision(Long instanceId, Long historicalId)

Reverts data from a historical revision of the given instance.

Parameters:

• instanceId – the id of the instance which will be reverted
• historicalId – the id of the historical revision that we are reverting to

Throws:

• org.motechproject.mds.exception.object.ObjectNotFoundException – if entity with instanceId was not found
• HistoryInstanceNotFoundException – if the historical instance with historicalId was not found

Returns:

the reverted instance

update

T update(T object)

Updates the given instance in MDS.

Parameters:

• object – instance to update

Returns:

updated instance

updateFromTransient

T updateFromTransient(T transientObject)

Returns the persistent instance, updated with the values from the transient instance. If there’s no instance of the id from the transient instance, it will create one.

Parameters:

• transientObject – transient object, from which an update will take place

Returns:

persistent instance, updated with the values from the transient instance

updateFromTransient

T updateFromTransient(T transientObject, Set<String> fieldsToUpdate)

Returns the persistent instance, updated with the values from the transient instance. If there’s no instance of the id from the transient instance, it will create one. Only fields with the names passed to the method will be updated.

Parameters:

• transientObject – transient object, from which an update will take place
• fieldsToUpdate – set of field names that should be updated

Returns:

persistent instance, updated with the values from the transient instance