InstanceService¶

public interface InstanceService¶: The InstanceService interface, defines methods responsible for executing actions on the instances of the entity.

Methods¶

countHistoryRecords¶

long countHistoryRecords(Long entityId, Long instanceId)¶

Returns total count of historical revisions, for the given instance. Current revision is not included in the count.

Parameters:	entityId – id of the entity instanceId – id of the instance
Returns:	total count of historical revisions

countRecords¶

long countRecords(Long entityId)¶

Gets a total number of instances, for the given entity.

Parameters:	entityId – id of the entity
Returns:	number of instances

countRecordsByLookup¶

long countRecordsByLookup(Long entityId, String lookupName, Map<String, Object> lookupMap)¶

Retrieves total count of the instances, that match given lookup criteria. Throws org.motechproject.mds.exception.lookup.LookupNotFoundException if lookup of the given name does not exist for the given entity. It will also throw org.motechproject.mds.exception.lookup.LookupExecutionException if lookup parameters do not match their definition.

Parameters:	entityId – id of the entity lookupName – name of the lookup lookupMap – map, containing lookup parameters with their respective values
Returns:	total count, of the instances that match lookup criteria

countRecordsWithFilters¶

long countRecordsWithFilters(Long entityId, Filters filters)¶

Retrieves total count of the instances, that match given filter criteria.

Parameters:	entityId – id of the entity filters – filters to use
Returns:	total count, of the instances that match filter criteria

countTrashRecords¶

long countTrashRecords(Long entityId)¶

Returns total count of the instances of the given entity, placed in trash. This will only consider instances, that have been moved to trash on the given entity schema.

Parameters:	entityId – id of the entity
Returns:	count of instances, placed in trash

deleteAllInstances¶

void deleteAllInstances(Long entityId)¶

Removes all instances from MDS. Depending on the settings, it will either be moved to trash or deleted permanently.

Parameters:	entityId – id of the entity

deleteInstance¶

void deleteInstance(Long entityId, Long instanceId)¶

Removes an instance from MDS. Depending on the settings, it will either be moved to trash or deleted permanently.

Parameters:	entityId – id of the entity instanceId – id of the instance

deleteSelectedInstances¶

void deleteSelectedInstances(Long entityId, List<Long> instanceIds)¶

Removes selected instances from MDS. Depending on the settings, it will either be moved to trash or deleted permanently.

Parameters:	entityId – id of the entity instanceIds – list of ids of the instances

getEntityFields¶

List<FieldDto> getEntityFields(Long entityId)¶

Retrieves all fields of the entity. This will not include draft fields, created, modified or deleted by the current user. Throws org.motechproject.mds.exception.entity.EntityNotFoundException, if entity of the given id does not exist.

Parameters:	entityId – id of the entity
Returns:	all fields of the entity

getEntityInstance¶

EntityRecord getEntityInstance(Long entityId, Long instanceId)¶

Retrieves an instance of the given entity, by its id. If there’s no instance of such id, for the given entity, it throws org.motechproject.mds.exception.object.ObjectNotFoundException.

Parameters:	entityId – id of the entity instanceId – id of the instance
Returns:	an instance representation

getEntityRecords¶

List<BasicEntityRecord> getEntityRecords(Long entityId, QueryParams queryParams)¶

Returns all instances of the entity, that the current user has access to. Additionally, allows to tamper the results, using query parameters (eg. to limit the number of retrieves records). Throws org.motechproject.mds.exception.entity.EntityNotFoundException, if entity of the given id does not exist.

Parameters:	entityId – id of the entity queryParams – query parameters to use, retrieving instances
Returns:	a list of instances

getEntityRecords¶

List<BasicEntityRecord> getEntityRecords(Long entityId)¶

Returns all instances of the entity, that the current user has access to. Throws org.motechproject.mds.exception.entity.EntityNotFoundException, if entity of the given id does not exist.

Parameters:	entityId – id of the entity
Returns:	a list of instances

getEntityRecordsFromLookup¶

List<BasicEntityRecord> getEntityRecordsFromLookup(Long entityId, String lookupName, Map<String, Object> lookupMap, QueryParams queryParams)¶

Retrieves and executes a lookup of the given name, from the given entity. Additionally, allows to tamper the results, using query parameters (eg. to limit the number of retrieves records). It will throw org.motechproject.mds.exception.lookup.LookupExecutionException in case the provided lookup parameters do not match the lookup definition or if the execution could not be performed for any other reason. It will also throw org.motechproject.mds.exception.entity.EntityNotFoundException and org.motechproject.mds.exception.lookup.LookupNotFoundException if entity of the given id or lookup of the given name does not exist.

Parameters:	entityId – id of the entity lookupName – name of the lookup lookupMap – map, containing lookup parameters with their respective values queryParams – query parameters to use, retrieving instances
Returns:	a list of instances, retrieved using the given lookup

getEntityRecordsWithFilter¶

List<BasicEntityRecord> getEntityRecordsWithFilter(Long entityId, Filters filters, QueryParams queryParams)¶

Retrieves all instances of the given entity, that match criteria, specified in the provided filters. Additionally, allows to tamper the results, using query parameters (eg. to limit the number of retrieves records). It will throw org.motechproject.mds.exception.entity.EntityNotFoundException when entity of given id does not exist.

Parameters:	entityId – id of the entity filters – filters to use, retrieving instances queryParams – query parameters to use, retrieving instances
Returns:	a list of instances, matching given filters

getHistoryRecord¶

HistoryRecord getHistoryRecord(Long entityId, Long instanceId, Long historyId)¶

Retrieves a single, historical revision of an instance, by its id.

Parameters:	entityId – id of the entity instanceId – id of the instance historyId – id of the historical revision
Returns:	the historical revision of the instance

