Plugin loading, invocation and discovery

This topic is intended as a guide for implementing plugins that are loaded and invoked by the extension framework.

Plugin interface

All extension implementations must implement an interface that is descended from the super plugin interface known as Plugin. Typically, you are required to implement the most specific interface in the hierarchy, according to the type of plugin that you are writing; for example, if you wanted to implement a plugin that was an event handler for the OnSessionCreatedEvent engine event, you would implement the OnSessionCreatedEventHandler, NOT the generic EngineEventHandler interface.

Regardless of the specific interface implemented, all plugin implementations must conform to the following to be loaded and invoked properly by the extension framework:

Must implement the getInstance(args : RegisterArgs) : Plugin method. This method is to return an instance of the plugin object if the plugin has determined (using the contents of the specific RegisterArgs implementation instance passed) that it is usable.
Must have a parameter free constructor.
Must correctly implement all methods defined by the specific interface that it implements. This includes methods defined in super-interfaces of the specific interface implemented by the plugin.

Extension types

The point at which an extension is registered and the registration arguments that are passed to it, is determined by its type. There are several types of plugins:

Engine plugin: Interview Engine plugins are available to customize the behavior of the Interview Engine. Interview Engine plugins are registered when the instance of an engine is create.
Platform plugin: plugins that are available in the Web Determinations web application, as opposed to the Interview Engine or session. These are registered when an application session is created, as distinct from an Interview Session.
Service plugin: Determinations Server plugin that allows the leveraging of the Web Determinations technology to create a custom SOAP/HTTP based web service.
Session plugin: plugins that attach to a particular Interview Session. Interview Session plugins are registered when the instance of a session is created.

What do you want to do?

Understand what installation methods are available

Install extensions to work on Oracle Policy Modeling Build and Run instances

Understand what installation methods are available

There are two methods of installing extensions:

Auto-discovery
Manual configuration

Auto-discovery

It is possible to automatically discover and register extensions when the applications start. Using this method, plugin installation is simply a matter of compiling the plugin libraries (.jar in Java or .dll in .NET) and deploying them to the plugins folder and restarting the application. The plugins folder is located in <web root>/WEB-INF/classes/plugins in Java or <web root>/bin/plugins in .NET.

Multiple plugins can be compiled into a single library or multiple plugin libraries can be used. Any third party dependencies must be copied into a location that will cause them to be automatically loaded when the applications starts such as <web root>/WEB-INF/lib in Java or <web root>/bin/ in .NET.

Note for Java Deployments:

Because the Auto-discovery mechanism requires the ability to introspect the class path, this method may not be available in certain application servers such as Oracle WebLogic Application server, when running the war file unexpanded. In such cases, plugins must be loaded using the manual configuration option

Manual configuration

Manually configuring which plugins to load involves deploying the extensions, and any third party dependencies to a location that will automatically be loaded when the application starts such as <web root>/WEB-INF/lib in Java or <web root>/bin/ in .NET. The list of plugin classes to be loaded must then be manually specified using the plugin.libraries property in application.properties

Install extensions to work on Oracle Policy Modeling Build and Run instances

Installing extensions to enable Oracle Policy Modeling Build and Run instances to use those extensions, is the same process as installing either onto the Determinations Server or onto a Web Determinations server.

The Oracle Policy Modeling Build and Run command invokes a Java web server as well, and its plugin folder can be found in the 'Release' folder directly in the project folder; for example, if we have a rulebase named 'MyRulebase', located in C:\projects\MyRulebase, the plugins folder will be located in the path:

C:\projects\MyRulebase\Release\web-determinations\WEB-INF\classes\plugins

Register an extension

Regardless of the specific interface implemented, all extensions must conform to the following to be loaded and invoked properly by the extension framework:

