Understanding Drools KIE API: KieServices, KieContainer, KieBase, and KieSession Explained

KieServices

The KieServices interface offers numerous methods to access KIE objects related to building and running rules. Through it you can obtain a KieContainer (to work with KieBase and KSession) and a KieRepository (to manage KieModules).

KieContainer

A KieContainer acts as a holder for one or more KieBases. It provides methods to retrieve a KieBase and to create KieSessions, the latter internally using the underlying KieBase.

KieBase

KieBase is a knowledge repository that stores rules, processes, and other artifacts. It does not contain runtime data; to execute rules you must create a KieSession from a KieBase.

KieSession

KieSession is the interaction point with the Drools engine. Built from a KieBase, it holds runtime data (facts) and performs rule evaluation in real time. Creating a KieSession via a KieContainer is convenient because the session is derived from the cached KieBase, making session creation inexpensive compared to building a KieBase.

KieRepository

KieRepository is a singleton that stores KieModules, which are defined by kmodule.xml files.

KieProject

KieContainer uses a KieProject to initialize and construct KieModules, placing them into the KieRepository. The container then queries the KieProject for module definitions to build KieBase and KieSession instances.

ClasspathKieProject

ClasspathKieProject implements the KieProject interface, constructing KieModules from META-INF/kmodule.xml files found on the classpath. This enables Maven‑based Drools projects to load rule and process files with minimal code.

kmodule.xml Configuration

KieBase Attributes

name (required): the name of the KieBase.

includes (optional): comma‑separated list of other KieBase names whose rules and processes should be included.

packages (default: all): comma‑separated list of package paths; by default all rule files under resources are included.

default (default: false): whether this KieBase is the default one for the module.

equalsBehavior (default: identity): determines how the engine checks for duplicate facts— identity uses ==, equality uses .equals().

eventProcessingMode (default: cloud): cloud treats events as normal facts; stream enables temporal reasoning.

declarativeAgenda (default: disabled): advanced switch that allows rules to control the execution of other rules.

KieSession Attributes

name (required): unique identifier for the session.

type (default: stateful): stateful sessions retain working memory across invocations; stateless sessions do not.

default (default: false): marks the session as the default for the module.

clockType (default: realtime): realtime uses the system clock; pseudo is for simulated time in tests.

beliefSystem (default: simple): selects the belief system type, e.g., simple, defeasible, or jtms.