EntityService

public interface EntityService

This interface provides methods related with executing actions on an entity.

See also: org.motechproject.mds.domain.Entity

Methods

abandonChanges

void abandonChanges(Long entityId)

Removes the draft data permanently.

Parameters:
  • entityId – id of the draft entity

addDisplayedFields

void addDisplayedFields(EntityDto entityDto, Map<String, Long> positions)

Adds ability to point fields that should be displayed on the data browser by default and allows to set their position on the UI. If not invoked on any field and no field has the org.motechproject.mds.annotations.UIDisplayable annotation, all the fields, except auto-generated ones will be displayed. If invoked on at least one field, all other fields will get hidden by default.

Parameters:
  • entityDto – entity representation
  • positions – a map of field names and their positions. If position is irrelevant, place -1 as entry value

addFields

void addFields(EntityDto entity, FieldDto... fields)

Adds fields to the given entity. If the field of identical name already exists in the entity definition, it will be updated. If the entity does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entity – the entity to add fields to
  • fields – fields to add or update

addFields

void addFields(EntityDto entity, Collection<FieldDto> fields)

Adds fields to the given entity. If the field of identical name already exists in the entity definition, it will be updated. If the entity does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entity – the entity to add fields to
  • fields – fields to add or update

addFields

void addFields(Long entityId, FieldDto... fields)

Adds fields to the given entity. If the field of identical name already exists in the entity definition, it will be updated. If the entity does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entityId – id of the entity to add fields to
  • fields – fields to add or update

addFields

void addFields(Long entityId, Collection<FieldDto> fields)

Adds fields to the given entity. If the field of identical name already exists in the entity definition, it will be updated. If the entity does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entityId – id of the entity to add fields to
  • fields – fields to add or update

addFilterableFields

void addFilterableFields(EntityDto entityDto, Collection<String> fieldNames)

Provides ability to point fields, for which UI should provide the ability to filter through. Note, that only several field types support filtering via UI. If a field of not supported type is marked as filterable, this will have no effect.

Parameters:
  • entityDto – entity representation
  • fieldNames – the names of the fields, that should be marked filterable

addLookups

void addLookups(EntityDto entityDto, LookupDto... lookups)

Adds or updates lookups for the given entity.

Parameters:
  • entityDto – entity representation
  • lookups – lookups to add or update

addLookups

void addLookups(EntityDto entityDto, Collection<LookupDto> lookups)

Adds or updates lookups for the given entity.

Parameters:
  • entityDto – entity representation
  • lookups – lookups to add or update

addLookups

void addLookups(Long entityId, LookupDto... lookups)

Adds or updates lookups for the given entity.

Parameters:
  • entityId – id of an entity
  • lookups – lookups to add or update

addLookups

void addLookups(Long entityId, Collection<LookupDto> lookups)

Adds or updates lookups for the given entity.

Parameters:
  • entityId – id of an entity
  • lookups – lookups to add or update

addNonEditableFields

void addNonEditableFields(EntityDto entityDto, Map<String, Boolean> nonEditableFields)

Provides ability to point fields that should be non-editable via UI.

Parameters:
  • entityDto – entity representation
  • nonEditableFields – a map of the non-editable field names and their display values.

commitChanges

List<String> commitChanges(Long entityId)

Retrieves a draft and attempts to update actual entity, according to the changes present in the draft. The username, for which the draft should be retrieved, will be determined on the current security context. If the draft is outdated, which means that somebody else has already updated the entity, the org.motechproject.mds.exception.entity.EntityChangedException will be thrown. If the draft is not outdated, a validation will be performed to determine whether the changes are valid and can be applied, and if so the changes will be made and the draft will get deleted.

Parameters:
  • entityId – id of the draft or actual entity
Returns:

a list of modules, affected by the commit

commitChanges

List<String> commitChanges(Long entityId, String changesOwner)

Retrieves a draft for a given user and attempts to update actual entity, according to the changes present in the draft. If the draft is outdated, which means that somebody else has already updated the entity, the org.motechproject.mds.exception.entity.EntityChangedException will be thrown. If the draft is not outdated, a validation will be performed to determine whether the changes are valid and can be applied, and if so the changes will be made and the draft will get deleted.

Parameters:
  • entityId – id of the draft or actual entity
Returns:

a list of modules, affected by the commit

createEntity

EntityDto createEntity(EntityDto entityDto)

Creates an entity and adds default fields, provided the entity does not contain them already (from inheritance). It will throw org.motechproject.mds.exception.entity.EntityAlreadyExistException if an entity of identical class name already exists.

Parameters:
  • entityDto – representation of an entity to construct from.
Returns:

representation of a created entity.

deleteEntity

void deleteEntity(Long entityId)

Removes the entity with the given id. This will also remove all drafts associated with the deleted entity.

Parameters:
  • entityId – The id of an entity

findEntitiesByPackage

List<EntityDto> findEntitiesByPackage(String packageName)

Retrieves entities for the given package

Parameters:
  • packageName – the package name
Returns:

