easyrec Wiki

Plugin Guide

Authors:

Attachments

Easyrec-administration-plugins-upload.PNG (19722 bytes)

Easyrec-administration-plugins-uploaded.PNG (29372 bytes)

Easyrec-administration-plugins.PNG (26508 bytes)

Easyrec-administration-pluginsmenu.PNG (11025 bytes)

This page will guide you through writing your own plugin for easyrec.

Starting with easyrec 0.95 a plugin-api for generators is available. A generator is the component of easyrec that calculates item associations - i.e. the recommendations. To implement your own generator you need to implement a certain interface - GeneratorSupport - and provide a easyrec-plugin.xml on the root path of your .jar file. The following document will walk you through creating a generator from scratch step-by-step. Complementary have a look at the sample plugin - located at easyrec/easyrec-plugins/easyrec-plugins-sample - which contains a complete, working sample-generator.

Creating a new maven module
Implementing the interfaces
Testing the plugin
Uploading the plugin

Creating a new maven module

First you need to create a Maven project to contain your code. If you haven't installed maven follow these instructions. Then you can setup your plugin project:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-generator -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Replace the bold-faced strings with your own information. Then add the following dependencies to your pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   ...
   <dependencies>
       <dependency>
           <groupId>org.easyrec</groupId>
           <artifactId>easyrec-plugin-api</artifactId>
           <version>${project.version}</version>
       </dependency>
       <dependency>
           <groupId>org.easyrec</groupId>
           <artifactId>easyrec-utils</artifactId>
           <version>0.95</version>
       </dependency>
       <dependency>
           <groupId>org.easyrec</groupId>
           <artifactId>easyrec-core</artifactId>
           <version>0.95</version>
       </dependency>
       <dependency>
           <groupId>org.easyrec</groupId>
           <artifactId>easyrec-domain</artifactId>
           <version>0.95</version>
       </dependency>
   </dependencies>
   ...
</project>

Finally you need to create a easyrec-plugin.xml file which is a Spring configuration file that is parsed by easyrec when the plugin is loaded:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
</beans>

Implementing the interfaces

The entry-point for your generator is your imlementation of the abstract class org.easyrec.plugin.support.GeneratorPluginSupport. You need to implement three interfaces and edit easyrec-plugin.xml to make easyrec able to load your plugin.

GeneratorPluginSupport

Make sure that your generator class extending GeneratorPluginSupport provides a default (=no arguments) constructor. Otherwise easyrec cannot instantiate the generator and the plugin will be rejected.

Two type parameters need to be supplied:

C: your implementation of org.easyrec.plugin.generator.GeneratorConfiguration.
S: your implementation of org.easyrec.plugin.stats.GeneratorStatistics.

The method doExecute(ExecutionControl control, S stats) is where you place the code that is run when easyrec requests your generator to compute recommendations and must be implemented. Use control to send progress updates to easyrec. Use stats to store runtime statistics for your plugin.

Several hooks are provided by easyrec. They are called in the following order:

doInstall() is called when your plugin is first installed, i.e. run only once.
doInitialize() is called whenever easyrec loads your plugin (easyrec might unload the plugin to preserve memory, or reload it in case of a crash.)
doCleanup() is called whenever easyrec unloads your plugin (counterpart of doInitialize().)
doUninstall() is called when your plugin is uninstalled (counterpart of doInstall().)

GeneratorConfiguration

You can specify some configuration options your plugin needs. You need to create member variables annotated with org.easyrec.plugin.configuration.PluginParameter to make the configuration options visible in the easyrec administration interface. org.easyrec.plugin.generator.GeneratorConfiguration defines some default configuration options:

configurationName: name of the configuration, used for switching between different configurations.
tenantId: the tenant who owns this configuration - not visible in administration interface.
associationType: the association type used to describe generated item associations (defaults to IS_RELATED.)

GeneratorStatistics

Stores runtime statistics of your plugin. You can supply the following values or additionally implement your own:

startDate: time doExecute was called - automatically recorded.
endDate: time doExecute finished - automatically recorded.
numberOfRulesCreated: the number of recommendations/item associations generated by the generator.
numberOfActionsConsidered: the number of actions used for calculating the recommendations.

RunConditionEnabled

Starting with easyrec 1.0 plugins can implement the RunConditionEnabled interface. The interface specifies a single method that gets called before the execution of the plugin starts. the methods gets passed the Date of the last execution of the plugin by the container. If the method returns true the plugin will be exectued, if false the exectuion is skipped. This allows for the conditioned execution of plugins, i.e. it can be checked if any necessary prework has been done that is required.

boolean evaluateRuncondition(Date lastRun)

For example the ARM plugin now checks whether there have been any actions since the last plugin run. If not then the rules will not change and it is thus unecessary to do the calculation again.

easyrec-plugin.xml

When you implemented your GeneratorPluginSupport you need to make your plugin available for easyrec through the Spring configuration. Adapt the fileeasyrec-plugin.xml to include a Spring-bean of your generator:

<?xml version="1.0" encoding="utf-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
   <bean id="myGenerator" class="com.mycompany.app.MyGenerator"/>
</beans>

Again some values need to be changed:

myGenerator: name of the Spring-bean of your generator.
com.mycompany.app.MyGenerator: qualified class-name of your generator.

Testing the plugin

To start a test-run of your plugin you can extend the abstract class org.easyrec.plugin.cli.AbstractGeneratorCLI. Two type parameters need to be supplied:

GC The configuration class used by your generator.
GS The statistics class used by your generator.

Furthermore two methods need to be implemented:

String[] getConfigurations() Return a list of spring configuration files. You need to supply all files that contain the beans your generator uses.
Generator<gc, gs=""> getGenerator() Return an instance of your generator. </gc,>

Finally implement the main function as follows:

   public static void main(final String[] args) {
       final MyGeneratorCLI generatorCLI = new MyGeneratorCLI();
       generatorCLI.processCommandLineCall(args);
   }

Remember to change the code to contain your implementation of the command-line interface.