feat(core): add TestElementUpgrader SPI for load-time property upgrades

SaveService can rename keys and classes on load via NameUpdater, but it cannot
transform property *values*. Add a TestElementUpgrader service interface,
discovered with ServiceLoader, that upgrades legacy properties on a loaded test
plan. SaveService runs all registered upgraders to a fix point after reading a
plan, so chained upgrades converge without numbering the migrations.

Add the first upgrader: an HTTP-side ResponseProcessingModeUpgrader maps the
legacy HTTPSampler.md5 flag to responseProcessingMode. It keys off the property
name, so it upgrades both HTTP samplers and HTTP Request Defaults (a
ConfigTestElement), which core cannot reference directly.

This normalises old plans into the new property on load and on re-save. Runtime
correctness for plans built another way still relies on
getResponseProcessingMode() falling back to the legacy flag.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: vlsi

src/core/src/main/java/org/apache/jmeter/save/SaveService.java

@@ -455,7 +455,12 @@ private static HashTree readTree(InputStream inputStream, File file)
                 log.error("Problem loading XML: see above.");
                 return null;
             }
-            return wrapper.testPlan;
+            HashTree testPlan = wrapper.testPlan;
+            // Upgrade legacy property values (e.g. HTTPSampler.md5 -> responseProcessingMode) right after
+            // load, so the in-memory tree and any re-save use the current representation. NameUpdater only
+            // renames keys/classes, so value transforms live in TestElementUpgrader services instead.
+            TestElementUpgraders.upgrade(testPlan);
+            return testPlan;
         } catch (CannotResolveClassException | ConversionException | NoClassDefFoundError e) {
             if(file != null) {
                 throw new IllegalArgumentException("Problem loading XML from:'"+file.getAbsolutePath()+"'. \nCause:\n"+

src/core/src/main/kotlin/org/apache/jmeter/save/TestElementUpgrader.kt

@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jmeter.save
+
+import org.apache.jmeter.testelement.TestElement
+import org.apache.jorphan.reflect.JMeterService
+import org.apiguardian.api.API
+
+/**
+ * Upgrades a [TestElement] loaded from an older test-plan format, transforming legacy properties
+ * into their current representation.
+ *
+ * Unlike [org.apache.jmeter.util.NameUpdater], which only renames property keys and element
+ * classes, an upgrader can transform property *values* — for example, a boolean flag into an enum
+ * resource key.
+ *
+ * Implementations are discovered with [java.util.ServiceLoader], so register them with
+ * `@AutoService(TestElementUpgrader::class)`.
+ *
+ * Implementations must be **idempotent** and **forward-only**:
+ * - running [upgrade] on an already-current element returns `false` and changes nothing;
+ * - an upgrade never re-creates the legacy shape it just removed.
+ *
+ * These rules let [TestElementUpgraders] run every upgrader to a fix point, so chained upgrades
+ * (one property migrated, then migrated again later) converge regardless of registration order,
+ * without numbering the migrations.
+ *
+ * @since 6.0.0
+ */
+@JMeterService
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public fun interface TestElementUpgrader {
+    /**
+     * Upgrades a single element in place.
+     *
+     * @param element the element to inspect and, if it carries a legacy shape, upgrade
+     * @return `true` if the element was modified, `false` otherwise
+     */
+    public fun upgrade(element: TestElement): Boolean
+}

src/core/src/main/kotlin/org/apache/jmeter/save/TestElementUpgraders.kt

@@ -0,0 +1,125 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jmeter.save
+
+import org.apache.jmeter.testelement.TestElement
+import org.apache.jmeter.util.JMeterUtils
+import org.apache.jorphan.collections.HashTree
+import org.apache.jorphan.reflect.LogAndIgnoreServiceLoadExceptionHandler
+import org.apiguardian.api.API
+import org.slf4j.LoggerFactory
+import java.util.ServiceLoader
+
+/**
+ * Discovers [TestElementUpgrader] services and applies them to a loaded test plan.
+ *
+ * Each element is upgraded to a fix point: every upgrader is applied to the element repeatedly
+ * until a pass changes nothing. Because each upgrader is idempotent, forward-only, and touches only
+ * the element it is given, a chain of upgrades on the same property converges without any ordering
+ * metadata, and elements can be upgraded independently of each other.
+ *
+ * @since 6.0.0
+ */
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public object TestElementUpgraders {
+    private val log = LoggerFactory.getLogger(TestElementUpgraders::class.java)
+
+    private val upgraders: List<TestElementUpgrader> = load()
+
+    private fun load(): List<TestElementUpgrader> =
+        try {
+            JMeterUtils.loadServicesAndScanJars(
+                TestElementUpgrader::class.java,
+                ServiceLoader.load(TestElementUpgrader::class.java),
+                Thread.currentThread().contextClassLoader,
+                LogAndIgnoreServiceLoadExceptionHandler(log)
+            ).toList()
+        } catch (e: Exception) {
+            log.error("Unable to load TestElementUpgrader services", e)
+            emptyList()
+        }
+
+    /**
+     * Applies every registered upgrader to every [TestElement] in the tree.
+     *
+     * @param tree the loaded test plan to upgrade in place
+     */
+    @JvmStatic
+    public fun upgrade(tree: HashTree) {
+        if (upgraders.isEmpty()) {
+            return
+        }
+        // Walk the tree iteratively (no recursion) and upgrade each element as it is visited. Property
+        // upgrades change only an element's own properties, not the tree structure, and HashTree keys
+        // by identity (IdentityHashMap), so editing an element in place during the walk is safe and
+        // needs no separate "collect to a list" pass. A future structural phase would run before this
+        // one, so the tree shape is already stable here.
+        val pending = ArrayDeque<HashTree>()
+        pending.addLast(tree)
+        while (pending.isNotEmpty()) {
+            val subTree = pending.removeLast()
+            for (node in subTree.list()) {
+                if (node is TestElement) {
+                    upgrade(node)
+                }
+                pending.addLast(subTree.getTree(node))
+            }
+        }
+    }
+
+    private fun upgrade(element: TestElement) {
+        // A forward-only chain on one property settles within `upgraders.size` passes; the extra pass
+        // confirms convergence, and the bound stops a misbehaving (cyclic) upgrader from looping forever.
+        val maxPasses = upgraders.size + 1
+        var pass = 0
+        var changed = true
+        while (changed && pass < maxPasses) {
+            changed = false
+            for (upgrader in upgraders) {
+                changed = applyUpgrader(upgrader, element) || changed
+            }
+            pass++
+        }
+        if (changed) {
+            log.warn(
+                "TestElement upgraders did not converge for {} after {} passes; some legacy properties may remain",
+                describe(element), maxPasses
+            )
+        }
+    }
+
+    private fun applyUpgrader(upgrader: TestElementUpgrader, element: TestElement): Boolean =
+        try {
+            val changed = upgrader.upgrade(element)
+            if (changed && log.isDebugEnabled) {
+                log.debug("{} upgraded {}", upgrader.javaClass.name, describe(element))
+            }
+            changed
+        } catch (e: Exception) { // NOSONAR one bad upgrader must not make the whole plan unloadable
+            // Surfaced at ERROR so it is visible without enabling debug logging: name the element the
+            // user can recognise, say what happened, and that the element was left as-is.
+            log.error(
+                "Failed to upgrade {} from an older JMeter format; leaving it unchanged. Failing upgrader: {}",
+                describe(element), upgrader.javaClass.name, e
+            )
+            false
+        }
+
+    private fun describe(element: TestElement): String =
+        "element '${element.name}' (${element.javaClass.name})"
+}

src/protocol/http/src/main/kotlin/org/apache/jmeter/protocol/http/sampler/ResponseProcessingModeUpgrader.kt

@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jmeter.protocol.http.sampler
+
+import com.google.auto.service.AutoService
+import org.apache.jmeter.protocol.http.sampler.HTTPSamplerBase.ResponseProcessingMode
+import org.apache.jmeter.save.TestElementUpgrader
+import org.apache.jmeter.testelement.TestElement
+import org.apiguardian.api.API
+
+/**
+ * Upgrades the legacy `HTTPSampler.md5` boolean property to `HTTPSampler.responseProcessingMode`.
+ *
+ * It keys off the property name, not the element class, so it upgrades both HTTP samplers and HTTP
+ * Request Defaults (a `ConfigTestElement`). `md5=true` becomes the decoded-MD5 checksum mode (the
+ * historical "Save as MD5" behaviour); `md5=false` becomes "store the response", which keeps it as
+ * an explicit choice that still overrides a value inherited from HTTP Request Defaults.
+ *
+ * @since 6.0.0
+ */
+@AutoService(TestElementUpgrader::class)
+@API(status = API.Status.INTERNAL, since = "6.0.0")
+public class ResponseProcessingModeUpgrader : TestElementUpgrader {
+    override fun upgrade(element: TestElement): Boolean {
+        val schema = HTTPSamplerBaseSchema.INSTANCE
+
+        @Suppress("DEPRECATION")
+        val md5 = element.getPropertyOrNull(schema.storeAsMD5)?.booleanValue ?: return false
+        // Keep an already-set mode (idempotent, and a newer property wins over the legacy flag).
+        if (element.getPropertyOrNull(schema.responseProcessingMode.name) == null) {
+            val mode = if (md5) {
+                ResponseProcessingMode.CHECKSUM_DECODED_MD5
+            } else {
+                ResponseProcessingMode.STORE_COMPRESSED
+            }
+            element[schema.responseProcessingMode] = mode.resourceKey
+        }
+        @Suppress("DEPRECATION")
+        element.removeProperty(schema.storeAsMD5)
+        return true
+    }
+}

src/protocol/http/src/test/kotlin/org/apache/jmeter/protocol/http/sampler/ResponseProcessingModeUpgradeOnLoadTest.kt

@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jmeter.protocol.http.sampler
+
+import org.apache.jmeter.config.ConfigTestElement
+import org.apache.jmeter.protocol.http.sampler.HTTPSamplerBase.ResponseProcessingMode
+import org.apache.jmeter.save.TestElementUpgraders
+import org.apache.jmeter.testelement.property.BooleanProperty
+import org.apache.jorphan.collections.ListedHashTree
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+
+/**
+ * End-to-end check of the [TestElementUpgraders] driver with the ServiceLoader-registered
+ * [ResponseProcessingModeUpgrader], mirroring what SaveService runs after loading a test plan.
+ */
+class ResponseProcessingModeUpgradeOnLoadTest {
+    private val md5 = "HTTPSampler.md5"
+    private val mode = HTTPSamplerBaseSchema.INSTANCE.responseProcessingMode.name
+
+    @Test
+    fun upgradesBothSamplerAndHttpRequestDefaults() {
+        val sampler = HTTPSamplerProxy().apply { setProperty(BooleanProperty(md5, true)) }
+        // HTTP Request Defaults are a ConfigTestElement; the upgrader keys off the property name,
+        // so it must be upgraded too.
+        val defaults = ConfigTestElement().apply { setProperty(BooleanProperty(md5, false)) }
+
+        val tree = ListedHashTree()
+        tree.add(sampler)
+        tree.add(defaults)
+
+        TestElementUpgraders.upgrade(tree)
+
+        assertEquals(ResponseProcessingMode.CHECKSUM_DECODED_MD5.resourceKey, sampler.getPropertyAsString(mode))
+        assertEquals("", sampler.getPropertyAsString(md5), "the sampler's legacy md5 must be removed")
+
+        assertEquals(ResponseProcessingMode.STORE_COMPRESSED.resourceKey, defaults.getPropertyAsString(mode))
+        assertEquals("", defaults.getPropertyAsString(md5), "the defaults' legacy md5 must be removed")
+    }
+}

src/protocol/http/src/test/kotlin/org/apache/jmeter/protocol/http/sampler/ResponseProcessingModeUpgraderTest.kt

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.jmeter.protocol.http.sampler
+
+import org.apache.jmeter.protocol.http.sampler.HTTPSamplerBase.ResponseProcessingMode
+import org.apache.jmeter.testelement.property.BooleanProperty
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+
+class ResponseProcessingModeUpgraderTest {
+    private val upgrader = ResponseProcessingModeUpgrader()
+    private val md5 = "HTTPSampler.md5"
+    private val mode = HTTPSamplerBaseSchema.INSTANCE.responseProcessingMode.name
+
+    @Test
+    fun md5TrueBecomesChecksumDecodedMd5() {
+        val element = HTTPSamplerProxy()
+        element.setProperty(BooleanProperty(md5, true))
+
+        assertTrue(upgrader.upgrade(element))
+        assertEquals(ResponseProcessingMode.CHECKSUM_DECODED_MD5.resourceKey, element.getPropertyAsString(mode))
+        assertEquals("", element.getPropertyAsString(md5), "the legacy md5 property must be removed")
+        assertFalse(upgrader.upgrade(element), "a second run is a no-op (idempotent)")
+    }
+
+    @Test
+    fun md5FalseBecomesStoreCompressed() {
+        val element = HTTPSamplerProxy()
+        element.setProperty(BooleanProperty(md5, false))
+
+        assertTrue(upgrader.upgrade(element))
+        assertEquals(ResponseProcessingMode.STORE_COMPRESSED.resourceKey, element.getPropertyAsString(mode))
+        assertEquals("", element.getPropertyAsString(md5))
+    }
+
+    @Test
+    fun elementWithoutMd5IsUntouched() {
+        val element = HTTPSamplerProxy()
+        assertFalse(upgrader.upgrade(element))
+        assertEquals("", element.getPropertyAsString(mode))
+    }
+
+    @Test
+    fun existingModeIsKeptAndLegacyMd5Removed() {
+        val element = HTTPSamplerProxy()
+        element.setProperty(mode, ResponseProcessingMode.FETCH_AND_DISCARD.resourceKey)
+        element.setProperty(BooleanProperty(md5, true))
+
+        assertTrue(upgrader.upgrade(element))
+        assertEquals(
+            ResponseProcessingMode.FETCH_AND_DISCARD.resourceKey,
+            element.getPropertyAsString(mode),
+            "an explicit mode must win over the legacy md5"
+        )
+        assertEquals("", element.getPropertyAsString(md5))
+    }
+}