Rule Authoring API

In Hammurapi Rules a rule (i.e. a unit of inference) is a Java method with Infer annotation. Such method is called an inference method. An inference method shall have one or more parameters through which input facts are fed to the inference method. Inference methods and their parameters can have Condition annotations. Classes with inference methods are called rule classes. Rule classes are organized into rule sets. Such classes are instantiated when a rule session is created. They can be configured with parameters from a rule set definition.

Interfaces and annotations to bind methods to the inference network are defined in com.hammurapi.reasoning.spi package.

• Infer - Indicates that a method is an inference method.
• Condition - Condition (Java expression) for an inference method or its parameters.
• Accept - Indicates that a method is a condition for a multi-parameter inference method.

• InferenceContext - provides means for rule methods to post conclusions and access inference contextual information.
• Rule - Rules with lifecycle shall implement this interface.

@Infer
@Condition("son, parent: son.getObject().equals(parent.getObject())")
public GrandSon infer(Son son, Parent parent) {
	return new GrandSon(son.getSubject(), parent.getSubject());
}

The inference method above defines a condition as an annotation. An alternative is to use if block inside the method. Use of annotation, though, is preferred because it allows the engine to optimize the inference network by chaining/sharing conditions. In the case of condition chaining/sharing if two inference methods have identical conditions (e.g. invoiceAmount>1000) then the engine may optimize inference network so the condition is evaluated once per fact instead once per fact per inference method. The method doesn't use InferenceContext.post(), it simply returns conclusions. As such it doesn't have to declare conclusion types in its @Infer annotations.

@Infer(Cousin.class)
public void infer(Child child1, Child child2, Sibling sibling) {
	if (child1.getObject().equals(sibling.getSubject()) && child2.getObject().equals(sibling.getObject())) {
		InferenceContext.INSTANCE.post(new Cousin(child1.getSubject(), child2.getSubject()));
	}
}

The method above uses InferenceContext.post() method to post conclusions and, therefore, has to declare conclusion types which it posts.

The diagram above shows rule lifecycle ¹⁾.

• Initialization (2.x)
  • Rule classes are instantiated as part of rule session instantiation (2.2).
  • After instantiation, configuration parameters from the rule set are injected into rule instances (2.3).
  • If rule class implements Rule interface then its init() method is invoked (2.4).
• Operation (3.x)
  • When client code puts facts to the knowledge base, the engine fires appropriate inference methods (3.1).
  • Inference methods can post conclusions to the knowledge base in two ways:
    • By returning value from the inference method.
    • By invoking InferenceContext.INSTANCE.post() (3.2).
• Termination (5.x) - When inference session close() method is invoked, the session invokes release() methods on rule instances which implements Rule interface.