Configure local JVM agent attachment

The JVM agent attachment mechanism with JMX-based access is designed to attach to a target Java process running on the same physical machine and upload a JVM agent that exposes the user interface (UI) structure of the target application. This functionality is designed to navigate and automate Java-based UIs, such as applets.

The attachment process supports target applications running on any long-term support (LTS) version of the Java Development Kit (JDK)—namely Java 8, 11, 17, and 21—from within a Worker application running on JDK 21.

This logic ensures cross-version compatibility, especially with Java 8, which is not fully compatible with newer versions in terms of tooling APIs, such as com.sun.tools.attach.

Configuration parameters

The application accepts the following system properties to locate the required JDKs and JARs:

-Djdk8.x64.path=<path-to-jdk8> ^
-Djdk21.x64.path=<path-to-jdk21> ^
-Drpa.jvm.dependency.dir=../rpa-grid/dependency ^

If specific paths to JARs are required, you can override the defaults with:

-Drpa.jvm.connector.java8.path=<path-to-java8-connector/jvm-connector.jar> ^
-Drpa.jvm.connector.java21.path=<path-to-java21-connector/jvm-connector.jar> ^
-Drpa.jvm.agent.java8.path=<path-to-java8-connector/rpa-jvmagent.jar> ^
-Drpa.jvm.agent.java11.path=<path-to-java11-connector/rpa-jvmagent.jar> ^
-Drpa.jvm.agent.java21.path=<path-to-java21-connector/rpa-jvmagent.jar> ^

If you need to explicitly use remote TargetJVMAttacher, set the corresponding property to true:

-Drpa.jvm.connector.remote=true ^

Attacher implementations

There are two strategies for attaching to the target JVM:

• DefaultJVMAttacher

  • Used within the main application process (JDK 21)

  • Instantiated with:

  new DefaultJVMAttacher(int pid, String agentPath).attach();
  • Used only if the target process is not running on JDK 8 and the rpa.jvm.connector.remote property is not set to true

• TargetJVMAttacher (Proxy)

  • Used when cross-JDK compatibility issues can arise (especially for Java 8 targets)

  • Launches a separate helper process (jvm-connector.jar) compiled and run on a JDK version compatible with the target JVM

  • Internally, this executes:

    new DefaultJVMAttacher(pid, agentPath).attach();

• The JVM agent (rpa-jvmagent.jar) must also be compiled for the same JDK version as the target.

The compatibility matrix is as follows:

Target JDK	JVM connector compiled on	JVM agent compiled on	JVM connector runs on
Java 8	Java 8	Java 8	Java 8
Java 11	Java 11	Java 11	Java 21
Java 17	Java 11	Java 11	Java 21
Java 21	Java 21	Java 21	Java 21

How it works

1. The main application determines the JDK version of the target process using com.sun.tools.attach.VirtualMachine:

   VirtualMachine.attach(pid).getSystemProperties().getProperty("java.version");

   This version is normalized to the closest LTS version.

2. The attachment strategy selection is based on the detected version. If the target is JDK 8 or rpa.jvm.connector.remote=true, use TargetJVMAttacher. Otherwise, use DefaultJVMAttacher.

3. If a proxy is needed, do the following:

   • Locate appropriate jvm-connector.jar and rpa-jvmagent.jar via explicit system properties or by inferring them from rpa.jvm.dependency.dir.

   • Launch the connector JAR in a new JVM process on the appropriate JDK (8 or 21) as per the compatibility matrix.

4. The agent is injected into the target process using VirtualMachine.loadAgent(). The agent sets up a JMX server and returns a JMX connector address.

5. The main application connects to the target JVM via the returned connector address. The UI structure is retrieved via the exposed MBeans.

The functionality benefits are as follows:

• Cross-JDK compatibility: safely interacts with older JVMs from Java 21.

• Version-safe attachments: prevents runtime errors between different JDKs.

• Configurable paths: all JDKs and JARs can be explicitly configured.

• Future-proof: easily extensible to future LTS JDKs.

Troubleshooting

• Ensure required JDKs are installed and accessible via jdk*.x64.path.

• Confirm the presence of correct jvm-connector.jar and rpa-jvmagent.jar.

• For Java 8, both the Connector and JVM must be compiled and run using JDK 8.

• Check for these common log messages:

  • "Failed to detect JDK version for PID"

  • "Unable to attach to target JVM. Process exit code"

  • "Unable to find JMX address for target JVM"

  • "Not found at path"

  • "Unknown version format"