A list of entities

findEntityFieldByName

FieldDto findEntityFieldByName(Long entityId, String name)

Retrieves a field by name. This will not include draft fields.

Parameters:
  • entityId – id of an entity
  • name – name of the field
Returns:

Field of the given name for given entity id

findFieldByName

FieldDto findFieldByName(Long entityId, String name)

Retrieves a field by name. This will be able to find any draft fields, that the current user has added, deleted or modified in any way.

Parameters:
  • entityId – id of an entity
  • name – name of the field
Returns:

Actual or draft field of the given name for given entity id

getAdvancedSettings

AdvancedSettingsDto getAdvancedSettings(Long entityId)

Retrieves advanced settings for an entity. This will include any draft changes that the current user has made to the entity.

Parameters:
  • entityId – id of an entity
Returns:

advanced settings for the entity

getAdvancedSettings

AdvancedSettingsDto getAdvancedSettings(Long entityId, boolean committed)

Retrieves advanced settings for an entity.

Parameters:
  • entityId – id of an entity
  • committed – a flag indicating whether the settings should come from actual entity or a draft
Returns:

advanced settings for the entity

getCurrentSchemaVersion

Long getCurrentSchemaVersion(String entityClassName)

Retrieves current version of the entity schema. The version gets incremented each time the entity gets updated. It throws org.motechproject.mds.exception.entity.EntityNotFoundException if entity of given class name does not exist.

Parameters:
  • entityClassName – fully qualified class name of the entity
Returns:

schema version for the entity

getDisplayFields

List<FieldDto> getDisplayFields(Long entityId)

Retrieves all fields of an entity, that are marked as displayable. By default, these are all the fields that aren’t auto-generated by the MDS. The displayable fields can be adjusted using annotations or addDisplayedFields(org.motechproject.mds.dto.EntityDto,java.util.Map) method. If entity of given id does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException.

Parameters:
  • entityId – id of an entity
Returns:

All fields of the entity, that are marked as displayable

getEntity

EntityDto getEntity(Long entityId)

Returns an entity of the given id. If an entity with given id does not exist, it will return null.

Parameters:
  • entityId – The id of an entity.
Returns:

Entity with given id or null.

getEntityByClassName

EntityDto getEntityByClassName(String className)

Retrieves entity by the className parameter

Parameters:
  • className – the className of an entity
Returns:

Entity with the given className

getEntityDraft

EntityDraft getEntityDraft(Long entityId)

Retrieves the entity draft. The user, for which the draft should be obtained, will be determined on the current security context.

Parameters:
  • entityId – id of the draft or actual entity
Returns:

Entity draft for the user

getEntityDraft

EntityDraft getEntityDraft(Long entityId, String username)

Retrieves the entity draft for the given user.

Parameters:
  • entityId – id of the draft or actual entity
Returns:

Entity draft for the user

getEntityFieldById

FieldDto getEntityFieldById(Long entityId, Long fieldId)

Retrieves a field by id. This will not include draft fields.

Parameters:
  • entityId – id of an entity
  • fieldId – id of the field
Returns:

Field of the given name for given entity id

getEntityFields

List<FieldDto> getEntityFields(Long entityId)

Retrieves a list of all fields for the given entity. This will not include any draft fields.

Parameters:
  • entityId – id of an entity
Returns:

a list of fields for an entity

getEntityFieldsByClassName

List<FieldDto> getEntityFieldsByClassName(String className)

Retrieves a list of all fields for the given entity class name. This will not include any draft fields.

Parameters:
  • className – the entity class name
Returns:

a list of fields for the entity

getEntityFieldsByClassNameForUI

List<FieldDto> getEntityFieldsByClassNameForUI(String className)

Retrieves a list of all fields for the given entity class name. This will not include any draft fields. Since this for the UI, additional display options such as all combobox values will be added to the resultant fields.

Parameters:
  • className – the entity class name
Returns:

a list of fields for the entity

getEntityFieldsForUI

List<FieldDto> getEntityFieldsForUI(Long entityId)

Returns the list of fields for the entity, ready to use for the UI. Combobox fields will contain all available options.

Parameters:
  • entityId – the id of the entity
Returns:

the list of fields for the UI

getEntityForEdit

EntityDto getEntityForEdit(Long entityId)

Retrieves a draft entity representation, connected to the currently logged in user.

Parameters:
  • entityId – id of an entity to retrieve
Returns:

draft entity representation

getEntityLookups

List<LookupDto> getEntityLookups(Long entityId)

Retrieves a list of all lookups for the given entity. This will not include draft lookups.

Parameters:
  • entityId – id of an entity
Returns:

a list of lookups for an entity

getFields

List<FieldDto> getFields(Long entityId)

Retrieves a list of all fields for the given entity. This will include draft fields, that the current user has added, deleted or modified in any way.

Parameters:
  • entityId – id of an entity
Returns:

a list of fields for an entity

getLookupByName

LookupDto getLookupByName(Long entityId, String lookupName)

