org.openmrs.logic
Interface LogicService

@Transactional
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

void	addRule(java.lang.String token, Rule rule) Registers a new rule with the logic service.
void	addRule(java.lang.String token, java.lang.String[] tags, Rule rule) Registers a new rule with the logic service, associating the tags with the given token
void	addTokenTag(java.lang.String token, java.lang.String tag) Adds a tag to the given token.
java.util.Map<LogicCriteria,java.util.Map<java.lang.Integer,Result>>	eval(Cohort who, java.util.List<LogicCriteria> criterias) Evaluates a collection of queries for a set of patients
java.util.Map<java.lang.Integer,Result>	eval(Cohort who, LogicCriteria criteria) Evaluates a query over a list of patients
java.util.Map<java.lang.Integer,Result>	eval(Cohort who, LogicCriteria criteria, java.util.Map<java.lang.String,java.lang.Object> parameters) Evaluates a query over a list of patients
java.util.Map<java.lang.Integer,Result>	eval(Cohort who, java.lang.String expression) Evaluates a query over a list of patients
java.util.Map<java.lang.Integer,Result>	eval(Cohort who, java.lang.String expression, java.util.Map<java.lang.String,java.lang.Object> parameters) Evaluates a query over a list of patients
Result	eval(java.lang.Integer patientId, LogicCriteria criteria) Evaluates a query for a given patient
Result	eval(java.lang.Integer patientId, LogicCriteria criteria, java.util.Map<java.lang.String,java.lang.Object> parameters) Evaluates a query for a given patient
java.util.Map<LogicCriteria,Result>	eval(java.lang.Integer patientId, java.util.Map<java.lang.String,java.lang.Object> parameters, LogicCriteria... criteria) Evaluates multiple LogicCriteria for a single patient.
java.util.Map<java.lang.String,Result>	eval(java.lang.Integer patientId, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String... expressions) Evaluates multiple logic expressions for a single patient.
Result	eval(java.lang.Integer patientId, java.lang.String expression) Evaluates a rule for a given patient, given the token for the rule.
Result	eval(java.lang.Integer patientId, java.lang.String expression, java.util.Map<java.lang.String,java.lang.Object> parameters) Evaluates a rule for a given patient, given a token and parameters for the rule.
Result	eval(Patient who, LogicCriteria criteria) Deprecated. use eval(Integer, LogicCriteria)
Result	eval(Patient who, LogicCriteria criteria, java.util.Map<java.lang.String,java.lang.Object> parameters) Deprecated. use eval(Integer, LogicCriteria, Map)
Result	eval(Patient who, java.lang.String expression) Deprecated. use eval(Integer, String)
Result	eval(Patient who, java.lang.String expression, java.util.Map<java.lang.String,java.lang.Object> parameters) Deprecated. use eval(Integer, String, Map)
java.util.Set<java.lang.String>	findTags(java.lang.String partialTag) Deprecated. use getTags(String)
java.util.Set<java.lang.String>	findToken(java.lang.String token) Deprecated. use getTokens(String)
java.util.List<java.lang.String>	getAllTokens() Fetch all known (registered) tokens
Result.Datatype	getDefaultDatatype(java.lang.String token) Fetches the default datatype this token will return when fed to an eval() call.
LogicDataSource	getLogicDataSource(java.lang.String name) Get a logic data source by name
java.util.Map<java.lang.String,LogicDataSource>	getLogicDataSources() Get all registered logic data sources
java.util.Set<RuleParameterInfo>	getParameterList(java.lang.String token) Fetches the parameters expected by a given rule
Rule	getRule(java.lang.String token) Gets the rule registered under a given token
java.util.List<java.lang.String>	getTags(java.lang.String partialTag) Performs a partial match search for token tags among all known tokens.
java.util.Collection<java.lang.String>	getTagsByToken(java.lang.String token) Deprecated. use getTokenTags(String)
java.util.Set<java.lang.String>	getTokens() Deprecated. use getAllTokens()
java.util.List<java.lang.String>	getTokens(java.lang.String partialToken) Fetch all known (registered) tokens matching a given string
java.util.Set<java.lang.String>	getTokensByTag(java.lang.String tag) Deprecated. use getTokensWithTag(String)
java.util.List<java.lang.String>	getTokensWithTag(java.lang.String tag) Gets all tokens associated with this tag.
java.util.Set<java.lang.String>	getTokenTags(java.lang.String token) Gets all tags associated with this token.
LogicCriteria	parse(java.lang.String criteria) Parse a criteria String to create a new LogicCriteria.
LogicCriteria	parseString(java.lang.String inStr) Deprecated. use parse(String)
void	registerLogicDataSource(java.lang.String name, LogicDataSource logicDataSource) Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)
void	removeLogicDataSource(java.lang.String name) Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)
void	removeRule(java.lang.String token) Removes a rule from the logic service
void	removeTokenTag(java.lang.String token, java.lang.String tag) Removes a token's previously assigned tag.
void	setLogicDataSources(java.util.Map<java.lang.String,LogicDataSource> logicDataSources) Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)
void	updateRule(java.lang.String token, Rule rule) Update a rule that has previously been registered

