InstanceService¶
-
public interface
InstanceService
¶ The
InstanceService
interface, defines methods responsible for executing actions on the instances of the entity.
Methods¶
countHistoryRecords¶
countRecords¶
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 throworg.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¶
countTrashRecords¶
deleteAllInstances¶
deleteInstance¶
deleteSelectedInstances¶
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 throworg.motechproject.mds.exception.entity.EntityNotFoundException
andorg.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
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 throwsorg.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