• LarkcProject
• WP5
• PlatformManual

Page Outdated!

See LarKC_PlatformManual_V1_0.pdf

Getting started guide - Page Outdated!

1. Installation

1.1. Prerequisites

The following software is required to be installed on your machine for working with LarKC:

• Java development kit (tested with version 1.6)

• Apache Ant tool for the deployment or one of Java IDEs (like Eclipse , Netbeans etc.) for the development

• one of the SVN clients for downloading the code from the source code repository (if necessary):

  • TortoiseSVN

  • CollabNet SVN

  • a command line client (for Linux, please see the Link for more details)

1.2. Getting the Source Code

The source code of LarKC is available for downloading at LarKC@SourceForge development environment (please refer to the link above for more details). By means of LarKC@SourceForge, the LarKC users may either download the latest release (via web browser, any additional tools are required) or check out the main development version (trunk) from the source code repository, using special client tools (see the Prerequisites section for more details).

1.2.1. Getting the Source Code from the latest releases

The latest releases are available at the Link

1.2.2. Getting the Source Code from the LarKC repository

The latest source code for the platform and plug-ins can be checked-out from the project SVN repository (https://larkc.svn.sourceforge.net/svnroot/larkc/trunk/platform) and (https://larkc.svn.sourceforge.net/svnroot/larkc/trunk/plugins) using any SVN client.

1.2.2.1. Using command line SVN client (mainly for Linux users)

me@myComp:~/$ svn checkout --username yourname https://larkc.svn.sourceforge.net/svnroot/larkc/trunk/ LarKC

This will download the platform and all of the example plug-ins developed by LarKC consortium into 2 separate directories. It is also possible to check-out platform and plug-ins separately and also to check-out each plug-in separately from the plugin directory tree.

1.2.2.2. Using TortoiseSVN (for Windows users)

To check-out the code using TortoiseSVN tool, please create the directory where you want to have the platform and the plug-ins, for example ./LarKC and then in windows explorer right click and pick SVN Checkout option.

Image 1: Check-out using TortoiseSVN

For the URL of repository enter the https://larkc.svn.sourceforge.net/svnroot/larkc/trunk and click OK.

Image 2: Check-out using TortoiseSVN

1.3. Source Code Structure

The Source Code of LarKC consists of two essential parts: a Platform and a Plug-in Collection.The Platform is the main LarKC feature which enables the Plug-in development, construction in a workflow and running the experiments.

Five main Plug-in types are recongized for LarKC: Decider, Identifier, Reasoner, Selector, Transformer

The structure of a single Plug-in is as follows:

• plug-ins / plug-in type [Decide, Identify, Reason, Select, Transform] / ...

• ...Plug-in name / lib - for storing the libs, src - the source code

The Plug-in collection contains template for each Plug-in type ("template_type"), which might be beneficial for constructing new plug-ins of the corresponding type.

In the current design, the Platform (or a single Plug-in) are separate software projects which are compiled separately.The only prerequisite for compiling Plug-ins is availability of the compiled Platform code.

1.4. Working with the Source Code

1.4.1. Costructing Workflows

There are three ways to register the plug-ins to the platform:

• copy them under the ./plugins/ directory where each plug-in have its own directory.
• copy the plug-in distribution files (.larkc) to the ./plugins/ directory
• modify the ./conf/plugins.ini file, to point to the appropriate plug-in wsdl file, directory or .larkc file

When registering plug-ins, please make sure that you only have one decider. Platform will use only the last decider being registered.

1.4.2. Deployment using the ANT Tool

As the first step (after downloading [and unpacking in case of the release version] ), build the platform by means of the "ant" command from the platform/ directory.

me@myComp:~/larkc/$ cd platform
me@myComp:~/larkc/platform$ ant
Buildfile: build.xml

init:
    [mkdir] Created dir: /home/eyal/larkc/platform/bin
    [mkdir] Created dir: /home/eyal/larkc/platform/dist

compile:
    [javac] Compiling 700 source files to /home/eyal/larkc/platform/bin
    [javac] Note: Some input files use or override a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.

dist:
      [jar] Building jar: /home/eyal/larkc/platform/dist/larkc-platform.jar
     [copy] Copying 7 files to /home/eyal/larkc/platform/dist
     [copy] Copying 42 files to /home/eyal/larkc/platform/dist/ext
     [copy] Copying 14 files to /home/eyal/larkc/platform/dist/conf

BUILD SUCCESSFUL
Total time: 23 seconds

The built platform components are placed in the platform/dist directory:

me@myComp:~/larkc/$ cd platform/dist
me@myComp:~/larkc/platform$ ls -la
bin/
conf/
ext/
plugins/
run-larkc.bat
run-larkc.sh

Once the platform build has successfuly finished, the plug-ins can be built.

After the workflow is constructed, that means that all the plug-ins combined in the workflow are copied to to the plugins/ directory (please refer to Constrcution Workflows Section for details), simply execute "ant" in the plug-ins/ directory for building the plug-in collection, similarly as described above for the platform. The outcome of the building process is a set of .larkc files (corresonding to each plug-in in the workflow) in the platform/dist/plugins directory.

me@myComp:~/larkc/platform$ cd ../plugins/
me@myComp:~/larkc/plugins$ ant

...
BUILD SUCCESSFUL

After the plug-ins are successfully built, the workflow can be started using the run-larkc command (.sh for linux or .bat for windlows) from the platform/dist folder.

1.4.3. Developing the Code using Eclipse IDE

First, you have to check out the code, as described in chapter 1.2.

After you have the code on your disk, open Eclipse, and when it asks for the workspace directory, please make sure that the directory where you checked out the platform and plug-ins is not in the direct subtree of the workspace directory.

After it starts in the File menu, pick the Import sub menu (File>Import).

In the import window, pick the "Existing Projects into Workspace" option:

Image 1: importing project to Eclipse

Then in the next window, click on the first Browse button, and pick the directory, where you have checked out the platform and plug-ins. After this, just click finish and the platform and plug-in projects will be imported.

Because the platform needs to have plug-ins registered, all the plug-in projects have build output directory linked to the PLATFORM_ROOT/plugins/PluginName directory. This makes it easier to develop and test plug-ins together with the platform. To set up the PLATFORM_ROOT, go to menu Window ->Preferences and then in the side menu go to General->Workspace->Linked Resources and click New and then Folder.

Image 1: Add PLATFORM_ROOT variable

In order to run/debug the platform inside the Eclipse, you have to set up the Eclipse's run configuration. You do that by clicking on the arrow next to the green "play" button and then the Run Configurations... option:

Image 2: run configuration

On the Run Configurations window, which opens, create new Java Application (left side), and then under name enter the configuration name you want to have. For example platform. Under the Project, pick the project into which you imported the platform, and under Main class, write eu.larkc.core.Larkc. See image 3:

Image 3: run configuration window

Then if you use 32bit Java, click on the tab "Arguments" and under "VM arguments" add "-Xmx512m" as seen on the image. Parameter "VM arguments" is only needed if you are running 32bit version of Java, or running out of memory because of your plug-ins:

Image 4: run configuration window command line arguments

LarKC Platform is now ready to run (without the plug-ins).

1.4.3.1. Plugins

First you have to check out the code, as described in chapter 1.1 (...trunk/plugins).

After you have the plugins project and source code on your disk, please repeat the importing project step as described in 1.2.1 for the platform, but this time for the plugins.

1.4.3.2. Putting it together

In order to be able to run the plug-ins from the plugins project inside the Platform project, both projects (or at least the plug-ins you would want to use) must be built successfully.

Plugins project default settings after check-out are set up, to build into a /bin subdirectory. This is also the default location where the platform will check for the plug-ins (please check the plugins.ini file).

If everything builds, and the plug-in doesn't need any special libraries, the platform should be already able to run it.

In case, when the plug-in uses some .jar files, not known to the platform, those files have to be included in the platforms class-path. The easiest way to do that is to right click the Platform project, and pick Build path -> Configure Build Path and then in the window that opens, go to the tab Libraries and click Add External JARs.

Default platform checkout uses ?UrbanCity plug-ins, which DO need external libraries.

After the platform server is up and running a Decider and other plug-ins, it can be queried using some sort of SPARQL client (ie.Example-test windows SPARQL client).

When debugging the plug-ins for the first time (ie set a breakpoint somewhere in your plug-in), the Eclipse may report: "Source not found". In this case, just click the "Edit Source Lookup Path", then "Add" -> "Java Project", check the Plugins project and click the "OK" button.

1.4.4. Using Netbeans

1.4.5. Development of the new Plug-ins

For the development issues, it might be beneficial to use to use the special templates the plug-in collection in the LarKC repository is supplied with.

Therefore, the users are advised to create a new entry in the corresponding folder of the plugin/ directory and copy the template files there.

Please note, that if you use the version checked out from the source code repository, the copying should be done by means of the "svn copy" command, or its equivalent in the graphical client used