org.openmrs.logic

Interface LogicService

public interface LogicService

The Logic Service provides a mechanism for both registering and consuming business logic in the form of logic rules. Rules may be run against a single patient or a set of patients. Rules are registered under a unique string token. Later evaluation and/or retrieval of the rule is done through the token. Tokens can be tagged with any number of string word/phrases to simplify organization and lookup of tokens. Data source results can be obtained directly by using a token in the form @foo.bar, where foo is the logic data source name and bar is the key for that data source. For example, the token @person.gender is a direct reference to the gender key of the person logic data source.

Example Usage

 Patient myPatient = Context.getPatientService().getPatient(123);
 LogicService logicService = Context.getLogicService();
 Result result = logicService.eval(myPatient, "HIV POSITIVE");
 if (result.toBoolean()) {
        // patient is HIV positive
 }
 

Results can be derived with specific criteria as well. For example, to fetch the maximum CD4 count within the past six months:

   Result result = logicService.eval(myPatient, new LogicCriteria("CD4 COUNT")
     .within(Duration.months(6)).max();
 

or within 6 months of 11-November-2006:

   Calendar calendar = Calendar.getInstance();
   calendar.set(2006, 11, 11);
   Date targetDate = calendar.getTime();
   Result result = logicService.eval(myPatient, new LogicCriteria("CD4 COUNT")
     .asOf(targetDate).within(Duration.months(6)).max();
 

See Also:

Rule, LogicCriteria, LogicDataSource

Method Summary

Modifier and Type	Method and Description
void	addRule(String token, Rule rule) Registers a new rule with the logic service.
void	addRule(String token, String[] tags, Rule rule) Registers a new rule with the logic service, associating the tags with the given token
void	addTokenTag(String token, String tag) Adds a tag to the given token.
Map<LogicCriteria,Map<Integer,Result>>	eval(Cohort who, List<LogicCriteria> criterias) Evaluates a collection of queries for a set of patients
Map<Integer,Result>	eval(Cohort who, LogicCriteria criteria) Evaluates a query over a list of patients
Map<Integer,Result>	eval(Cohort who, LogicCriteria criteria, Map<String,Object> parameters) Evaluates a query over a list of patients
Map<Integer,Result>	eval(Cohort who, String expression) Evaluates a query over a list of patients
Map<Integer,Result>	eval(Cohort who, String expression, Map<String,Object> parameters) Evaluates a query over a list of patients
Result	eval(Integer patientId, LogicCriteria criteria) Evaluates a query for a given patient
Result	eval(Integer patientId, LogicCriteria criteria, Map<String,Object> parameters) Evaluates a query for a given patient
Map<LogicCriteria,Result>	eval(Integer patientId, Map<String,Object> parameters, LogicCriteria... criteria) Evaluates multiple LogicCriteria for a single patient.
Map<String,Result>	eval(Integer patientId, Map<String,Object> parameters, String... expressions) Evaluates multiple logic expressions for a single patient.
Result	eval(Integer patientId, String expression) Evaluates a rule for a given patient, given the token for the rule.
Result	eval(Integer patientId, String expression, Map<String,Object> parameters) Evaluates a rule for a given patient, given a token and parameters for the rule.
List<String>	getAllTokens() Fetch all known (registered) tokens
Result.Datatype	getDefaultDatatype(String token) Fetches the default datatype this token will return when fed to an eval() call.
LogicDataSource	getLogicDataSource(String name) Get a logic data source by name
Map<String,LogicDataSource>	getLogicDataSources() Get all registered logic data sources
Set<RuleParameterInfo>	getParameterList(String token) Fetches the parameters expected by a given rule
Rule	getRule(String token) Gets the rule registered under a given token
List<String>	getTags(String partialTag) Performs a partial match search for token tags among all known tokens.
List<String>	getTokens(String partialToken) Fetch all known (registered) tokens matching a given string
List<String>	getTokensWithTag(String tag) Gets all tokens associated with this tag.
Set<String>	getTokenTags(String token) Gets all tags associated with this token.
LogicCriteria	parse(String criteria) Parse a criteria String to create a new LogicCriteria.
void	removeRule(String token) Removes a rule from the logic service
void	removeTokenTag(String token, String tag) Removes a token's previously assigned tag.
void	updateRule(String token, Rule rule) Update a rule that has previously been registered

Method Detail

getAllTokens

List<String> getAllTokens()

Fetch all known (registered) tokens

Returns:

all known (registered) tokens Should return all registered token

getTokens

List<String> getTokens(String partialToken)

Fetch all known (registered) tokens matching a given string

Parameters:

partialToken - full or partial token name

Returns:

all tokens containing the given string Should return all registered token matching the input fully Should return all registered token matching the input partially Should not fail when input is null

addRule

void addRule(String token,
             Rule rule)
      throws LogicException

Registers a new rule with the logic service.

Parameters:

token - the lookup key ("token") for this rule

rule - new rule to be registered

Throws:

LogicException

See Also:

Should not fail when another rule is registered on the same token Should persist the rule and associate it with the token

addRule

void addRule(String token,
             String[] tags,
             Rule rule)
      throws LogicException

Registers a new rule with the logic service, associating the tags with the given token

Parameters:

token - the unique lookup key ("token") for this rule

tags - words or phrases associated with this token (do not need to be unique)

rule - new rule to be registered

Throws:

LogicException - Should not fail when no tags is specified Should persist rule with the tags

getRule

Rule getRule(String token)
      throws LogicException

Gets the rule registered under a given token

Parameters:

token - lookup key ("token") under which the rule is registered

Returns:

rule registered under the given token

Throws:

LogicException - if no rule by that name is found Should return Rule associated with the input token Should fail when no Rule is associated with the input token Should return ReferenceRule

updateRule

void updateRule(String token,
                Rule rule)
         throws LogicException

Update a rule that has previously been registered

Parameters:

token - lookup key ("token") for the rule to be updated

rule - new version of rule (replaces existing rule)

Throws:

LogicException - Should update Rule when another Rule is registered under the same token

removeRule

void removeRule(String token)
         throws LogicException

Removes a rule from the logic service

Parameters:

token - lookup key ("token") under which rule to be removed is registered

Throws:

LogicException - Should remove rule

eval

Result eval(Integer patientId,
            String expression)
     throws LogicException

Evaluates a rule for a given patient, given the token for the rule.

Parameters:

patientId - patient for whom the rule is to be calculated

expression - expression to be parsed and evaluated

Returns:

patient-specific result from given rule

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

See Also:

parse(String)

eval

Result eval(Integer patientId,
            String expression,
            Map<String,Object> parameters)
     throws LogicException

Evaluates a rule for a given patient, given a token and parameters for the rule.

Parameters:

patientId - patient for whom the rule is to be calculated

expression - expression to be parsed and evaluated

parameters - parameters to be passed to the rule

Returns:

patient-specific result from given rule

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

See Also:

parse(String)

eval

Result eval(Integer patientId,
            LogicCriteria criteria)
     throws LogicException

Evaluates a query for a given patient

Parameters:

patientId - patient for whom the query is to be run

criteria - question to be answered (along with the token) for the given patient

Returns:

result of query

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

eval

Result eval(Integer patientId,
            LogicCriteria criteria,
            Map<String,Object> parameters)
     throws LogicException

Evaluates a query for a given patient

Parameters:

patientId - Patient for whom the query is to be run

criteria - Criteria question to be answered (along with the token) for the given patient

parameters - Map of arguments to be passed to the rule

Returns:

Result of query

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

eval

Map<String,Result> eval(Integer patientId,
                        Map<String,Object> parameters,
                        String... expressions)
                 throws LogicException

Evaluates multiple logic expressions for a single patient. (The expressions argument is an array and comes last because using a List would give this method the same type erasure as the LogicCriteria... version.)

Parameters:

patientId - which patient to run the rules on

parameters - global parameters to be passed to all rule evaluations

expressions - expressions to be parsed and run

Returns:

results of the rule evaluations

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

See Also:

parse(String)

eval

Map<LogicCriteria,Result> eval(Integer patientId,
                               Map<String,Object> parameters,
                               LogicCriteria... criteria)
                        throws LogicException

Evaluates multiple LogicCriteria for a single patient. (The criteria argument is an array and comes last because using a List would give this method the same type erasure as the String... version.)

Parameters:

patientId - which patient to run the rules on

parameters - global parameters to be passed to all rule evaluations

criteria - what criteria to run

Returns:

results of the rule evaluations

Throws:

LogicException

Since:

1.6.3, 1.7.2, and 1.8

eval

Map<Integer,Result> eval(Cohort who,
                         String expression)
                  throws LogicException

Evaluates a query over a list of patients

Parameters:

who - patients for whom the query is to be run

expression - expression to be parsed and evaluated for each patient

Returns:

result for each patient

Throws:

LogicException

See Also:

parse(String)

eval

Map<Integer,Result> eval(Cohort who,
                         String expression,
                         Map<String,Object> parameters)
                  throws LogicException

Evaluates a query over a list of patients

Parameters:

who - patients for whom the query is to be run

expression - expression to be parsed and evaluated for each patient

parameters - parameters to be passed to the rule

Returns:

result for each patient

Throws:

LogicException

See Also:

parse(String)

eval

Map<Integer,Result> eval(Cohort who,
                         LogicCriteria criteria)
                  throws LogicException

Evaluates a query over a list of patients

Parameters:

who - patients for whom the query is to be run

criteria - question to be answered (along with the token) for each patient

Returns:

result for each patient

Throws:

LogicException

eval

Map<Integer,Result> eval(Cohort who,
                         LogicCriteria criteria,
                         Map<String,Object> parameters)
                  throws LogicException

Evaluates a query over a list of patients

Parameters:

who - patients for whom the query is to run

criteria - question to be answered (along with the token) for each patient

parameters - arguments to be passed to the rule

Returns:

result for each patient

Throws:

LogicException

eval

Map<LogicCriteria,Map<Integer,Result>> eval(Cohort who,
                                            List<LogicCriteria> criterias)
                                     throws LogicException

Evaluates a collection of queries for a set of patients

Parameters:

who - patients for whom the queries are to be run

criterias - parallel list of criteria to be evaluated on each patient

Returns:

results for each patient

Throws:

LogicException

addTokenTag

void addTokenTag(String token,
                 String tag)

Adds a tag to the given token.

Parameters:

token -

tag - Should add tag for a token

removeTokenTag

void removeTokenTag(String token,
                    String tag)

Removes a token's previously assigned tag.

Parameters:

token -

tag - Should remove tag from a token

getTokenTags

Set<String> getTokenTags(String token)

Gets all tags associated with this token.

Parameters:

token - token to look up by

Returns:

collection of tags Should return set of tags for a certain token

getTokensWithTag

List<String> getTokensWithTag(String tag)

Gets all tokens associated with this tag.

Parameters:

tag - tag to look up by

Returns:

collection of tokens Should return set of token associated with a tag

getTags

List<String> getTags(String partialTag)

Performs a partial match search for token tags among all known tokens.

Parameters:

partialTag - partial match string

Returns:

collection of tags Should return set of tags matching input tag partially

getDefaultDatatype

Result.Datatype getDefaultDatatype(String token)

Fetches the default datatype this token will return when fed to an eval() call. Results (returned by the logic service) are loosely typed by design; however, the default datatype can be a useful hint for managing user interfaces or providing default behavior when working with rules.

Parameters:

token - token to look the datatype up for

Returns:

datatype of the given token

getParameterList

Set<RuleParameterInfo> getParameterList(String token)

Fetches the parameters expected by a given rule

Returns:

list of parameters

getLogicDataSources

Map<String,LogicDataSource> getLogicDataSources()

Get all registered logic data sources

Returns:

all registered logic data sources

getLogicDataSource

LogicDataSource getLogicDataSource(String name)

Get a logic data source by name

Parameters:

name - name of the desired logic data source

Returns:

the logic data source with the given name or null if there is no data source registered under the given name (must be an exact match)

parse

LogicCriteria parse(String criteria)

Parse a criteria String to create a new LogicCriteria.

Example:
logicService.parseString("LAST 'CD4 COUNT' < 200");

Parameters:

criteria - LogicCriteria expression in a plain String object.

Returns:

LogicCriteria using all possible operand and operator from the String input