User Guide

In a general form an XML configuration file is built as in the following example:

The specification of a configuration XML file is provided by the schema file config.xsd.

The configuration file is looked up using the default strategy provided by Apache Commons Configuration, e.g. first in the file system as a relative or absolute path and then in the classpath. If not found, the configuration file is looked up in the file system relative to the Sponge home directory.

The Engine Builder API is provided by DefaultSpongeEngine.builder() static method that returns the EngineBuilder instance. This API follows a builder design pattern.

The Engine Builder API provides the method config() to read an XML configuration file as well.

The Engine Builder API preserves the load order of knowledge bases, including knowledge bases specified in the configuration file.

You may set engine parameters via ConfigurationManager but only after invoking build() and before starting up the engine.

To startup the engine you should invoke the startup() method. After startup, the engine runs in the background (i.e. using threads other than the current one) until you shutdown it.

When a Sponge instance is no longer needed it should be shut down by invoking shutdown() or requestShutdown() method. It instructs the engine to do some clean up, stop all managed threads, free resources, etc. The shutdown() uses the current thread to stop the engine. The requestShutdown() uses a new thread to stop the engine, thus allowing to shutdown the engine from the within, e.g. form an event processor.

Shutting down doesn’t guarantee that all events sent to the engine will be processed. However, all events that have already been read from the Input Event Queue (by the Filter Processing Unit) will be fully processed by the engine, if the processing doesn’t exceed shutdown timeouts (specified by the executorShutdownTimeout configuration parameter). All newer events remaining in the Input Event Queue will not be processed at all.

Generally, script knowledge base files consist of a few parts:

Sponge follows a convention that the names of all callback functions and methods start with on, e.g. onStartup for a knowledge base or onConfigure for a processor.

When Sponge is starting, callback functions are invoked in the following order:

Before onStartup() is invoked you will not be able to send events or access plugins. That is because the engine hasn’t started fully yet.

When a knowledge base is reloaded, the callback functions are invoked in the following order:

The following predefined global variables are available in all knowledge bases.

For each plugin a global variable will be created. The name of this variable is the plugin name (i.e. the value configured as the plugin name attribute in the configuration).

A user variable could be defined in one of the two scopes:

For a complete list of available methods see the EngineOperations and the KnowledgeBaseEngineOperations Javadoc.

Sponge gives the possibility to define a knowledge base in a few files. In order to do that, in the configuration file in the <engine> section you may define which files should be loaded by adding <file> tags to <knowledgeBase>. Additional files could also be loaded from a knowledge base level.

Sometimes a situation may happen that there will be a need for a dynamic modification of processors, for example to add a new rule or modify an existing one. It is possible to do it without the need of shutting down and then starting the system again.

When variables are used in a knowledge base and you don’t want them to be changed after reloading of the knowledge base, you should place their definitions in onInit() callback functions rather than simply in the main script or in onLoad(). That is because the main script and onLoad() are always executed during reloading but onInit() function is not.

When reloading the system, the configuration file is not loaded again. If the changes in this file (e.g. registering a new plugin) are to be visible in the system, the only way is to restart.

When the Sponge engine is being reloaded, the previously defined processors will not be removed from the registry. When a processor definition has changed in the file being reloaded, it will be auto-enabled (i.e. registered) once more with the new definition. If auto-enable is off, then sponge.enable method must be invoked. In that case sponge.enable should be placed in the onLoad() callback function.

If auto-enable is on (this is the default setting), then all processors will be enabled after reloading, even processors that have been manually disabled before.

Depending on the specific interactions and taking into account differences in the third-party implementations of scripting languages, reloading sometimes may lead to problems or side effects and it should be used carefully. For example if onLoad callback function definition is removed in the Python script file before reloading, the instance of this function that had been loaded before will still be present in the interpreter and will be invoked. That is because the scripts being reloaded run in the same interpreter instance.

As mentioned before, Sponge provides the possibility to read a knowledge base from many files. Dividing a knowledge base into a few files allows in an easy way to separate some functionalities.

The order in which the files are loaded is important. The files will be loaded in such order in which they were placed in the configuration.

Sponge is a multi-threaded system. Sponge engine operations are thread-safe. However, attention should be paid that processors defined in a knowledge base access any shared resources in a thread-safe way. This could be achieved in various ways using Java or scripting language mechanisms.

Non script knowledge bases may be written in Java or Kotlin. Non script base processor classes follow the naming convention JAction, JTrigger, JKnowledgeBase etc for Java and KAction, KTrigger, KKnowledgeBase etc for Kotlin.

There are some limitation in the interoperability between scripting knowledge bases:

For more information see Sponge Javadoc.

