Python adapter

.gitignore

@@ -0,0 +1,3 @@
+.idea
+target
+*.iml

README.md

@@ -1,2 +1,10 @@
 ## USE Monitor
 The USE monitor allows for monitoring running applications and to verify the applications behave as defined in a USE model.
+
+### Requirements
+
+Add the following vm argument to the `use` start script:
+
+```
+--add-exports=jdk.jdi/com.sun.tools.jdi=ALL-UNNAMED
+```

adapter/Python/README.md

@@ -0,0 +1,32 @@
+# USE Monitor Python Adapter
+
+USE monitor plugin that adds support for the monitoring of Python programs.
+
+## Adapter Settings
+- Host: Hostname of the machine, where the debuggee program is located.
+- Port: Port on which the Debugpy server running the Python program is listening to.
+- Workspace: Absolute path to the root directory of the Python program to monitor.
+- Max. Instances: Maximum number of instances that USE should map and display.
+
+## How to use the plugin 
+1. In the USE project under `use/use-core/target` create the following folder structure:
+`mkdir -p lib/plugins/monitor_adapter`
+2. Run `mvn clean package`
+3. Copy the `MonitorAdapter_Python-1.0-SNAPSHOT.jar` to `lib/plugins/monitor_adapter`
+4. Copy the `monitor-1.0-SNAPSHOT.jar` to `lib/plugins`
+5. Copy the `monitor/lib/lablib-checkboxtree-3.2.jar` to `lib`
+6. Add an IntelliJ run configuration with the main class `org.tzi.use.main.Main`, VM option `--add-exports=jdk.jdi/com.sun.tools.jdi=ALL-UNNAMED` and class path `use-gui`
+7. Modify the classpath with the `lib` folder addition
+
+## How to start the Debugpy server
+
+```
+#!/usr/bin/env bash
+
+mkdir -p logs
+
+debugpy \
+    --listen 5678 \
+    --log-to ./logs/ \
+    ./<your_script>.py
+```

adapter/Python/dependency-reduced-pom.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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/maven-v4_0_0.xsd">
+  <parent>
+    <artifactId>plugin_monitor</artifactId>
+    <groupId>org.tzi.use</groupId>
+    <version>1.0-SNAPSHOT</version>
+    <relativePath>../../pom.xml</relativePath>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+  <artifactId>MonitorAdapter_Python</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>3.2.2</version>
+      </plugin>
+      <plugin>
+        <artifactId>maven-shade-plugin</artifactId>
+        <version>3.5.0</version>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  <dependencies>
+    <dependency>
+      <groupId>org.tzi.use</groupId>
+      <artifactId>use-core</artifactId>
+      <version>7.1.1</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.tzi.use</groupId>
+      <artifactId>use-gui</artifactId>
+      <version>7.1.1</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.tzi.use</groupId>
+      <artifactId>monitor</artifactId>
+      <version>1.0-SNAPSHOT</version>
+      <scope>provided</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>lablib-checkboxtree</artifactId>
+          <groupId>it.cnr.imaa.essi</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+  </dependencies>
+</project>

adapter/Python/pom.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.tzi.use</groupId>
+        <artifactId>plugin_monitor</artifactId>
+        <version>1.0-SNAPSHOT</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>MonitorAdapter_Python</artifactId>
+    <version>1.0-SNAPSHOT</version>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.tzi.use</groupId>
+            <artifactId>use-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.tzi.use</groupId>
+            <artifactId>use-gui</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.tzi.use</groupId>
+            <artifactId>monitor</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-annotations</artifactId>
+            <version>2.19.0</version>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>2.19.0</version>
+            <scope>compile</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.2.2</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.5.0</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

adapter/Python/requirements.txt

@@ -0,0 +1 @@
+debugpy==1.18.17

adapter/Python/src/main/java/org/tzi/use/monitor/adapter/python/BreakpointHandler.java