Must implement the getInstance(args : RegisterArgs) : Plugin method. This method allows an extension class to read the RegisterArgs and its contents to determine whether it should be registered to the current Web Determinations interview (by returning an instance of itself). In addition to that, because the plugin has control on what instance of itself it returns, it is able to instantiate an instance of itself with arguments from the RegisterArgs args.
- This allows the plugin to only become loaded on specific rulebases, or locale, and so on if rulebase or locale data is in the passed RegisterArgs
- This also allows the plugin to choose which constructor to use for instantiation; for example, new CustomPlugin(SessionContext ctx)
- This is critical for ensuring that only one plugin is registered per Web Determinations interview
  Note:
  The above RegsterArgs is more specific depending on the plugin; for example, DataAdaptorPlugins receive InterviewSessionRegisterArgs, CustomScreenProviders receive PlatformSessionRegisterArgs, and so on.
- In is permissible to implement singleton plugins by returning the same instance of the plugin for multiple invocations of getInstance(), however, it is the implementer's responsibility to ensure thread safety in such situations.
Must have a public parameter free constructor.
Must correctly implement all methods defined by the specific interface that it implements. This includes methods defined in super-interfaces of the specific interface implemented by the plugin.

Code Sample - Sample Plugin - RulebaseSpecificDataAdaptor

public class RulebaseSpecificDataAdaptor implements DataAdaptorPlugin { //TIP: Each Plugin implements a Plugin Interface

        /**

         * Only provide this plugin if the Web Determinations session's rulebase is the 'SpecialRulebase' rulebase.

         * The specific RegisterArgs object we get here is an instance of InterviewSessionRegisterArgs.

         */

        public Plugin getInstance(InterviewSessionRegisterArgs args) { //TIP: Each Plugin interface implemented have different getInstance() argument

                if (args.getSession().getRulebase().getIdentifier().equals("SpecialRulebase")){

                    return new RulebaseSpecificDataAdaptor ();

                } else {

                    return null;

                }

        }

        /**

         * Parameterless constructor to conform to the plugin requirements

         */

        public RulebaseSpecificDataAdaptor (){

        }

...

Notes about Hot-swapping mode

If Hot-swapping mode is turned on, then:

When a new rulebase is added, the Custom Service plugin will be given an opportunity to register a service against that rulebase.
When a rulebase is deleted, any service registered against it will be automatically unloaded.
Updating an existing rulebase is equivalent to a delete and load.

Plugins and RegisterArgs

The following table indicates which specific RegisterArgs implementation objects may passed to the getInstance method of descendant interfaces of the base Plugin interface.

REGISTERARGS implementation	Encapsulated objects	Plugin Descendent interface(s)
InterviewEngineRegisterArgs	- The Interview Engine in use.
InterviewSessionRegisterArgs	- The current InterviewSession.	EngineEventHandler DataAdaptorPlugin DocumentGenerationPlugin CommentaryProviderPlugin ListProviderPlugin
PlatformSessionRegisterArgs	- The current SessionContext.	CustomScreenProvider CustomControlProvider PlatformEventHandler WebDeterminationsFormatter
InterviewServletRegisterArgs	- The InterviewServletContext object in use.

Plugin type	Interface	Ancestor interface
Data Adaptor	DataAdaptorPlugin	EnginePlugin
Document Generator	DocumentGenerationPlugin	EnginePlugin
Commentary Provider	CommentaryProviderPlugin	EnginePlugin
List Provider	ListProviderPlugin	EnginePlugin
Custom Screen Provider	CustomScreenProvider	PlatformPlugin
Custom Control Provider	CustomControlProvider	PlatformPlugin
Web Determinations Formatter	WebDeterminationsFormatter	PlatformPlugin

Do's and don'ts

As part of the initialization logic implemented in your implementation of the getInstance method or the parameter free constructor, DO NOT set a static (class-scope) reference to any of the objects encapsulated by the given RegisterArgs parameter.
It is not permissible for plugins to directly alter the state of any of RegisterArgs members passed in the get instance method.
Do not make assumptions about the number of times that the getInstance method is called. It is up to the logic implemented in this method to determine whether the plugin is to be available in a particular context. Every call to this method is another chance to the plugin to inform the application that it is ready to be used or to invalidate itself for use.
Once the first call to the getInstance method returns, the plugin's code may be called at any point. That is, you may not make any assumptions about the order and number of calls into your code.