Freeplane Remote Server Plugin

https://github.com/Docear/Desktop/tree/htw

The Freeplane Remote Plugin makes it possible to control Freeplane from the outside.
It can react to all actions that are defined through the HTW-Messages project.
The plugin is an OSGI-bundle, which depends on Freeplane and uses an Akka Actor to handle requests.

Instructions to run

1. Get latest version at: https://ci.docear.org/ci/job/Docear-Desktop-freeplane/ws/freeplane_framework/dist/freeplane_server.zip
2. unzip
3. run freeplane.sh / freeplane.bat The Frontend/API-Server can now communicate with Freeplane

Notes:

• When killing Freeplane make sure, that no RUNNING_PID is present anymore. Otherwise you cannot execute it again

Currently only one instance per system

At the moment it is only possible to run Freeplane Headless at a time. To assure this we implemented the creation of a RUNNING_PID on start up. This file contains the PID of the current Freeplane process. In case you have to kill Freepane hard, you need to delete the RUNNING_PID to restart it again.

Usage / Communication

All communication with the plugin are based on Akka.
For more infos on why we use Akka see the page Why Akka.

Requirements

• Java or Scala based application
• This project uses Akka Version 2.10 and the following artefacts:
  • <dependency org="com.typesafe.akka" name="akka-actor_2.10" rev="2.1.0"/>
  • <dependency org="com.typesafe.akka" name="akka-remote_2.10" rev="2.1.0"/>
• Current version of HTW-Messages project
• application.conf in your class path. (Example application.conf)

Sample

A demonstration of how you can communicate with the Remote plugin can be found here

Dependencies

• Dependencies are managed through Apache Ivy.
• The dependencies are stored in the /ivy.xml-file.
• Please try to only use managed dependencies!

Add a new managed dependencies

1. find, where the library is hosted.
2. Normally google for <library name> maven (e.g. akka remote maven)
3. Pick the version you need (if not sure, take the most popular/newest release)
4. Copy the "Ivy"-dependency to the /ivy.xml-file
5. Open terminal / command prompt in /ant-folder
6. Execute ant lib_fileset
   For Eclipse
7. Refresh project
8. Add new .jar-files in /lib-folder to classpath

Logging

The logging engine we use is Logback. Logback is also used by the Play Framework, which we use for our Frontend/API-Server. It comes with a rolling log-file implementation and can easily be used to generated several files with different log-levels from one logging stream.

Logging Configuration

Currently we log to two different files.

	Full log	info-level and above
File Location	/var/log/mindmap-backend/application.log	/var/log/mindmap-backend/application-info.log
Roll Over Rule	daily	daily
Size Limit	100 MB	100 MB

How to log

The logger can be accessed via RemoteController.getLogger().
The following log-levels are supported in that order: debug, info, warn, error.

• debug should be used for not important output about current state and method calls.
• info should be used for interesting data, like which user logged in or jobs that get executed.
• warn should be used for events that might cause issues or are not intendend. (e.g. a user tries to open a map he does not own)
• error should be used for unrecognized and unhandled exceptions.

A logging can look like:

//Please use placeholders and no string concatenation, because it boosts the performance
RemoteController.getLogger().info("User {} accessed map with id {}", username, mapId);

Tests

The tests can be found in an extra project called freeplane_plugin_remote_tests.
They are based on JUnit and for every possible request should be at least one test.

How to run tests

Tests can be run on a local freeplane headless instance.

1. Start Freeplane Headless
2. Execute Tests project