@@ -0,0 +1,199 @@
+package org.tzi.use.monitor.adapter.python;
+
+import org.tzi.use.monitor.adapter.python.dap.custom.DAPValue;
+import org.tzi.use.monitor.adapter.python.dap.StackFrame;
+import org.tzi.use.monitor.adapter.python.dap.StoppedEventClass;
+import org.tzi.use.monitor.plugins.monitor.vm.mm.python.*;
+import org.tzi.use.plugins.monitor.Monitor;
+import org.tzi.use.uml.ocl.value.Value;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.logging.Level;
+
+/**
+ * This class is responsible for handling breakpoint events for
+ * constructor calls and method calls and exits, and informing
+ * the monitor of such events.
+ */
+public class BreakpointHandler implements Runnable {
+
+    private final Monitor.Controller controller;
+    private final PythonAdapter adapter;
+    private final Messenger messenger;
+    private final DebugpyClient debugpyClient;
+
+    public BreakpointHandler(DebugpyClient debugpyClient, PythonAdapter adapter,
+                             Monitor.Controller controller, Messenger messenger) {
+        this.debugpyClient = debugpyClient;
+        this.adapter = adapter;
+        this.controller = controller;
+        this.messenger = messenger;
+    }
+
+    @Override
+    public void run() {
+        while (debugpyClient.isConnected) {
+            try {
+                messenger.breakpointEventFuture = new CompletableFuture<>();
+                StoppedEventClass breakpointEvent = messenger.breakpointEventFuture.get();
+                if (!debugpyClient.isConnected) {
+                    return;
+                }
+                StackFrame currFrame = messenger.getCurrentFrame(Math.toIntExact(breakpointEvent.getBody().getThreadID()));
+                int currLineNo = (int) currFrame.getLine();
+                String file = currFrame.getSource().getPath();
+
+                Map<Integer, String> lineToClass = debugpyClient.fileToClassNameMap.get(file);
+                if (lineToClass == null || !lineToClass.containsKey(currLineNo)) {
+                    controller.newLogMessage(this, Level.WARNING, "No mapped class for " + file + ":" + currLineNo);
+                    debugpyClient.resume();
+                    continue;
+                }
+
+                Map<Integer, BreakpointType> lineToBP = debugpyClient.fileToBreakpointTypeMap.get(file);
+                if (lineToBP == null || !lineToBP.containsKey(currLineNo)) {
+                    controller.newLogMessage(this, Level.WARNING, "No breakpoint type for " + file + ":" + currLineNo);
+                    debugpyClient.resume();
+                    continue;
+                }
+
+                String qualifiedClassName = lineToClass.get(currLineNo);
+                BreakpointType breakpointType = lineToBP.get(currLineNo);
+
+                switch (breakpointType) {
+                    case CONSTRUCTOR_CALL -> onConstructorCall(currFrame, qualifiedClassName);
+                    case METHOD_CALL -> onMethodCall(currFrame, qualifiedClassName);
+                    case METHOD_EXIT -> onMethodExit(currFrame, qualifiedClassName);
+                    case MODIFICATION -> onAttrMod(currFrame, qualifiedClassName);
+                }
+
+                debugpyClient.resume(); // Match monitor running state
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                return;
+            } catch (ExecutionException e) {
+                controller.newLogMessage(this, Level.SEVERE, "Failed to process breakpoint event: " + e.getMessage());
+            }
+        }
+    }
+
+    private void onConstructorCall(StackFrame currentFrame, String fullyQualifiedClassName) {
+        controller.newLogMessage(this, Level.FINE, "onConstructorCall: " + fullyQualifiedClassName + "." + currentFrame.getName());
+
+        PyType pyType = (PyType) controller.getVMType(fullyQualifiedClassName);
+        PyObject pyObject = new PyObject(adapter, messenger.getSelfId(currentFrame.getID()), pyType);
+
+        controller.onNewVMObject(pyObject);
+    }
+
+    private void onMethodCall(StackFrame stackFrame, String fullyQualifiedClassName) {
+        controller.newLogMessage(this, Level.FINE, String.format("onMethodCall: %s.%s", fullyQualifiedClassName, stackFrame.getName()));
+
+        PyType pyType = (PyType) controller.getVMType(fullyQualifiedClassName);
+
+        String methodId;
+        boolean isModuleMethod = pyType == null;
+        if (isModuleMethod) {
+            methodId = String.format("%s:%s.%s", fullyQualifiedClassName, fullyQualifiedClassName, stackFrame.getName());
+        } else {
+            var methods = pyType.getMethodsByName(stackFrame.getName());
+            if (methods.isEmpty()) {
+                controller.newLogMessage(this, Level.WARNING,
+                        "No VM method found for " + fullyQualifiedClassName + "." + stackFrame.getName());
+                return;
+            }
+            methodId = (String) methods.getFirst().getId();
+        }
+
+        PyMethod pyMethod = (PyMethod) controller.getVMMethod(methodId);
+        if (pyMethod == null) {
+            controller.newLogMessage(this, Level.WARNING, "VM method lookup returned null for id: " + methodId);
+            return;
+        }
+
+        Long pyObjId = isModuleMethod
+                ? DebugpyClient.GLOBAL_MODULE_ID
+                : messenger.getSelfId(stackFrame.getID());
+        PyObject pyObject = (PyObject) controller.getVMObject(pyObjId);
+
+        List<Value> argValues = new ArrayList<>();
+        for (String argName : pyMethod.getArgumentNames()) {
+            DAPValue argDAPValue = messenger.getMethodArgDAPValue(stackFrame.getID(), argName);
+            argValues.add(debugpyClient.getUSEValue(argDAPValue));
+        }
+
+        PyMethodCall pyMethodCall = new PyMethodCall(pyMethod, pyObject, argValues);
+
+        controller.onMethodCall(pyMethodCall);
+    }
+
+    private void onMethodExit(StackFrame stackFrame, String qualifiedClassName) {
+        PyType pyType = (PyType) controller.getVMType(qualifiedClassName);
+
+        boolean isModuleMethod = pyType == null;
+
+        String methodId;
+        if (isModuleMethod) {
+            methodId = String.format("%s:%s.%s", qualifiedClassName, qualifiedClassName, stackFrame.getName());
+        } else {
+            var methods = pyType.getMethodsByName(stackFrame.getName());
+            if (methods.isEmpty()) {
+                controller.newLogMessage(this, Level.WARNING, "No VM method found for exit of " +
+                        qualifiedClassName + "." + stackFrame.getName());
+                return;
+            }
+            methodId = (String) methods.getFirst().getId();
+        }
+
+        PyMethod pyMethod = (PyMethod) controller.getVMMethod(methodId);
+        controller.onMethodExit(pyMethod, pyMethod.getId());
+    }
+
+    private void onAttrMod(StackFrame stackFrame, String qualifiedClassName) {
+        controller.newLogMessage(this, Level.FINE, "onAttributeModification: " + qualifiedClassName + "." + stackFrame.getName());
+
+        boolean isSetter = stackFrame.getName().startsWith("set");
+        if (!isSetter) {
+            controller.newLogMessage(this, Level.WARNING, "Wrongly stopped at non-setter method for attribute modification!");
+            return;
+        }
+
+        String attrName = stackFrame.getName().substring(4);
+
+        Long pyObjId = messenger.getSelfId(stackFrame.getID());
+        PyObject pyObject = (PyObject) controller.getVMObject(pyObjId);
+
+        PyField pyField = (PyField) pyObject.getType().getFieldByName(attrName);
+        if (pyField == null) {
+            controller.newLogMessage(this, Level.WARNING,
+                    "Cannot determine target attribute for setter: " + stackFrame.getName());
+            return;
+        }
+
+        var methods = pyObject.getType().getMethodsByName(stackFrame.getName());
+        if (methods.isEmpty()) {
+            controller.newLogMessage(this, Level.WARNING, "No VM method found for attribute modification on " +
+                    qualifiedClassName + "." + stackFrame.getName());
+            return;
+        }
+        String methodId = (String) methods.getFirst().getId();
+
+        PyMethod m = (PyMethod) controller.getVMMethod(methodId);
+
+        if (m != null) {
+            if (m.getArgumentNames().size() == 1) {
+                DAPValue argDAPValue = messenger.getMethodArgDAPValue(stackFrame.getID(), m.getArgumentNames().getFirst());
+                Value useValue = debugpyClient.getUSEValue(argDAPValue);
+                controller.onUpdateAttribute(pyObjId, pyField.getId(), useValue);
+            } else {
+                controller.newLogMessage(this, Level.WARNING,
+                        String.format("Could not resolve new value for attribute %s! Expected 1 setter method argument. Found: %d",
+                                pyField.getName(), m.getArgumentNames().size()));
+            }
+        }
+    }
+}

adapter/Python/src/main/java/org/tzi/use/monitor/adapter/python/BreakpointType.java

@@ -0,0 +1,8 @@
+package org.tzi.use.monitor.adapter.python;
+
+public enum BreakpointType {
+    METHOD_CALL,
+    METHOD_EXIT,
+    CONSTRUCTOR_CALL,
+    MODIFICATION
+}