Sponge provides a few predefined script files that may be used as one of files in your compatible (i.e. written in the same language) knowledge bases. For example you may use the Jython library in your XML configuration file: <file>classpath*:org/openksavi/sponge/jython/jython_library.py</file>. The classpath* notation is available only for Spring aware engines and allows to use Ant style (*) specifications for directories and files.

You may specify a version number for a knowledge base as an integer. It could be useful for example to enforce version checking when calling actions via the REST API. You should set the version in the onLoad callback function. After editing the knowledge base file and before reloading the engine, you could increase the version number.

The builder-style methods in the metadata classes follow the naming convention with<Property>, e.g. BinaryType().withMimeType("image/png").

Processors may be assigned to registered categories. Categories could be used in a client code to group processors independently of knowledge bases. This feature be useful if you don’t want to group processor by knowledge bases which requires more resources because each knowledge base has its own interpreter.

A registered category can be manually assigned to a processor a the processor configuration callback method onConfigure or dynamically by selecting processors that are to assigned to the category. The latter option could assign for example all processors defined in several knowledge bases to a single category in one line. Dynamic selection overwrites manual assigning.

Properties id and time are automatically set when adding an event to the Input Event Queue and there is no need for setting them manually.

In order to process an event there must be an event processor listening to events of that type (the types of events are recognized by their names). So this steps should be taken:

The event is cloned each time when the periodically generated events are sent to the Input Event Queue.

The standard implementation of events allows choosing the cloning policy shallow or deep. These policies differ in the way of cloning of events attributes. When using the former, the references to attributes are copied - each event processor works on the same attribute instances. The policy deep executes the procedure of deep cloning, so each next generated event will contain individual copies of the attributes.

The default implementation of an event is the AttributeMapEvent class. However, Sponge allows to use custom event implementations of the Event interface.

System events are sent automatically by the engine. An event sent in your code shouldn’t have the same name as any of the system events. Currently there is only one system event.

Control events are used by the engine internally. The names of control events have a prefix $. You shouldn’t give to your events a name that starts with this character.

Creating an event means creating an instance of an event class. Sending an event means that the created event will be put into the Input Event Queue, to be processed by filters and then by triggers, rules and correlators.

Event can be created and sent using the EventDefinition fluent API (e.g. sponge.event("helloEvent").set("say", "Hello World!").send()). The method sponge.event returns EventDefinition.

An event may be sent as:

Sample sending of events from the level of a knowledge base:

Sends the event named "e1" after 1 second from now.

Sends the event named "e2" after 2 seconds from now. New events will be periodically generated and sent every second.

Sends an event with attributes "color" and "severity" immediately.

Sends an event at the time specified by Cron notation.

A priority may be assigned only to control events, that are used internally by the engine. For standard events the priority always equals to 0 and cannot be modified.

A priority defines a level of the importance of an event. Events are added to and taken from queues with respect to their priorities. Priority is a positive or negative integer and the higher the number is, the higher is the priority of an event and the event will be processed before the others.

In order to define your processor in a script knowledge base, you have to create a class extending the base class pointed by a specific alias (e.g. Filter for filters). In order to define your processor in a Java knowledge base, you have to create a class extending a specific class (e.g. JFilter for filters).

A name of a processor is a name of a class defining this processor.

The operation of registering a processor in the engine is called enabling. Registered processors are available to the engine to perform specific tasks. For example, after enabling an event processor starts listening to events it is interested in.

Processors could be enabled:

Processors could be disabled only manually. To disable any script-based processors in a script knowledge base you may use sponge.disable() to disable one processor and sponge.disableAll() to disable many processors.

To disable any Java-based processors in a script knowledge base you may use sponge.disableJava(), sponge.disableJavaAll() or sponge.disableJavaByScan().

Processors provide builder-style, fluent methods to set metadata properties, e.g. self.withLabel("Label").withDescription("Description"). In many scripting languages properties can be accessed using a dot notation rather than a direct method call. For example a processor metadata may be read using self.meta or self.getMeta().

In addition to the inherited processor properties and methods, actions provide the following ones.

The onConfigure method in actions is not mandatory.

The code presented below defines the action named EchoAction that simply returns all arguments.

The code presented below defines the Java-based action named JavaEchoAction.

Actions may have metadata specified in the onConfigure method. Metadata may describe action arguments and a result. Metadata are not verified by the engine while performing an action call but could be interpreted by a client code or Sponge plugins. For example they could be useful in a generic GUI that calls Sponge actions. Metadata can be specified using the builder-style methods.

Metadata for arguments and a result are specified by types.

An action argument can be provided, i.e. its value and possible value set may be computed and returned to a client code any time before calling an action. A provided argument gives more flexibility than the defaultValue in the argument data type. Nested values of action arguments can be provided as well. In that case both a type being provided and a dependency path have to be named and can’t contain collections (lists or maps) as intermediate path elements.

