The plugin framework is similar to the SQLSubscriber handler plugin framework. The major difference is that it's not dependent on a particular handler, rather it's provided by the framework and is therefore available to all handlers.


Prerequisites

(warning) First, you will need to set up one of the Perspectium DataSync Agents.

(warning) You should stop running your DataSync Agent before making any Agent configuration changes.


Enabling the plugin

The plugin or java class needs to be available when the DataSync agent starts. The DataSync agent installation creates a jars directory and the plugin class file must be contained within a valid java jar file which will need to be copied into that directory. Furthermore, you must explicitly configure the DataSync Agent to load and use the plugin.

Here's an example of a task called <my_task> using the plugin called TruncateMessageValue:

<task>
        <task_name>my_task</task_name>
        <task_plugins>
                <plugin max_message_value_size="1024">com.abc.replicator.plugins.TruncateMessageValue</plugin>
        </task_plugins>
 </task>

The <task_plugins> directive must be enclosed within the <task> directive as shown in the above example. A single <plugin> statement is used per plugin. Multiple <plugin> statements are executed in the order in which they are configured. This approach allows chaining of several plugins, where each performs a specific task upon the message. The attributes and associated values configured in the <plugin> tag will be made available to the plugin when its processMessage method is called. This can be useful for providing static information to the plugin.

In our example the plugin com.abc.replicator.plugins.TruncateMessageValue will be enabled and called during processing by a sharer or subscriber. The class will have a single entry in the attributes map whose key will be max_message_value_size, and the value will be 1024. The java class uses the configured attribute to ensure that the value of each message does not exceed 1024 characters by performing truncation.


Writing a plugin

The plugin framework currently requires the plugins to be written using the Java language.

Each class or plugin must implement the IPlugin interface which looks like the following:

public interface IPlugin {
        public void processMessage(Message message, Map<String, String> attributes);
}


The plugin developer creates a single class which is called for each message that is being either shared or subscribed to. The processMessage java method can act upon the message as desired. All properties of the message are available to the plugin for reading and updating. Once the method returns the next plugin will be called until all plugins have been called. In the case of a <subscribe> handler the message will then be passed to the handler for processing. If the task is a <share> type then the message will be published to the Perspectium Mesh.