feat: add ResourceKeyed, LocalizedValue interfaces for combobox localization

Author: vlsi

build-logic/verification/src/main/kotlin/build-logic.autostyle.gradle.kts

@@ -101,7 +101,12 @@ plugins.withId("org.jetbrains.kotlin.jvm") {
         kotlin {
             license()
             trimTrailingWhitespace()
-            ktlint("0.40.0")
+            ktlint("0.40.0") {
+                filter {
+                    // TODO: remove exclusion when update ktlint
+                    exclude("**/org/apache/jorphan/locale/PlainValue.kt")
+                }
+            }
             endWithNewline()
         }
     }

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/ComboBoxValue.kt

@@ -0,0 +1,40 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+
+/**
+ * Marker interface for values that can be used in a combo box.
+ *
+ * This interface is intended to standardize handling of values for GUI components
+ * like combo boxes. Classes implementing this interface can define how their
+ * values are represented and localized, providing flexibility for different types
+ * of combo box content.
+ *
+ * Implementers may include:
+ * - Simple values (e.g., strings or plain objects).
+ * - Values with additional localization support for display in different locales.
+ * - Wrapper types that encapsulate richer behaviors for combo box items.
+ *
+ * This interface is marked as experimental and may change in future releases.
+ *
+ * @since 6.0.0
+ */
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public interface ComboBoxValue

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/LocalizedString.kt

@@ -0,0 +1,36 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+import org.jetbrains.annotations.NonNls
+
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public class LocalizedString(
+    override val resourceKey: @NonNls String,
+    private val resourceLocalizer: ResourceLocalizer,
+) : ResourceKeyed, ComboBoxValue {
+    override fun toString(): String =
+        resourceLocalizer.localize(resourceKey)
+
+    override fun equals(other: Any?): Boolean =
+        other is LocalizedString && other.resourceKey == resourceKey
+
+    override fun hashCode(): Int =
+        resourceKey.hashCode()
+}

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/LocalizedValue.kt

@@ -0,0 +1,51 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+
+/**
+ * Represents a localized value that combines an object implementing the [ResourceKeyed] interface
+ * with a localization function. This allows the object's resource key to be localized dynamically
+ * into a string representation.
+ *
+ * @param T The type of the value, which must implement the [ResourceKeyed] interface.
+ * @property value The object implementing [ResourceKeyed], which holds a resource key for localization.
+ * @property localizer A function that takes a resource key string and returns its localized string representation.
+ *
+ * The localized representation of this object is produced by applying the `localizer` function
+ * to the resource key of the `value`.
+ *
+ * The class provides equality and hash code implementations based on the underlying `value`.
+ *
+ * @since 6.0.0
+ */
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public class LocalizedValue<T : ResourceKeyed>(
+    public val value: T,
+    private val localizer: ResourceLocalizer,
+) : ResourceKeyed by value, ComboBoxValue {
+    override fun toString(): String =
+        localizer.localize(value.resourceKey)
+
+    override fun equals(other: Any?): Boolean =
+        other is LocalizedValue<*> && other.value == value
+
+    override fun hashCode(): Int =
+        value.hashCode()
+}

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/PlainValue.kt

@@ -0,0 +1,26 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+
+@JvmInline
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public value class PlainValue(public val value: String): ComboBoxValue {
+    override fun toString(): String = value
+}

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/ResourceKeyed.kt

@@ -0,0 +1,63 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+import org.jetbrains.annotations.NonNls
+
+/**
+ * Interface for enum types that provide their own localization resource key for GUI display.
+ *
+ * When an enum implements this interface, the [resourceKey] will be used for:
+ * - Storing the value in JMeter properties (instead of the enum name)
+ * - Looking up localized display text via `JMeterUtils.getResString(resourceKey)`
+ * - Binding to GUI components
+ *
+ * This allows enums to have stable, localization-friendly identifiers that are independent
+ * of the enum constant names.
+ *
+ * Example:
+ * ```java
+ * public enum ResponseMode implements ResourceKeyed {
+ *     STORE_COMPRESSED("response_mode_store"),
+ *     FETCH_DISCARD("response_mode_discard");
+ *
+ *     private final String key;
+ *     ResponseMode(String key) { this.key = key; }
+ *
+ *     @Override
+ *     public String getResourceKey() { return key; }
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public interface ResourceKeyed {
+    /**
+     * Returns the resource key used for localization and property storage.
+     *
+     * This key should:
+     * - Be stable across JMeter versions (don't change it)
+     * - Have a corresponding entry in messages.properties
+     * - Use lowercase with underscores by convention
+     *
+     * @return the resource key for this enum value
+     */
+    public val resourceKey: @NonNls String
+}