Retrieves lookup representation by entity id and lookup name. If entity of given id does not exists, it throws org.motechproject.mds.exception.entity.EntityNotFoundException. If there is no lookup of such name in the entity, it returns null.

Parameters:
  • entityId – id of an entity
  • lookupName – name of a lookup to retrieve
Returns:

Lookup representation, or null if a lookup of given name does not exist

getLookupFieldsMapping

Map<String, FieldDto> getLookupFieldsMapping(Long entityId, String lookupName)

Returns a map which contains lookup fields. Fields may come from related entities. Map keys represents lookup fields name which can contains a dot operator(for example relationshipField.id).

Parameters:
  • entityId – The id of an entity
  • lookupName – name of a lookup
Returns:

a map of lookup fields.

getSchema

SchemaHolder getSchema()

Retrieves the current MDS schema - entities, fields, lookups, advanced settings etc. This schema can be processed outside of a transacton.

Returns:the current MDS schema

incrementVersion

void incrementVersion(Long entityId)

Increments the version of the entity.

Parameters:
  • entityId – id of an entity
Throws:

listEntities

List<EntityDto> listEntities()

Returns all entities, that are currently stored in the database. This will not return Entity drafts and Entity audit. It will also not perform any security checks on the entities.

Returns:A list of all entities.

listEntities

List<EntityDto> listEntities(boolean withSecurityCheck)

Returns all entities, that are currently stored in the database. Allows to filter out entities, that the current user does not have access to. This will not return Entity drafts and Entity audit.

Parameters:
  • withSecurityCheck – set to true, if you wish to filter out entities, that current user does not have access to
Returns:

A list of all entities, that currently logged user has got access to.

listEntitiesByBundle

List<EntityDto> listEntitiesByBundle(String bundleSymbolicName)

Returns all entities of the bundle with the given name. This will not return Entity drafts and Entity audit. It will also not perform any security checks on the entities.

Parameters:
  • bundleSymbolicName – the symbolic name of the bundle
Returns:

A list of the bundle entities.

listWorkInProgress

List<EntityDto> listWorkInProgress()

Retrieves a list of all entities, that currently authenticated user has applied changes to.

Returns:A list of entities, modified by the user

safeGetAdvancedSettingsCommitted

AdvancedSettingsDto safeGetAdvancedSettingsCommitted(String entityClassName)

Returns the advanced settings for the entity with the given class name. This method is safe, meaning that it will return null for non-existent entities.

Parameters:
  • entityClassName – the class name of the entity
Returns:

the advanced settings of the entity, or null if the entity does not exist

saveDraftEntityChanges

DraftResult saveDraftEntityChanges(Long entityId, DraftData draftData, String username)

Creates, updates or removes draft data for the user. If there’s no draft for given user, it will be created. If a draft already exists, the existing draft will get updated.

Parameters:
  • entityId – id of an actual entity
  • draftData – data representing changes to the entity
  • username – the username to whom draft will be assigned
Returns:

The result, indicating whether changes have been made and whether a draft is outdated

saveDraftEntityChanges

DraftResult saveDraftEntityChanges(Long entityId, DraftData draftData)

Creates, updates or removes draft data. The username will be retrieved from the existing security context. If there’s no draft for given user, it will be created. If a draft already exists, the existing draft will get updated.

Parameters:
  • entityId – id of an actual entity
  • draftData – data representing changes to the entity
Returns:

The result, indicating whether changes have been made and whether a draft is outdated

updateDraft

EntityDto updateDraft(Long entityId)

Updates draft entity for the user, determined on the current security context. The update changes the parent entity of the draft to the latest version, which may happen if another user commits changes to the entity.

Parameters:
  • entityId – id of an entity
Returns:

updated draft entity

updateMaxFetchDepth

void updateMaxFetchDepth(Long entityId, Integer maxFetchDepth)

Updated the max fetch depth for a given entity. That fetch depth will be passed to the fetch plan of the persistence manager for that entity.

Parameters:
  • entityId – the id of the entity to update
  • maxFetchDepth – the new maximum fetch depth

updateRestOptions

void updateRestOptions(Long entityId, RestOptionsDto restOptionsDto)

Updates rest options for the given entity. If entity of the given id does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entityId – id of an entity
  • restOptionsDto – new rest options

updateSecurityOptions

void updateSecurityOptions(Long entityId, SecurityMode securityMode, Set<String> securityMembers, SecurityMode readOnlySecurityMode, Set<String> readOnlySecurityMembers)

Updates security options for the given entity. If entity of the given id does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entityId – id of an entity
  • securityMode – new security mode
  • securityMembers – set of user or role names
  • readOnlySecurityMode – new read only security mode
  • readOnlySecurityMembers – set of user or role names for read only security mode

updateTracking

void updateTracking(Long entityId, TrackingDto trackingDto)

Updates audit settings for the given entity. If entity of the given id does not exist, it throws org.motechproject.mds.exception.entity.EntityNotFoundException

Parameters:
  • entityId – id of an entity
  • trackingDto – new audit settings