Method Detail

getTokens

@Deprecated
java.util.Set<java.lang.String> getTokens()

Deprecated. use getAllTokens()

Fetch all known (registered) tokens

Returns:

all known (registered) tokens

getAllTokens

java.util.List<java.lang.String> getAllTokens()

Fetch all known (registered) tokens

Returns:

all known (registered) tokens

Expected behavior:

return all registered token

findToken

@Deprecated
java.util.Set<java.lang.String> findToken(java.lang.String token)

Deprecated. use getTokens(String)

Fetch all known (registered) tokens matching a given string

Parameters:

token - full or partial token name

Returns:

all tokens containing the given string

getTokens

java.util.List<java.lang.String> getTokens(java.lang.String partialToken)

Fetch all known (registered) tokens matching a given string

Parameters:

token - full or partial token name

Returns:

all tokens containing the given string

Expected behavior:

return all registered token matching the input fully, return all registered token matching the input partially, not fail when input is null

addRule

void addRule(java.lang.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:

Rule

Expected behavior:

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

addRule

void addRule(java.lang.String token,
             java.lang.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

Expected behavior:

not fail when no tags is specified, persist rule with the tags

getRule

Rule getRule(java.lang.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

Expected behavior:

return Rule associated with the input token, fail when no Rule is associated with the input token, return ReferenceRule

updateRule

void updateRule(java.lang.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

Expected behavior:

update Rule when another Rule is registered under the same token

removeRule

void removeRule(java.lang.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

Expected behavior:

remove rule

eval

Result eval(java.lang.Integer patientId,
            java.lang.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

See Also:

#parse(String)}

eval

Result eval(java.lang.Integer patientId,
            java.lang.String expression,
            java.util.Map<java.lang.String,java.lang.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

See Also:

#parse(String)}

eval

Result eval(java.lang.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

eval

Result eval(java.lang.Integer patientId,
            LogicCriteria criteria,
            java.util.Map<java.lang.String,java.lang.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

eval

java.util.Map<java.lang.String,Result> eval(java.lang.Integer patientId,
                                            java.util.Map<java.lang.String,java.lang.Object> parameters,
                                            java.lang.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

See Also:

#parse(String)}

eval

java.util.Map<LogicCriteria,Result> eval(java.lang.Integer patientId,
                                         java.util.Map<java.lang.String,java.lang.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

eval

@Deprecated
Result eval(Patient who,
                       java.lang.String expression)
            throws LogicException

Deprecated. use eval(Integer, String)

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

Parameters:

who - 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

See Also:

#parse(String)}

eval

@Deprecated
Result eval(Patient who,
                       java.lang.String expression,
                       java.util.Map<java.lang.String,java.lang.Object> parameters)
            throws LogicException

Deprecated. use eval(Integer, String, Map)

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

Parameters:

who - 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

See Also:

#parse(String)}

eval

@Deprecated
Result eval(Patient who,
                       LogicCriteria criteria)
            throws LogicException

Deprecated. use eval(Integer, LogicCriteria)

Evaluates a query for a given patient

Parameters:

who - 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

eval

@Deprecated
Result eval(Patient who,
                       LogicCriteria criteria,
                       java.util.Map<java.lang.String,java.lang.Object> parameters)
            throws LogicException

Deprecated. use eval(Integer, LogicCriteria, Map)

Evaluates a query for a given patient

Parameters:

who - 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

eval

java.util.Map<java.lang.Integer,Result> eval(Cohort who,
                                             java.lang.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

java.util.Map<java.lang.Integer,Result> eval(Cohort who,
                                             java.lang.String expression,
                                             java.util.Map<java.lang.String,java.lang.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

java.util.Map<java.lang.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

java.util.Map<java.lang.Integer,Result> eval(Cohort who,
                                             LogicCriteria criteria,
                                             java.util.Map<java.lang.String,java.lang.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

java.util.Map<LogicCriteria,java.util.Map<java.lang.Integer,Result>> eval(Cohort who,
                                                                          java.util.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(java.lang.String token,
                 java.lang.String tag)

Adds a tag to the given token.

Parameters:

token -

tag -

Expected behavior:

add tag for a token

removeTokenTag

void removeTokenTag(java.lang.String token,
                    java.lang.String tag)

Removes a token's previously assigned tag.

Parameters:

token -

tag -

Expected behavior:

remove tag from a token

getTagsByToken

@Deprecated
java.util.Collection<java.lang.String> getTagsByToken(java.lang.String token)

Deprecated. use getTokenTags(String)

Gets all tags associated with this token.

Parameters:

token - token to look up by

Returns:

collection of tags

getTokenTags

java.util.Set<java.lang.String> getTokenTags(java.lang.String token)

Gets all tags associated with this token.

Parameters:

token - token to look up by

Returns:

collection of tags

Expected behavior:

return set of tags for a certain token

getTokensByTag

@Deprecated
java.util.Set<java.lang.String> getTokensByTag(java.lang.String tag)

Deprecated. use getTokensWithTag(String)

Gets all tokens associated with this tag.

Parameters:

tag - tag to look up by

Returns:

collection of tokens

getTokensWithTag

java.util.List<java.lang.String> getTokensWithTag(java.lang.String tag)

Gets all tokens associated with this tag.

Parameters:

tag - tag to look up by

Returns:

collection of tokens

Expected behavior:

return set of token associated with a tag

findTags

@Deprecated
java.util.Set<java.lang.String> findTags(java.lang.String partialTag)

Deprecated. use getTags(String)

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

Parameters:

partialTag - partial match string

Returns:

collection of tags

getTags

java.util.List<java.lang.String> getTags(java.lang.String partialTag)

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

Parameters:

partialTag - partial match string

Returns:

collection of tags

Expected behavior:

return set of tags matching input tag partially

getDefaultDatatype

Result.Datatype getDefaultDatatype(java.lang.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

java.util.Set<RuleParameterInfo> getParameterList(java.lang.String token)

Fetches the parameters expected by a given rule

Returns:

list of parameters

registerLogicDataSource

@Deprecated
void registerLogicDataSource(java.lang.String name,
                                        LogicDataSource logicDataSource)
                             throws LogicException

Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)

Adds a data source to the logic service. Data sources provide access to granular data that can be combined by rules to derive higher level information.

Parameters:

name - name for the data source

logicDataSource - the data source

Throws:

LogicException

getLogicDataSources

java.util.Map<java.lang.String,LogicDataSource> getLogicDataSources()

Get all registered logic data sources

Returns:

all registered logic data sources

setLogicDataSources

@Deprecated
void setLogicDataSources(java.util.Map<java.lang.String,LogicDataSource> logicDataSources)
                         throws LogicException

Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)

Adds the given logic data sources to the list of current data sources on this logic service

Parameters:

logicDataSources -

Throws:

LogicException

getLogicDataSource

LogicDataSource getLogicDataSource(java.lang.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)

removeLogicDataSource

@Deprecated
void removeLogicDataSource(java.lang.String name)

Deprecated. data sources are now auto-registered via Spring (since Logic module version 0.5)

Remove a logic data source by name

Parameters:

name - name of the logic data source to be unregistered

parseString

@Deprecated
LogicCriteria parseString(java.lang.String inStr)

Deprecated. use parse(String)

Parse a criteria String to create a new LogicCriteria.

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

Parameters:

inStr - LogicCriteria expression in a plain String object.

Returns:

LogicCriteria using all possible operand and operator from the String input

parse

LogicCriteria parse(java.lang.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