src/jorphan/src/main/kotlin/org/apache/jorphan/locale/ResourceLocalizer.kt

@@ -0,0 +1,40 @@
+/*
+ * 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.jorphan.locale
+
+import org.apiguardian.api.API
+import org.jetbrains.annotations.Nls
+import org.jetbrains.annotations.NonNls
+
+/**
+ * Functional interface for localizing resource strings.
+ *
+ * This interface provides a single method, [localize], which takes a non-localized input string
+ * and returns its localized representation. Implementations of this interface define how the
+ * localization is performed, such as looking up translations in a resource bundle or applying
+ * other localization mechanisms.
+ *
+ * The input string is expected to be a resource identifier or key, and the output is a string
+ * appropriate for display in a user interface or other localized context.
+ *
+ * @since 6.0.0
+ */
+@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public fun interface ResourceLocalizer {
+    public fun localize(input: @NonNls String): @Nls String
+}

src/jorphan/src/main/kotlin/org/apache/jorphan/util/EnumUtils.kt

@@ -18,6 +18,7 @@
 @file:JvmName("EnumUtils")
 package org.apache.jorphan.util
 
+import org.apache.jorphan.locale.ResourceKeyed
 import org.apiguardian.api.API
 import java.util.Collections.unmodifiableList
 import java.util.Collections.unmodifiableMap
@@ -39,34 +40,30 @@ private val VALUE_MAP = object : ClassValue<Map<String, Enum<*>>>() {
         require(type.isEnum) {
             "Class $type is not an enum"
         }
-        @Suppress("UNCHECKED_CAST")
-        type as Class<Enum<*>>
         return unmodifiableMap(
-            VALUES.get(type).associateBy { it.stringValue }
+            VALUES.get(type).associateBy {
+                (it as ResourceKeyed).resourceKey
+            }
         )
     }
 }
 
 @Suppress("UNCHECKED_CAST")
-@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
-public fun <T : Enum<*>> values(klass: Class<out T>): List<T> =
-    VALUES.get(klass) as List<T>
+@get:API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public val <T : Enum<*>> Class<out T>.enumValues: List<T>
+    get() = VALUES.get(this) as List<T>
 
 @Suppress("UNCHECKED_CAST")
-@API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
-public fun <T : Enum<*>> valueMap(klass: Class<out T>): List<T> =
-    VALUES.get(klass) as List<T>
+@get:API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
+public val <T> Class<out T>.enumValueMap: Map<String, T> where T : Enum<*>, T : ResourceKeyed
+    get() = VALUE_MAP.get(this) as Map<String, T>
 
 @Suppress("UNCHECKED_CAST")
 @API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
-public inline fun <reified T : Enum<*>> valueOf(value: String): T? =
-    valueOf(T::class.java, value)
+public inline fun <reified T> valueOf(value: String): T? where T : Enum<*>, T : ResourceKeyed =
+    T::class.java.valueOf(value)
 
 @Suppress("UNCHECKED_CAST")
 @API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
-public fun <T : Enum<*>> valueOf(klass: Class<T>, value: String): T? =
-    VALUE_MAP.get(klass)[value] as T?
-
-@get:API(status = API.Status.EXPERIMENTAL, since = "6.0.0")
-public val Enum<*>.stringValue: String
-    get() = toString()
+public fun <T> Class<T>.valueOf(value: String): T? where T : Enum<*>, T : ResourceKeyed =
+    enumValueMap[value]