The onProvideArgs(ProvideArgsContext context) method is used to provide action argument values.

This feature makes easier creating a generic UI for an action call that reads and presents the actual state of the entities that are to be changed or only viewed by the action and its arguments.

A provided argument can be readOnly. In that case its value in the onCall method should be ignored. A read only argument type has to be nullable.

A provided argument can depend on other arguments but only those that are specified earlier. In the example argument actuator5 depends on actuator1. Its possible value set contains the value of actuator1.

Arguments configured as provided have to be calculated in the onProvideArgs callback method and set in the provided map. For each provided argument its value and possible value set can be produced as the instance of the ArgValue class. The optional withValue method sets the provided value. The optional withAnnotatedValueSet method sets the value set along with annotations (e.g. labels) where each element is an instance of the AnnotatedValue class. The optional withValueSet method sets the possible value set with no annotations.

The parameter names in the onProvideArgs is a set of argument names that are to be provided. The current parameter is a not null map of argument names and their current values passed from a client code. The current value means the value used in a client code, for example entered by a user into an UI before calling the action. This map is required to contain values of those arguments that the arguments specified in the names depend on.

Actions may implement additional Java interfaces. It could be used to provide custom behavior of actions.

Filters allow only certain events to be processed by the engine. Filters are executed in the same order as the order of their registration (i.e. enabling).

You could modify event attributes in filters if necessary.

The alias for the base class for script-based filters is Filter. The base class for Java-based filters is JFilter.

Triggers run a specified code when an event happens.

The alias for the base class for script-based triggers is Trigger. The base class for Java-based filters is JTrigger.

Sometimes there is a need to perform certain actions when a sequence of events has happened, additionally fulfilling some conditions. To handle such event relationships (both temporal and logical), Sponge provides rules. It is important for the behavior of the rules that events that happened first must be sent first into the engine.

The alias for the base class for script-based rules is Rule. The base class for Java-based rules is JRule.

A rule group is a set of rule instances, each created automatically for every event that could be accepted as the first event of this rule.

Correlators could be viewed as a generalized form of rules. They detect correlations between events and could be used for implementing any complex event processing that isn’t provided by filters, triggers or rules.

Correlators listen to the specified events regardless of their order and provide manual processing of each such event. It means that they require more programming than the other processors, however provide more customized behavior. For example they need explicit stopping by calling the finish method. An instance of a correlator is created when the correlator accepts an incoming event as its first event.

A correlator instance, when started, may be finished:

The alias for the base class for script-based correlators is Correlator. The base class for Java-based correlators is JCorrelator.

A correlator group is a set of instances of the correlator.

This plugin definition section contains:

The above configuration defines a plugin implemented by org.openksavi.sponge.examples.EchoPlugin class. This plugin may be used in the knowledge base as a global variable named echoPlugin (according to the name attribute). There are additional configuration parameters defined for this plugin. These parameters could be read in the onConfigure() method of the plugin class, called before starting the plugin.

An access to the plugin could be achieved in two ways:

Because echoPlugin implements the method getEcho(), you may invoke it in two ways:

Sponge loads plugins when starting the system according to the steps:

If you want to use Sponge with, for example, Python scripting knowledge bases, add this dependency to your pom.xml:

There is also a Bill Of Materials style maven artifact for Sponge. Example usage in your pom.xml:

In that case you may omit the versions of the dependencies.

Sponge engine can be configured as a Spring bean. That configuration provides standardized access to an embedded Sponge engine for example in J2EE environment.

To provide access to the Spring ApplicationContext in the knowledge base, the SpringPlugin instance should be created, configured as a Spring bean and added to the Sponge engine. The Spring plugin shouldn’t be defined in Sponge XML configuration file.

For more information see the SpringPlugin Javadoc.

The SpringSpongeEngine starts up automatically (in the afterPropertiesSet Spring callback method) by default. However it can be configured not to start automatically by setting autoStartup to false.

Maven users will need to add the following dependency to their pom.xml for this component:

The Sponge REST API provides users a remote access to the key Sponge functionalities. The REST API server plugin (RestApiServerPlugin) uses Apache Camel REST DSL in order to configure the JSON/REST service. After starting the plugin, the online API specification in the Swagger JSON format will be available at URL http://localhost:1836/api-doc.

The default name of the REST API plugin (which can be used in knowledge bases) is restApiServer.

For more information see the RestApiServerPlugin Javadoc.

The REST API plugin provides a simple predefined knowledge base libraries: engine_admin_library.py and engine_public_library.py.

Maven users will need to add the following dependency to their pom.xml:

Depending on the REST Camel component, you should add a corresponding dependency, e.g. camel-jetty for Jetty, camel-servlet for a generic servlet. For more information see the Camel documentation.