Plugin Guide

From Easyrec Wiki
Jump to: navigation, search

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.

Contents

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>

At last 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.

easyrec-plugin.xml

When you implemented your GeneratorPluginSupport you need to make your plugin available for easyrec through the Spring configuration. Adapt the file easyrec-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 the bold-faced 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.

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 bold-faced code to contain your implementation of the command-line interface.

Uploading the plugin

You need to have administration rights to install plugins!

Go to the administration view and select Plugins. Easyrec-administration-pluginsmenu.PNG

Choose Upload new plugin. Easyrec-administration-plugins.PNG

Select the plugin .jar you want to upload to upload and click Upload. Easyrec-administration-plugins-upload.PNG

Install the plugin (this will call doInstall(). Easyrec-administration-plugins-uploaded.PNG

Personal tools
Namespaces

Variants
Actions
easyrec documentation
Navigation
Toolbox