CohortService (OpenMRS 2.7.0-SNAPSHOT API)

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

CohortServiceImpl
```
public interface CohortService
extends OpenmrsService
```
API methods related to Cohorts and CohortDefinitions
- A Cohort is a list of patient ids.
- A CohortDefinition is a search strategy which can be used to arrive at a cohort. Therefore, the patients returned by running a CohortDefinition can be different depending on the data that is stored elsewhere in the database.
See Also:

Cohort

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`Cohort`	`addPatientToCohort(Cohort cohort, Patient patient)` Adds a new patient to a Cohort.
`CohortMembership`	`endCohortMembership(CohortMembership cohortMembership, Date onDate)` Ends the specified CohortMembership i.e. sets its end date to the current date
`List<Cohort>`	`getAllCohorts()` Gets all Cohorts (not including voided ones)
`List<Cohort>`	`getAllCohorts(boolean includeVoided)` Gets all Cohorts, possibly including the voided ones
`Cohort`	`getCohort(Integer id)` Gets a Cohort by its database primary key
`Cohort`	`getCohort(String name)` Deprecated. use `getCohortByName(String)`
`Cohort`	`getCohortByName(String name)` Gets a non voided Cohort by its name
`Cohort`	`getCohortByUuid(String uuid)` Get Cohort by its UUID
`CohortMembership`	`getCohortMembershipByUuid(String uuid)` Get CohortMembership by its UUID
`List<CohortMembership>`	`getCohortMemberships(Integer patientId, Date activeOnDate, boolean includeVoided)` Gets memberships for the given patient, optionally active on a specific date
`List<Cohort>`	`getCohorts(String nameFragment)` Returns Cohorts whose names match the given string.
`List<Cohort>`	`getCohortsContainingPatient(Patient patient)` Deprecated. use `getCohortsContainingPatientId(Integer)` Find all Cohorts that contain the given patient. (Not including voided Cohorts)
`List<Cohort>`	`getCohortsContainingPatientId(Integer patientId)` Find all Cohorts that contain the given patientId right now.
`void`	`notifyPatientUnvoided(Patient patient, User originallyVoidedBy, Date originalDateVoided)` NOTE: CLIENT CODE SHOULD NEVER CALL THIS METHOD.
`void`	`notifyPatientVoided(Patient patient)` NOTE: CLIENT CODE SHOULD NEVER CALL THIS METHOD.
`Cohort`	`purgeCohort(Cohort cohort)` Completely removes a Cohort from the database (not reversible)
`void`	`purgeCohortMembership(CohortMembership cohortMembership)` Removes a CohortMembership from its parent Cohort
`Cohort`	`removePatientFromCohort(Cohort cohort, Patient patient)` Deprecated. since 2.1.0 you should explicitly call either `endCohortMembership(CohortMembership, Date)` or `voidCohortMembership(CohortMembership, String)`
`Cohort`	`saveCohort(Cohort cohort)` Save a cohort to the database (create if new, or update if changed) This method will throw an exception if any patientIds in the Cohort don't exist.
`void`	`setCohortDAO(CohortDAO dao)` Sets the CohortDAO for this service to use
`Cohort`	`voidCohort(Cohort cohort, String reason)` Voids the given cohort, deleting it from the perspective of the typical end user.
`CohortMembership`	`voidCohortMembership(CohortMembership cohortMembership, String reason)` Marks the specified CohortMembership as voided

Methods inherited from interface org.openmrs.api.OpenmrsService
onShutdown, onStartup

- Method Detail
  - setCohortDAO
```
void setCohortDAO(CohortDAO dao)
```
    Sets the CohortDAO for this service to use
    
    Parameters:
    
    dao -
  - saveCohort
```
@Authorized(value={"Add Cohorts","Edit Cohorts"})
Cohort saveCohort(Cohort cohort)
                                                             throws APIException
```
    Save a cohort to the database (create if new, or update if changed) This method will throw an exception if any patientIds in the Cohort don't exist.
    
    Parameters:
    
    cohort - the cohort to be saved to the database
    
    Returns:
    
    The cohort that was passed in
    
    Throws:
    
    APIException - Should create new cohorts Should update an existing cohort
  - voidCohort
```
@Authorized(value="Delete Cohorts")
Cohort voidCohort(Cohort cohort,
                                                      String reason)
                                               throws APIException
```
    Voids the given cohort, deleting it from the perspective of the typical end user.
    
    Parameters:
    
    cohort - the cohort to delete
    
    reason - the reason this cohort is being retired
    
    Returns:
    
    The cohort that was passed in
    
    Throws:
    
    APIException - Should fail if reason is null Should fail if reason is empty Should void cohort Should not change an already voided cohort
  - purgeCohort
