org.openmrs.logic.datasource

Interface LogicDataSource

public interface LogicDataSource

Provides data to the logic service engine. Each data source is responsible for exposing a set of keys to the logic service and delivering results to the logic service engine upon request. Requests to the data source reference the evaluation context, a patient cohort, and criteria.

• Context. The evaluation context (org.openmrs.logic.LogicContext) defines the index date and any global parameters. All criteria should be applied as if the current date is the index date, allowing for retrospective queries.
• Cohort. The list of patients for which results should be returned
• Criteria. A chain of criteria to be applied to the results, passed to the data source, since each data source knows how to apply these criteria in the most efficient matter.

Keys (and their subsequent results) work best if they are well documented and maximize the re-use of data. For example, consider a data source that has access to a historical listing of pharmacy visits for patients. For each visit to the name of the pharmacy, the date of the visit and the number of prescriptions filled at that visit are known. You might want to make a key for each attribute, e.g.

• pharmacy — returns a text result with the name of the pharmacy
• visit date — returns a date result with the date of the pharmacy visit
• number of prescriptions

A consumer of the logic service could then use

 Context.getLogicService().eval(myPatient, "@pharmacy visit.pharmacy");
 

to get a list of the names of pharamacies visited by the patient. However, this limits the ways we can use the result. On the other hand, consider defining the key:

• visit — returns a text result with the result date equal to the pharmacy visit date, the text value equal to the name of the pharmacy, and the numeric result overloaded with the number of prescriptions filled at the pharmacy visit.

Now a consumer of the logic service can use the same result in several different ways:

 
 Result result = Context.getLogicService().eval(myPatient, "@pharmacy visit.visit");
 
 Result lastVisit = result.latest();
 
 Date dateOfVisit = result.getResultDate();
 
 String pharmacy = result.toString();
 
 int numberOfPrescriptions = result.toNumber();
 

One way to approach the design of a new data service is to avoid thinking of the individual attributes, but rather think about turning the data into the fewest number of observations (a key for each) filled with as much data as possible. Remember that you can overload values within results; however, such overloading should aim to be as intuitive as possible and well documented. New logic data sources should be documented on the OpenMRS wiki, including a description of the keys available from the data source as well as the characteristics of the result returned for each key.

Field Summary

Fields

Modifier and Type	Field and Description
static String	NAME The name by which this data source should be registered when it is loaded.

Method Summary

Modifier and Type	Method and Description
int	getDefaultTTL()
Collection<String>	getKeys()
boolean	hasKey(String key)
Map<Integer,Result>	read(LogicContext context, Cohort patients, LogicCriteria criteria) Extracts data from the data source.

Field Detail

NAME

static final String NAME

The name by which this data source should be registered when it is loaded. Implementations should override this like public static final String NAME = "person";

See Also:

Constant Field Values

Method Detail

read

Map<Integer,Result> read(LogicContext context,
                         Cohort patients,
                         LogicCriteria criteria)
                  throws LogicException

Extracts data from the data source. Actually, this function only checks for cached data and forwards all non-cached requests to its subclass(es).

Parameters:

context - the current logic context

patients - Cohort of Patient(s) for whom to perform the queries

criteria - LogicCriteria identifying which data is to be extracted

Returns:

Map of results for each patient, grouped by requested data element

Throws:

LogicException

getKeys

Collection<String> getKeys()

hasKey

boolean hasKey(String key)

getDefaultTTL

int getDefaultTTL()