Creating LarKC plug-ins
This guide is written for platform version 2.x and utilizes the maven archetype plug-in to generate plug-in skeletons.
Contents
In a nutshell
Install maven, check out the LarKC Platform and mvn install the platform
Generate archetype: mvn archetype:generate -DarchetypeCatalog=http://larkc.svn.sourceforge.net/svnroot/larkc/trunk/larkc-plugin-archetype/
- Implement desired functionality
Build plug-in: mvn install
Prerequisites
Before starting make sure that you have
Maven installed (in this guide version 2.2.1 was used)
- a recent version of the LarKC platform
For ease of development it is recommended that you have the platform's source, as opposed to a jar version. You can check out the trunk version of LarKC via sourceforge.
svn co https://larkc.svn.sourceforge.net/svnroot/larkc/trunk/platform
After the checkout, execute mvn install in the platform directory. If the install goal fails due to failing tests, try ignoring tests via mvn install -DskipTests.
Creating a plug-in skeleton
Note: Since archetype support is not very good in m2eclipse, it is recommended to generate LarKC plug-ins via the command line.
To generate a LarKC plug-in the generate goal of archetype is called. To use the LarKC plug-in archetype we need to specify the archetypeCatalog parameter. Change to your workspace directory and issue the following command:
mvn archetype:generate -DarchetypeCatalog=http://larkc.svn.sourceforge.net/svnroot/larkc/trunk/larkc-plugin-archetype/
This may take a while since maven needs to download the necessary plug-ins and resolve all dependencies. After this is done you will be prompted to choose which archetype to use. The output should look as follows:
$ mvn archetype:generate -DarchetypeCatalog=http://larkc.svn.sourceforge.net/svnroot/larkc/trunk/larkc-plugin-archetype/
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] [archetype:generate {execution: default-cli}]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: http://larkc.svn.sourceforge.net/svnroot/larkc/trunk/larkc-plugin-archetype/ -> larkc-plugin-archetype (Creates an empty LarKC plug-in; useful if you want to
develop your own LarKC plug-ins.)
Choose a number: :Only one archetype should be present: larkc-plugin-archetype. Choose larkc-plugin-archetype by entering 1 and confirm by pressing return. If there are multiple versions of the archetype present, select the newest one.
Choose a number: : 1 [INFO] Using property: groupId = eu.larkc [INFO] Using property: artifactId = plugin.myplugin [INFO] Using property: version = 0.0.1-SNAPSHOT [INFO] Using property: package = eu.larkc.plugin.myplugin [INFO] Using property: larkcPluginName = MyPlugin Confirm properties configuration: groupId: eu.larkc artifactId: plugin.myplugin version: 0.0.1-SNAPSHOT package: eu.larkc.plugin.myplugin larkcPluginName: MyPlugin Y:
Press return again to create a plug-in using the default properties. By doing so a plug-in skeleton named MyPlugin will be created.
In most cases you don't want to use the default properties. To set your own properties deny the default values by entering n. Confirm with return. You will be asked to set all required properties. To use the default value for a property simply press return. The following shows an example of custom properties to create an "?IrisReasoner" plug-in.
Y: n Define value for property 'groupId': eu.larkc: Define value for property 'artifactId': plugin.myplugin: plugin.reasoner.iris Define value for property 'version': 0.0.1-SNAPSHOT: Define value for property 'package': eu.larkc.plugin.myplugin: eu.larkc.plugin.reasoner.iris Define value for property 'larkcPluginName': MyPlugin: IrisReasoner
Confirm the properties configuration you have entered to create a plug-in skeleton using these specific properties. If all went well you will see the following output:
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3 seconds [INFO] Finished at: Mon Mar 21 13:43:26 CET 2011 [INFO] Final Memory: 14M/164M [INFO] ------------------------------------------------------------------------
The generated plug-in can now be edited to your likings. Every plug-in skeleton is a valid maven project and can thus be build using the standard maven procedure.
A very convenient way to develop plug-ins is to import the generated plug-in skeleton in eclipse. You can do that as usual via the File->Import dialog. Choose Existing Maven Projects or Existing Projects into Workspace and select the previously generated plug-in skeleton. Make sure that you also have the LarKC platform as a project in your workspace, since every LarKC plug-in is dependend on the platform.
Building a LarKC plug-in
Since plug-ins are maven projects, they can be build via mvn install.
In a terminal simply run mvn install in the plug-in directory. Alternatively, in eclipse (with m2eclipse installed) there is a predefined run configuration: Run As -> Maven install
If the build is successful a jar file will be created in the projects target folder and automatically copied to ../platform/plugins.
Building a LarKC plug-in which uses non-maven libraries
First of all, it is possible that the library you need is deployed in some maven repository. Try searching at http://mvnrepository.com/ or a similar site and add the dependency to your plug-in's pom.xml file.
If your plug-in does depend on any special plug-ins which are not deployed in a maven repository you can use the maven assembly goal to include them in your plug-in file. Place any libraries you wish to include with your plug-in in the lib/ folder of your plug-in. Then change the POM file of the plug-in project. The following part of the POM file has to be changed accordingly, by specifying the ?GroupId, ?ArtifactId, Version and the ?SystemPath of the library, that is placed in the lib/ folder:
<!-- Declare any special libraries (which have to be put in /lib) here. -->
<!--
<dependency>
<groupId>your.external.library</groupId>
<artifactId>artifactid</artifactId>
<version>x.x.x</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/your-library.jar</systemPath>
</dependency>
-->Multiple dependencies can be specified by adding more dependency sections to the POM file. Then run mvn assembly:assembly (eclipse: Run As -> Maven assembly:assembly).
Registering a LarKC plug-in at the platform
The LarKC platform scans its plugins folder on startup and deploys any LarKC plug-ins which are present as .jar (or .larkc) files. If not done automatically (if your folder structure differs), copy your plug-in (the jar file generated by mvn install - e.g. plugin.MyPlugin-0.0.1-SNAPSHOT.jar) to the plugins folder of the platform (e.g. platform/plugins) and start LarKC.
To make sure that your plug-in can be loaded start LarKC by running the main class eu.larkc.core.Larkc via Run As -> Java Application. If debug output is enabled, the plug-in registry will notify you about which plug-ins have been loaded. If your plug-in was loaded successfully the output should read as follows:
... 14:17:16.573 INFO e.l.c.p.PluginRegistry: Registered the eu.larkc.plugin.myplugin.MyPlugin ...
You can also list all plug-ins which have been registered via the management interface. Pointing your browser to http://localhost:8182/registry?getAllPlugins will show you a list of all loaded plug-ins.
Testing your plug-in
To test your plug-in create a simple workflow which utilizes your plug-in(s). A very basic example would be as follows:
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix larkc: <http://larkc.eu/schema#> . # Define two plug-ins _:plugin1 a <urn:eu.larkc.plugin.myplugin.MyPlugin> . _:plugin2 a <urn:eu.larkc.plugin.myplugin.MyPlugin> . # Connect the plug-ins _:plugin1 larkc:connectsTo _:plugin2 . # Define a path to set the input and output of the workflow _:path a larkc:Path . _:path larkc:hasInput _:plugin1 . _:path larkc:hasOutput _:plugin2 . # Connect an endpoint to the path <urn:myTestEndpoint> a <urn:eu.larkc.endpoint.test> . <urn:myTestEndpoint> larkc:links _:path .
You can initialize this workflow via the management interface. After starting LarKC point your browser to http://localhost:8182/ and submit your workflow there. If the workflow creation was successful, the ID of the workflow will be returned (e.g. e39d48e0-03c9-4d81-9e0a-7bc4fda7095b). Use this ID to retrieve the endpoint of your workflow.
The plug-in's constructor and initialiseInternal method will be called on workflow creation.
After successful workflow creation, use the following URL to get an endpoint for a specific workflow: HTTP GET /workflow/WID/endpoint/?urn=urn Where the WID is the unique ID of your workflow (as returned by successful workflow creation) and urn is the endpoint urn (e.g. <urn:myTestEndpoint>).
Example:
HTTP GET http://localhost:8182/workflow/135cc37f-b6e5-490c-8f5b-8271e8d20e17/endpoint?urn=urn:myTestEndpoint
The URL of your endpoint will be returned (e.g. http://localhost:8183/testendpoint ). Start your workflow by sending a HTTP POST request to the endpoint of your workflow.
Example:
curl -d "query=SELECT * WHERE {?s ?p ?o}" http://127.0.1.1:8183/testendpointNote: curl is a simple command-line tool which is capable of forming HTTP POST requests.
This will start your workflow. As soon as your plug-in receives its first input the invokeInternal method will be called.