```
Cohort purgeCohort(Cohort cohort)
            throws APIException
```
    Completely removes a Cohort from the database (not reversible)
    
    Parameters:
    
    cohort - the Cohort to completely remove from the database
    
    Throws:
    
    APIException - Should delete cohort from database
  - getCohort
```
@Authorized(value="Get Patient Cohorts")
Cohort getCohort(Integer id)
                                                   throws APIException
```
    Gets a Cohort by its database primary key
    
    Parameters:
    
    id -
    
    Returns:
    
    the Cohort with the given primary key, or null if none exists
    
    Throws:
    
    APIException - Should get cohort by id
  - getCohortByName
```
@Authorized(value="Get Patient Cohorts")
Cohort getCohortByName(String name)
                                                         throws APIException
```
    Gets a non voided Cohort by its name
    
    Parameters:
    
    name -
    
    Returns:
    
    the Cohort with the given name, or null if none exists
    
    Throws:
    
    APIException - Should get cohort given a name Should get the nonvoided cohort if two exist with same name Should only get non voided cohorts by name
    
    Since:
    
    2.1.0
  - getCohort
```
@Deprecated
 @Authorized(value="Get Patient Cohorts")
Cohort getCohort(String name)
                                                                throws APIException
```
    Deprecated. use getCohortByName(String)
    
    Throws:
    
    APIException
  - getAllCohorts
```
@Authorized(value="Get Patient Cohorts")
List<Cohort> getAllCohorts()
                                                             throws APIException
```
    Gets all Cohorts (not including voided ones)
    
    Returns:
    
    All Cohorts in the database (not including voided ones)
    
    Throws:
    
    APIException - Should get all nonvoided cohorts in database Should not return any voided cohorts
  - getAllCohorts
```
@Authorized(value="Get Patient Cohorts")
List<Cohort> getAllCohorts(boolean includeVoided)
                                                             throws APIException
```
    Gets all Cohorts, possibly including the voided ones
    
    Parameters:
    
    includeVoided - whether or not to include voided Cohorts
    
    Returns:
    
    All Cohorts, maybe including the voided ones
    
    Throws:
    
    APIException - Should return all cohorts and voided
  - getCohorts
```
List<Cohort> getCohorts(String nameFragment)
                 throws APIException
```
    Returns Cohorts whose names match the given string. Returns an empty list in the case of no results. Returns all Cohorts in the case of null or empty input
    
    Parameters:
    
    nameFragment -
    
    Returns:
    
    list of cohorts matching the name fragment
    
    Throws:
    
    APIException - Should never return null Should match cohorts by partial name
  - getCohortsContainingPatient
```
@Deprecated
 @Authorized(value="Get Patient Cohorts")
List<Cohort> getCohortsContainingPatient(Patient patient)
                                                                                        throws APIException
```
    Deprecated. use getCohortsContainingPatientId(Integer) Find all Cohorts that contain the given patient. (Not including voided Cohorts)
    
    Parameters:
    
    patient - patient used to find the cohorts
    
    Returns:
    
    All non-voided Cohorts that contain the given patient
    
    Throws:
    
    APIException - Should not return voided cohorts Should return cohorts that have given patient
  - getCohortsContainingPatientId
```
@Authorized(value="Get Patient Cohorts")
List<Cohort> getCohortsContainingPatientId(Integer patientId)
                                                                             throws APIException
```
    Find all Cohorts that contain the given patientId right now. (Not including voided Cohorts, or ended memberships)
    
    Parameters:
    
    patientId - patient id used to find the cohorts
    
    Returns:
    
    All non-voided Cohorts that contain the given patientId
    
    Throws:
    
    APIException
  - addPatientToCohort
```
@Authorized(value="Edit Cohorts")
Cohort addPatientToCohort(Cohort cohort,
                                                            Patient patient)
                                                     throws APIException
```
    Adds a new patient to a Cohort. If the patient is not already in the Cohort, then they are added, and the Cohort is saved, marking it as changed.
    
    Parameters:
    
    cohort - the cohort to receive the given patient
    
    patient - the patient to insert into the cohort
    
    Returns:
    
    The cohort that was passed in with the new patient in it
    
    Throws:
    
    APIException - Should add a patient and save the cohort Should add a patient and insert the cohort to database Should not fail if cohort already contains patient
  - removePatientFromCohort
