Rules

Rules are any set of instructions that can restrict or enhance the app. In other words, a rule has a set of criteria, and can it choose to pass or fail the rule based on that set of criteria.

A rule should extend the PassableRule abstract class. passesRule() should return true if the set of criteria is sufficient for a pass, and false otherwise. A PassableRule must also have a failure message, which can optionally be displayed to the user when a rule fails.

In order to use a rule (or set of rules), a RuleBuilder instance should be instantiated and built with the desired settings.

For example:

new RuleBuilder(getActivity())
    .addRule(new InstrumentSurveyLimitRule(mInstrument,
        getActivity().getString(R.string.rule_failure_instrument_survey_limit)))
    .addRule(new InstrumentTimingRule(mInstrument, getResources().getConfiguration().locale,
        getActivity().getString(R.string.rule_failure_survey_timing)))
    .showToastOnFailure(true)
    .checkRules()
    .getResult();

checkRules() will run the entire set of rules that has been added to the RuleBuilder, and getResult() will get the boolean value the rules have returned. A RuleBuilder will return false on the first failed rule, and will not continue testing rules. showToastOnFailure() determines if a Toast should be shown to the user if one of the rules fails. The default for this is false.

Alternatively, you may pass a success and error callback to the RuleBuilder using the RuleCallback interface:

new RuleBuilder(getActivity())
    .addRule(new InstrumentSurveyLimitRule(mInstrument,
        getActivity().getString(R.string.rule_failure_instrument_survey_limit)))
    .addRule(new InstrumentTimingRule(mInstrument, getResources().getConfiguration().locale,
        getActivity().getString(R.string.rule_failure_survey_timing)))
    .showToastOnFailure(true)
    .setCallbacks(new RuleCallback() {
        public void onRulesPass() {
            // The rule passed!
        }

        public void onRulesFail() {
            // The rule failed!
        }
    });

To add a new rule:

• Add the constant name to the RuleType enum in the Rule model
• Specify constants for the rule params and stored value keys in the Rule model
• Create a new class in the Rules package which extends the PassableRule abstract class.