getInstanceField¶

Object getInstanceField(Long entityId, Long instanceId, String fieldName)¶

Retrieves value of a single field of an instance. Throws org.motechproject.mds.exception.entity.EntityNotFoundException if entity of given id does not exist.

Parameters:	entityId – id of the entity instanceId – id of the instance fieldName – name of the field to retrieve
Throws:	InstanceNotFoundException – if instance with the given id does not exist
Returns:	value of the field

getInstanceFields¶

List<FieldInstanceDto> getInstanceFields(Long entityId, Long instanceId)¶

Returns field definitions of the given entity, assigned to the given instance. Throws org.motechproject.mds.exception.entity.EntityNotFoundException if entity of the given id does not exist.

Parameters:	entityId – id of the entity instanceId – id of the instance
Returns:	a list of field definitions

getInstanceHistory¶

List<BasicHistoryRecord> getInstanceHistory(Long entityId, Long instanceId, QueryParams queryParams)¶

Retrieves a list of historical revisions for the given instance. Current revision will not be a part of the result. Additionally, allows to tamper the results, using query parameters (eg. to limit the number of retrieves records).

Parameters:	entityId – id of the entity instanceId – id of the instance queryParams – query parameters to use, retrieving instances
Returns:	a list of historical revisions for the instance

getInstanceValueAsRelatedField¶

FieldRecord getInstanceValueAsRelatedField(Long entityId, Long fieldId, Long instanceId)¶

Retrieves MOTECH Data service for the class, related with the field of the given id from an entity. The service is then queried for the instance of the given id. If such instance is not found, it throws org.motechproject.mds.exception.object.ObjectNotFoundException. If such instance exists, its representation is prepared and returned.

Parameters:	entityId – id of the entity fieldId – id of the field from entity instanceId – id of the instance, from the related entity
Returns:	the related field representation

getRelatedFieldValue¶

Records<BasicEntityRecord> getRelatedFieldValue(Long entityId, Long instanceId, String fieldName, RelationshipsUpdate filter, QueryParams queryParams)¶

Returns the related field as collection, applying filtering. Allows retrieval of related fields for grids, etc.

Parameters:	entityId – the id of entity (the entity with the related field) instanceId – the id of the instance we want to retrieve the field for fieldName – the name of the related field filter – contains related fields that have been removed or added on the UI queryParams – the query params which will be used for retrieval
Returns:	the records object containing the values for the related field

getSingleTrashRecord¶

EntityRecord getSingleTrashRecord(Long entityId, Long instanceId)¶

Allows to retrieve a single instance, that has been moved to trash.

Parameters:	entityId – id of the entity instanceId – id of the instance in trash
Returns:	instance representation

getTrashRecords¶

List<BasicEntityRecord> getTrashRecords(Long entityId, QueryParams queryParams)¶

Retrieves instances of the given entity, placed in trash. This will only return instances, that have been moved to trash on the given entity schema. Additionally, allows to tamper the results, using query parameters (eg. to limit the number of retrieves records).

Parameters:	entityId – id of the entity queryParams – query parameters to use, retrieving instances from trash
Returns:	list of instances, placed in trash

newInstance¶

EntityRecord newInstance(Long entityId)¶

Prepares a new instance representation. Builds available fields and populates some of the auto-generated fields.

Parameters:	entityId – id of the entity
Returns:	the new instance representation

revertInstanceFromTrash¶

void revertInstanceFromTrash(Long entityId, Long instanceId)¶

Brings back an instance from trash. This, in fact, creates a new instance in MDS and assigns identical field values as the deleted instance, after which the deleted instance is removed permanently. Old id of the instance will not be persisted.

Parameters:	entityId – id of the entity instanceId – id of the instance in trash

revertPreviousVersion¶

void revertPreviousVersion(Long entityId, Long instanceId, Long historyId)¶

Retrieves a historical revision of an instance and attempts to revert specified instance to its previous state. It will throw org.motechproject.mds.exception.entity.EntitySchemaMismatchException if two instances are from two different schemas (meaning, that the entity has been changed at least once).

Parameters:	entityId – id of the entity instanceId – id of the instance historyId – id of the historical revision

saveInstance¶

Object saveInstance(EntityRecord entityRecord)¶

Saves the given instance representation in MDS. If the representation has the id field assigned, an update will be performed. Otherwise, it will attempt to create a new instance.

Parameters:	entityRecord – representation of the instance
Throws:	org.motechproject.mds.exception.object.ObjectNotFoundException – if the id is specified, but the instance of such id does not exist org.motechproject.mds.exception.object.ObjectUpdateException – if any problem arises while saving the instance
Returns:	Created instance

saveInstance¶

Object saveInstance(EntityRecord entityRecord, Long deleteValueFieldId)¶

Saves the given instance representation in MDS. If the representation has the id field assigned, an update will be performed. Otherwise, it will attempt to create an instance. If the id is specified, but the instance of such id does not exist, it throws org.motechproject.mds.exception.object.ObjectNotFoundException. If any problem arises while saving the the instance, it throws org.motechproject.mds.exception.object.ObjectUpdateException. This method is capable of removing the blob field values.

Parameters:	entityRecord – representation of the instance deleteValueFieldId – blob field ID, to clear the value for; it will not be effective for any other field types
Returns:	Created instance

validateNonEditableProperty¶

void validateNonEditableProperty(Long entityId)¶

Checks whether the entity with the given ID is non editable.

Parameters:	entityId – the id of the entity
Throws:	EntityInstancesNonEditableException – if the entity is non editable

verifyEntityAccess¶

void verifyEntityAccess(Long entityId)¶

Checks whether the logged in user has access to the entity with the given ID.

Parameters:	entityId – the id of the entity