Create a Rulebase Resolver plugin

The Rulebase Resolver plugin is responsible for locating and providing access to the archive steams (and associated module streams) of the rulebases that are available from the Oracle Determinations Interview Engine. By default the Interview Engine provides two methods for loading rulebases, either via the local file system using the FileRulebaseResolverPlugin or (for Java deployments only) via the Java Classpath API using the ClassloaderRulebaseResolverPlugin. This default behavior, however, can be customized by implementing the RulebaseResolverPlugin.

Overview

The responsibility for loading and maintaining rulebases is shared between two components: the RulebaseService and the RulebaseResolverPlugin. Simply put, the difference between the two is that the RulebaseService is responsible for reading the contents of the rulebase archives and managing the resulting InterviewRulebases, whereas responsibility for providing access to the actual archives is delegated to the RulebaseResolverPlugin.

More specifically the RulebaseService is responsible for:

Creating and caching the available InterviewRulebase objects.
Providing access to the list of available rulebases for this instance of the InterviewEngine.
Applying updates to the rulebase cache.

The RulebaseResolverPlugin is responsible for:

Determining where rulebases and modules are loaded from.
Providing access to the rulebase and module archive streams.
Notifying the rulebases services of any updates to be made to the rulebase cache.

The RulebaseResolverPlugin is created and initialized when the rulebase is created, and like all other Interview Engine plugins, there can only be one per instance of the engine.

Determining which style of RulebaseResolverPlugin to implement

When implementing a custom RulebaseResolverPlugin, the implementer must elect between one of the two following styles:

The Push Method: where rulebase (and associated modules) are "pushed" into the RulebaseService. Further updates may be dynamically pushed into the RulebaseService at the plugins discretion without the need to restart the InterviewEngine.
The Pull Method: where rulebases (and associated modules) are not loaded until specifically requested (that is, "pulled"). Rulebases loaded in this manner cannot be subsequently updated or removed from the cache.

It is recommended that RulebaseResolverPlugin implementations use the Push Method wherever possible. The difference between these two methods of loading rulebases are discussed in more detail below.

The Push Method

Under the Push Method, the plugin pushes the set of rulebases to be loaded as a RulebaseChangeSet, using the RulebaseService.applyChangeSet(...) method. Generally, the initial set of rulebases to be loaded should be pushed when the plugin's initialise() method is called.

When calling applyChangeSet(...) the provided change set will be applied on a best efforts basis. This method will return with a list of RulebaseChangeSetError to indicate any errors (as well as any existing rulebases that were unloaded as a result) that may have occurred while attempting to apply the change set. Furthermore, any changes provided in a given RulebaseChangeSet are considered complete. This means that where a rulebase is dependant on one or more modules, both the rulebase and all of its associated module archives must be provided in the same change set for the rulebase to be able to load correctly.

Source code

To view the source code for the RulebaseResolver sample, refer to examples\interview-engine\rulebase-resolver in the Java runtime zip file.

Dynamically updating rulebases (hotswapping)

Another advantage of using the Push Method is that it allows the rulebase cache to be dynamically updated after it is initialized, allowing rulebases modules to be added, removed or updated. Making such changes is simply a matter of making subsequent calls to RulebaseService.applyChangeSet(...) with a RulebaseChangeSet that contains the set of changes to be applied.

There are some other additional things to be aware of when implementing a RulebaseResolverPlugin that provides dynamic updating capability:

When updating an existing rulebase, it is the responsibility of the RulebaseResolverPlugin implementation to ensure that all applicable updates are provided in the same change set. For example, if a rulebase R relies on two modules A and B, both of which have been updated, then both those modules must be supplied in the same change set for the changes for R to be effected correctly.
Modules can be updated independently of anything that may rely on them, however, updating a module will cause every rulebases that relies on it to be re-loaded. Similarly removing a module will cause all rulebases that depend on it to be removed.
If an error occurs attempting to update a rulebase or module archive, any existing rulebases in the cache that relate to that archive will be automatically unloaded. The RulebaseChangeSetError will indicate which rulebases were unloaded for a given error.

The Pull Method

The Pull Method of loading rulebases is designed for situations where it is not possible to load a rulebase or module archive without being specifically told to which resource it needs to load. For example, a specific implementation stores their rulebase and/or module archives in a data store that only allows them to request a specific resource but provides it with no way to list all the available resources.

Under this method, rulebases are loaded on demand ("pulled") when the Interview Service gets a request for a rulebase that is not already stored in the cache. The process flow for such a request is:

Implementing a Pull style RulebaseResolverPlugin is a matter of implementing the findRulebase(…) and resolveModule(…) methods to return the corresponding rulebase and module archive InputStream.

There are a few disadvantages to implementing this style of resolver:

Once a rulebase or module is loaded it cannot be dynamically updated or removed.
Client applications cannot provide a complete list of available rulebases. Instead, rulebases will need to be loaded manually via the LoadRulebase action for the Determinations Server or through the StartSession URL for Web Determinations.

Source code

To view the source code for the RulebaseResolver sample, refer to examples\interview-engine\rulebase-resolver in the Java runtime zip file.

Example

See Rulebase Resolver sample code (DerbyRulebaseService) for a worked example of implementing a rulebase resolver plugin.