added README.md & documentation + some cleanups

Author: mtf90

README.md

@@ -0,0 +1,75 @@
+# learnlib-py4j-example
+
+This example shows how to learn a python-based system under learning (SUL) using [LearnLib][learnlib].
+
+This example is a *python-first* example, meaning the core of our setup is written in Python and we use [Py4J][py4j] in order to use the Java based LearnLib from our Python program.
+
+If you want a *java-first* approach, you may look into technologies such as [Jython][jython] which allows you to run Python programs on the JVM. If you want to go deeper down that rabbit hole, [GraalVM][graal] may be worth a look as well.
+
+
+## Requirements
+
+In order to run the Java side of the example you need to have a working [JDK][jdk] 8+ installation.
+OpenJDK should work just as well as OracleJDK.
+Furthermore, we use [Maven][maven] in order to build our LearnLib-Py4J connector.
+
+---
+
+For the Python side of this example you need to have a working [Python][python] installation.
+The example has only been tested with Python3 - Python2 may or may not work.
+We strongly suggest to install the [`virtualenv`][venv] tool in order setup the Python side of Py4J without affecting your global Python installation - although technically you only need to have the `python-py4j` libraries installed somewhere.
+
+---
+
+In order to show the learned hypothesis automata, we suggest to install [GraphVIZ][graphviz].
+However, if GraphVIZ (more specifically, `DOT`) is not installed, LearnLib will fallback to the [JUNG][jung] library, which is a fully Java-based visualization approach.
+
+
+## Preparing the example
+
+
+First, we will build the Java side of this example, which will leave us with an executable JAR containing the LearnLib and Py4J code.
+
+```
+cd java
+mvn package
+cd ..
+```
+
+---
+
+Then, we setup our virtual python environment and install the py4j libraries
+
+```
+virtualenv python/venv
+source python/venv/bin/activate
+pip install py4j==0.10.8.1
+```
+
+## Running the example
+
+To run the example, we first start our JVM process that listens for any calls performed by our Python programm (via the Py4J framework):
+
+`java -jar java/target/learnlib-py4j-example-1.0-SNAPSHOT.jar`
+
+---
+
+Then, we simply run our Python program:
+
+`python python/Main.py`
+
+---
+
+Once we are finished, the JVM process can be terminated by pressing <kbd>Ctrl</kbd> + <kbd>C</kbd> 
+
+
+[learnlib]: https://github.com/LearnLib/learnlib
+[py4j]: https://www.py4j.org/
+[jython]: http://www.jython.org/
+[graal]: https://www.graalvm.org/
+[jdk]: https://www.oracle.com/technetwork/java/javase/overview/index.html
+[maven]: https://maven.apache.org/
+[python]: https://www.python.org/
+[venv]: https://virtualenv.pypa.io
+[graphviz]: http://www.graphviz.org/
+[jung]: http://jung.sourceforge.net/

java/pom.xml

@@ -27,12 +27,14 @@ limitations under the License.
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 
-        <!-- AutomataLib requires Java 8 -->
+        <!-- LearnLib requires Java 8 -->
         <maven.compiler.source>1.8</maven.compiler.source>
         <maven.compiler.target>1.8</maven.compiler.target>
 
         <!-- Version of LearnLib to use -->
         <learnlib.version>0.13.1</learnlib.version>
+        <py4j.version>0.10.8.1</py4j.version>
+        <shade-plugin.version>3.2.1</shade-plugin.version>
     </properties>
 
     <dependencyManagement>
@@ -57,7 +59,7 @@ limitations under the License.
         <dependency>
             <groupId>net.sf.py4j</groupId>
             <artifactId>py4j</artifactId>
-            <version>0.10.8.1</version>
+            <version>${py4j.version}</version>
         </dependency>
 
         <!-- provide an SLF4J implementation -->
@@ -73,7 +75,7 @@ limitations under the License.
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-shade-plugin</artifactId>
-                <version>3.2.1</version>
+                <version>${shade-plugin.version}</version>
                 <executions>
                     <execution>
                         <phase>package</phase>

python/Main.py

@@ -1,6 +1,6 @@
 from py4j.java_gateway import JavaGateway, CallbackServerParameters
 
-
+# This class represents the Python side implementation of our system under learning (SUL)
 class PySUL:
 
     def __init__(self, gateway):
@@ -29,26 +29,36 @@ class Java:
 
 
 def main():
+    # Create our connection to the JVM process
     gateway = JavaGateway(callback_server_parameters=CallbackServerParameters())
 
+    # Instantiate our Python SUL and get the learning alphabet
     sul = PySUL(gateway)
     alphabet = sul.alphabet
 
+    # Construct the membership oracle
     mq_oracle = gateway.jvm.de.learnlib.oracle.membership.SULOracle(sul)
+
+    # Construct the equivalence oracle
     eq_oracle = gateway.jvm.de.learnlib.oracle.equivalence.WMethodEQOracle(mq_oracle, 3)
 
+    # Construct the learning algorithm (here TTT)
     ttt = gateway.jvm.de.learnlib.algorithms.ttt.mealy.TTTLearnerMealyBuilder() \
         .withAlphabet(alphabet) \
         .withOracle(mq_oracle) \
         .create()
 
+    # Construct the experiment, that runs the active learning loop until no more counterexamples can be found.
     experiment = gateway.jvm.de.learnlib.util.Experiment(ttt, eq_oracle, alphabet)
     experiment.run()
 
+    # Get the final hypothesis of our SUL
     hyp = experiment.getFinalHypothesis()
 
+    # Construct a buffer that we will use to print results on the Python side of our setup
     string_writer = gateway.jvm.java.io.StringWriter()
 
+    # Serialize the hypothesis to the DOT format and write it to the string_writer
     gateway.jvm.net.automatalib.serialization.dot.GraphDOT.write(hyp, alphabet, string_writer,
                                                                  # While varargs allow us to skip this parameter in Java, the method signature expects an array \
                                                                  gateway.new_array(
@@ -59,12 +69,14 @@ def main():
     print()
     print(string_writer.toString())
 
+    # Visualize the hypothesis
     gateway.jvm.net.automatalib.visualization.Visualization.visualize(hyp, alphabet,
                                                                       # While varargs allow us to skip this parameter in Java, the method signature expects an array \
                                                                       gateway.new_array(
                                                                           gateway.jvm.net.automatalib.visualization.VisualizationHelper,
                                                                           0))
 
+    # Close our connection
     gateway.close()