Merge pull request #3606 from KIT-IBPT/issue-3603

georgweiss · web-flow · commit 48b8c9c4e396 · 2025-11-03T12:27:46.000+01:00
Handle long values in EPICS Jackie PV support
diff --git a/core/pv-jackie/pom.xml b/core/pv-jackie/pom.xml
@@ -22,6 +22,13 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <version>${mockito.version}</version>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.epics</groupId>
       <artifactId>vtype</artifactId>
diff --git a/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/JackiePV.java b/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/JackiePV.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2017-2024 aquenos GmbH.
+ * Copyright (c) 2017-2025 aquenos GmbH.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -261,10 +261,12 @@ public CompletableFuture<?> asyncWrite(Object new_value) throws Exception {
                 // Use ca_put_callback.
                 final var listenable_future = channel.put(
                         ValueConverter.objectToChannelAccessSimpleOnlyValue(
+                                channel.getName(),
                                 new_value,
                                 channel.getClient().getConfiguration()
                                         .getCharset(),
-                                treat_char_as_long_string));
+                                treat_char_as_long_string,
+                                preferences.long_conversion_mode()));
                 final var completable_future = new CompletableFuture<Void>();
                 listenable_future.addCompletionListener((future) -> {
                     try {
@@ -304,10 +306,12 @@ public void write(Object new_value) throws Exception {
                 // Use ca_put without a callback.
                 channel.putNoCallback(
                         ValueConverter.objectToChannelAccessSimpleOnlyValue(
+                                channel.getName(),
                                 new_value,
                                 channel.getClient().getConfiguration()
                                         .getCharset(),
-                                treat_char_as_long_string));
+                                treat_char_as_long_string,
+                                preferences.long_conversion_mode()));
             }
             case YES -> {
                 // Wait for the write operation to complete. This allows code
diff --git a/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/JackiePreferences.java b/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/JackiePreferences.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2024 aquenos GmbH.
+ * Copyright (c) 2024-2025 aquenos GmbH.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -133,10 +133,73 @@ public record JackiePreferences(
         boolean dbe_property_supported,
         boolean honor_zero_precision,
         String hostname,
+        LongConversionMode long_conversion_mode,
         ChannelAccessEventMask monitor_mask,
         boolean rtyp_value_only,
         String username) {
 
+    /**
+     * Mode for handling integer numbers that are too large to fit into the
+     * {@link Integer} type.
+     */
+    public enum LongConversionMode {
+        /**
+         * Limit the {@link Long} value to the {@link Integer} range.
+         *
+         * A value that is greater than {@link Integer#MAX_VALUE} is converted
+         * to {@link Integer#MAX_VALUE}, and a value that is less than
+         * {@link Integer#MIN_VALUE} is converted to {@link Integer#MIN_VALUE}.
+         */
+        COERCE,
+
+        /**
+         * Limit the {@link Long} value to the {@link Integer} range and log a
+         * warning.
+         *
+         * This essentially is the same behavior as {@link #COERCE}, but a
+         * warning message is written to the log.
+         */
+        COERCE_AND_WARN,
+
+        /**
+         * Convert the {@link Long} value to a {@link Double}.
+         *
+         * This means that some precision is lost.
+         */
+        CONVERT,
+
+        /**
+         * Convert the {@link Long} value to a {@link Double} and log a
+         * warning.
+         *
+         * This essentially is the same behavior as {@link #CONVERT}, but a
+         * warning message is written to the log.
+         */
+        CONVERT_AND_WARN,
+
+        /**
+         * Raise an {@link IllegalArgumentException}.
+         */
+        FAIL,
+
+        /**
+         * Cast the {@link Long} value to an {@link Integer}.
+         *
+         * This means that the value will overflow (e.g.
+         * <code>Integer.MAX_VALUE + 1</code> becomes
+         * <code>Integer.MIN_VALUE</code>.
+         */
+        TRUNCATE,
+
+        /**
+         * Cast the {@link Long} value to an {@link Integer} and log a warning.
+         *
+         * This essentially is the same behavior as {@link #CAST}, but a
+         * warning message is written to the log.
+         */
+        TRUNCATE_AND_WARN,
+    }
+
     private final static JackiePreferences DEFAULT_INSTANCE;
 
     static {
@@ -216,6 +279,18 @@ private static JackiePreferences loadPreferences() {
         if (hostname.isEmpty()) {
             hostname = null;
         }
+        final var long_conversion_mode_string = preference_reader.get(
+                "long_conversion_mode");
+        LongConversionMode long_conversion_mode;
+        try {
+            long_conversion_mode = LongConversionMode.valueOf(
+                    long_conversion_mode_string);
+        } catch (IllegalArgumentException|NullPointerException e) {
+            logger.severe(
+                    "Invalid long conversion mode: "
+                            + long_conversion_mode_string);
+            long_conversion_mode = LongConversionMode.COERCE_AND_WARN;
+        }
         final var monitor_mask_string = preference_reader.get("monitor_mask");
         ChannelAccessEventMask monitor_mask;
         try {
@@ -493,6 +568,7 @@ private static JackiePreferences loadPreferences() {
         logger.config("dbe_property_supported = " + dbe_property_supported);
         logger.config("honor_zero_precision = " + honor_zero_precision);
         logger.config("hostname = " + hostname);
+        logger.config("long_conversion_mode = " + long_conversion_mode);
         logger.config("monitor_mask = " + monitor_mask);
         logger.config("rtyp_value_only = " + rtyp_value_only);
         logger.config("use_env = " + use_env);
@@ -513,6 +589,7 @@ private static JackiePreferences loadPreferences() {
                 dbe_property_supported,
                 honor_zero_precision,
                 hostname,
+                long_conversion_mode,
                 monitor_mask,
                 rtyp_value_only,
                 username);
diff --git a/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/util/ValueConverter.java b/core/pv-jackie/src/main/java/org/phoebus/pv/jackie/util/ValueConverter.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2024 aquenos GmbH.
+ * Copyright (c) 2024-2025 aquenos GmbH.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -52,6 +52,9 @@
 import org.epics.vtype.VStringArray;
 import org.epics.vtype.VType;
 import org.phoebus.core.vtypes.VTypeHelper;
+import org.phoebus.pv.jackie.JackiePreferences;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.nio.ByteBuffer;
 import java.nio.DoubleBuffer;
@@ -75,6 +78,14 @@ public final class ValueConverter {
      */
     public static final long OFFSET_EPICS_TO_UNIX_EPOCH_SECONDS = 631152000L;
 
+    /**
+     * Logger used by this class.
+     *
+     * The field is package private, so that unit-tests can inject a custom
+     * implementation.
+     */
+    static Logger log = LoggerFactory.getLogger(ValueConverter.class);
+
     private ValueConverter() {
     }
 
@@ -316,6 +327,9 @@ public static VType channelAccessToVType(
      * <code>int</code>, and <code>short</code>, arrays of these primitive
      * types, {@link String}, and arrays of {@link String}.
      *
+     * @param pv_name
+     *  name of the process variable for which the value is converted. This is
+     *  only used for logging purposes.
      * @param object
      *  object to be converted.
      * @param charset
@@ -324,15 +338,20 @@ public static VType channelAccessToVType(
      *  indicates whether a {@link String} or single element
      *  <code>String[]</code> array should be converted to a
      *  <code>DBR_CHAR</code> instead of a <code>DBR_STRING</code>.
+     * @param long_conversion_mode
+     *  behavior when converting a {@link Long} value that does not fit into an
+     *  {@link Integer}.
      * @return
      *  the converted value.
      * @throws IllegalArgumentException
      *  if <code>object</code> cannot be converted.
      */
     public static ChannelAccessSimpleOnlyValue<?> objectToChannelAccessSimpleOnlyValue(
+            String pv_name,
             Object object,
             Charset charset,
-            boolean convert_string_as_long_string) {
+            boolean convert_string_as_long_string,
+            JackiePreferences.LongConversionMode long_conversion_mode) {
         if (object instanceof VType vtype) {
             var converted_object = VTypeHelper.toObject(vtype);
             // VTypeHelper.toObject returns null if it does not know how to
@@ -367,6 +386,110 @@ public static ChannelAccessSimpleOnlyValue<?> objectToChannelAccessSimpleOnlyVal
         if (object instanceof int[] value) {
             return ChannelAccessValueFactory.createLong(value);
         }
+        if (object instanceof Long value) {
+            if (value >= Integer.MIN_VALUE && value <= Integer.MAX_VALUE) {
+                return ChannelAccessValueFactory.createLong(
+                        new int[]{value.intValue()});
+            }
+            return switch (long_conversion_mode) {
+                case COERCE -> ChannelAccessValueFactory.createLong(
+                        new int[]{coerceToInt(value)});
+                case COERCE_AND_WARN -> {
+                    final var coerced_value = coerceToInt(value);
+                    log.warn(
+                            "Writing long {} as int {} for PV {}",
+                            value,
+                            coerced_value,
+                            pv_name);
+                    yield ChannelAccessValueFactory.createLong(
+                            new int[]{coerced_value});
+                }
+                case CONVERT -> ChannelAccessValueFactory.createDouble(
+                        new double[]{value.doubleValue()});
+                case CONVERT_AND_WARN -> {
+                    final var converted_value = value.doubleValue();
+                    log.warn(
+                            "Writing long {} as double {} for PV {}",
+                            value,
+                            converted_value,
+                            pv_name);
+                    yield ChannelAccessValueFactory.createDouble(
+                            new double[]{converted_value});
+                }
+                case FAIL -> throw new IllegalArgumentException(
+                        "Cannot write long value " + value
+                                + ". The value is outside the range of a "
+                                + "32-bit signed integer.");
+                case TRUNCATE -> ChannelAccessValueFactory.createLong(
+                        new int[]{value.intValue()});
+                case TRUNCATE_AND_WARN -> {
+                    final var truncated_value = value.intValue();
+                    log.warn(
+                            "Writing long {} as int {} for PV {}",
+                            value,
+                            truncated_value,
+                            pv_name);
+                    yield ChannelAccessValueFactory.createLong(
+                            new int[]{truncated_value});
+                }
+            };
+        }
+        if (object instanceof long[] value) {
+            boolean limit_exceeded = false;
+            for (long element : value) {
+                if (element < Integer.MIN_VALUE
+                        || element > Integer.MAX_VALUE) {
+                    limit_exceeded = true;
+                    break;
+                }
+            }
+            if (!limit_exceeded) {
+                return ChannelAccessValueFactory.createLong(
+                        longArrayToIntArray(value));
+            }
+            return switch (long_conversion_mode) {
+                case COERCE -> ChannelAccessValueFactory.createLong(
+                        coerceToInt(value));
+                case COERCE_AND_WARN -> {
+                    final var coerced_value = coerceToInt(value);
+                    log.warn(
+                            "Writing long[] {} as int[] {} for PV {}",
+                            Arrays.toString(value),
+                            Arrays.toString(coerced_value),
+                            pv_name);
+                    yield ChannelAccessValueFactory.createLong(
+                            coerced_value);
+                }
+                case CONVERT -> ChannelAccessValueFactory.createDouble(
+                        longArrayToDoubleArray(value));
+                case CONVERT_AND_WARN -> {
+                    final var converted_value = longArrayToDoubleArray(value);
+                    log.warn(
+                            "Writing long[] {} as double[] {} for PV {}",
+                            Arrays.toString(value),
+                            Arrays.toString(converted_value),
+                            pv_name);
+                    yield ChannelAccessValueFactory.createDouble(
+                            converted_value);
+                }
+                case FAIL -> throw new IllegalArgumentException(
+                        "Cannot write long[] value " + Arrays.toString(value)
+                                + ". The value is outside the range of a "
+                                + "32-bit signed integer.");
+                case TRUNCATE -> ChannelAccessValueFactory.createLong(
+                        longArrayToIntArray(value));
+                case TRUNCATE_AND_WARN -> {
+                    final var truncated_value = longArrayToIntArray(value);
+                    log.warn(
+                            "Writing long[] {} as int[] {} for PV {}",
+                            Arrays.toString(value),
+                            Arrays.toString(truncated_value),
+                            pv_name);
+                    yield ChannelAccessValueFactory.createLong(
+                            truncated_value);
+                }
+            };
+        }
         if (object instanceof Short value) {
             return ChannelAccessValueFactory.createShort(new short[] {value});
         }
@@ -389,7 +512,7 @@ public static ChannelAccessSimpleOnlyValue<?> objectToChannelAccessSimpleOnlyVal
             // conversion if the array has a single element.
             if (value.length == 1 && convert_string_as_long_string) {
                 return objectToChannelAccessSimpleOnlyValue(
-                        value[0], charset, true);
+                        pv_name, value[0], charset, true, long_conversion_mode);
             }
             return ChannelAccessValueFactory.createString(
                     Arrays.asList(value), charset);
@@ -415,6 +538,21 @@ public int size() {
         };
     }
 
+    private static int coerceToInt(long value) {
+        if (value > Integer.MAX_VALUE) {
+            return Integer.MAX_VALUE;
+        } else if (value < Integer.MIN_VALUE) {
+            return Integer.MIN_VALUE;
+        } else {
+            return (int) value;
+        }
+    }
+
+    private static int[] coerceToInt(long[] array) {
+        return Arrays.stream(array).mapToInt(
+                ValueConverter::coerceToInt).toArray();
+    }
+
     private static Alarm convertAlarm(ChannelAccessTimeValue<?> time_value) {
         AlarmSeverity severity = switch (time_value.getAlarmSeverity()) {
             case NO_ALARM -> AlarmSeverity.NONE;
@@ -539,6 +677,16 @@ public int size() {
         };
     }
 
+    private static double[] longArrayToDoubleArray(long[] array) {
+        return Arrays.stream(array).mapToDouble(
+                element -> (double) element).toArray();
+    }
+
+    private static int[] longArrayToIntArray(long[] array) {
+        return Arrays.stream(array).mapToInt(
+                element -> (int) element).toArray();
+    }
+
     private static ListShort shortBufferToListShort(ShortBuffer buffer) {
         return new ListShort() {
             @Override
diff --git a/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties b/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties
diff --git a/core/pv-jackie/src/test/java/org/phoebus/pv/jackie/util/ValueConverterTest.java b/core/pv-jackie/src/test/java/org/phoebus/pv/jackie/util/ValueConverterTest.java