```
@Deprecated
 @Authorized(value="Edit Cohorts")
Cohort removePatientFromCohort(Cohort cohort,
                                                                              Patient patient)
                                                                       throws APIException
```
    Deprecated. since 2.1.0 you should explicitly call either endCohortMembership(CohortMembership, Date) or voidCohortMembership(CohortMembership, String)
    
    Removes a patient from a Cohort, by voiding their membership. (Has no effect if the patient is not in the cohort.) (This behavior is provided for consistency with the pre-2.1.0 API, which didn't track cohort membership dates.)
    
    Parameters:
    
    cohort - the cohort containing the given patient
    
    patient - the patient to remove from the given cohort
    
    Returns:
    
    The cohort that was passed in with the patient removed
    
    Throws:
    
    APIException - Should not fail if cohort doesn't contain patient Should save cohort after removing patient
  - getCohortByUuid
```
@Authorized(value="Get Patient Cohorts")
Cohort getCohortByUuid(String uuid)
```
    Get Cohort by its UUID
    
    Parameters:
    
    uuid -
    
    Returns:
    
    cohort or null Should find object given valid uuid Should return null if no object found with given uuid
  - getCohortMembershipByUuid
```
@Authorized(value="Get Patient Cohorts")
CohortMembership getCohortMembershipByUuid(String uuid)
```
    Get CohortMembership by its UUID
    
    Parameters:
    
    uuid -
    
    Returns:
    
    cohort membership or null
    
    Since:
    
    2.1.0
  - purgeCohortMembership
```
@Authorized(value="Edit Cohorts")
void purgeCohortMembership(CohortMembership cohortMembership)
```
    Removes a CohortMembership from its parent Cohort
    
    Parameters:
    
    cohortMembership - membership that will be removed from cohort
    
    Since:
    
    2.1.0
  - voidCohortMembership
```
@Authorized(value="Edit Cohorts")
CohortMembership voidCohortMembership(CohortMembership cohortMembership,
                                                                        String reason)
```
    Marks the specified CohortMembership as voided
    
    Parameters:
    
    cohortMembership - the CohortMembership to void
    
    reason - void reason
    
    Returns:
    
    the voided CohortMembership
    
    Since:
    
    2.1.0
  - endCohortMembership
```
@Authorized(value="Edit Cohorts")
CohortMembership endCohortMembership(CohortMembership cohortMembership,
                                                                       Date onDate)
```
    Ends the specified CohortMembership i.e. sets its end date to the current date
    
    Parameters:
    
    cohortMembership - the CohortMembership to end
    
    onDate - when to end the membership (optional, defaults to now)
    
    Returns:
    
    the ended CohortMembership
    
    Since:
    
    2.1.0
  - notifyPatientVoided
```
@Authorized(value="Edit Cohorts")
void notifyPatientVoided(Patient patient)
```
    NOTE: CLIENT CODE SHOULD NEVER CALL THIS METHOD. TREAT THIS AS AN INTERNAL METHOD WHICH MAY CHANGE WITHOUT WARNING. Used to notify this service that a patient has been voided, and therefore we should void all cohort memberships that refer to that patient
    
    Parameters:
    
    patient - patient that was voided Should void the membership for the patient that was passed in
    
    Since:
    
    2.1.0
  - notifyPatientUnvoided
```
@Authorized(value="Edit Cohorts")
void notifyPatientUnvoided(Patient patient,
                                                             User originallyVoidedBy,
                                                             Date originalDateVoided)
```
    NOTE: CLIENT CODE SHOULD NEVER CALL THIS METHOD. TREAT THIS AS AN INTERNAL METHOD WHICH MAY CHANGE WITHOUT WARNING. Used to notify this service that a patient has been unvoided, and therefore we should unvoid all cohort memberships that were automatically voided with the patient
    
    Parameters:
    
    patient - patient that was unvoided
    
    originallyVoidedBy -
    
    originalDateVoided - Should unvoid the membership for the patient that was passed in
    
    Since:
    
    2.1.0
  - getCohortMemberships
```
@Authorized(value="Get Patient Cohorts")
List<CohortMembership> getCohortMemberships(Integer patientId,
                                                                                     Date activeOnDate,
                                                                                     boolean includeVoided)
```
    Gets memberships for the given patient, optionally active on a specific date
    
    Parameters:
    
    patientId -
    
    activeOnDate -
    
    includeVoided -
    
    Returns:
    
    matching memberships
    
    Since:
    
    2.1.0

Interface CohortService

Method Summary

Methods inherited from interface org.openmrs.api.OpenmrsService

Method Detail

setCohortDAO

saveCohort

voidCohort

purgeCohort

getCohort

getCohortByName

getCohort

getAllCohorts

getAllCohorts

getCohorts

getCohortsContainingPatient

getCohortsContainingPatientId

addPatientToCohort

removePatientFromCohort

getCohortByUuid

getCohortMembershipByUuid

purgeCohortMembership

voidCohortMembership

endCohortMembership

notifyPatientVoided

notifyPatientUnvoided

getCohortMemberships