[fronius] Thing actions: Return boolean & Annotate all inputs as requ…

…ired (#17623) * [fronius] Symo Inverter actions: Return boolean to indicate success/failure * [fronius] Symo Inverter actions: Annotate all inputs as required * [fronius] Add `@ActionOutput` annotation As discussed in #17504. Signed-off-by: Florian Hotze <[email protected]>
openhab · Oct 29, 2024 · 7f256a7 · 7f256a7
1 parent 44fb3ad
commit 7f256a7
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 40 deletions.
diff --git a/bundles/org.openhab.binding.fronius/README.md b/bundles/org.openhab.binding.fronius/README.md
@@ -186,6 +186,8 @@ Once the actions instance has been retrieved, you can invoke the following metho
 - `addForcedBatteryChargingSchedule(LocalTime from, LocalTime until, QuantityType<Power> power)`: Add a schedule to force the battery to charge with the specified power in the specified time range.
 - `addForcedBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until, QuantityType<Power> power)`: Add a schedule to force the battery to charge with the specified power in the specified time range.
 
+All methods return a boolean value indicating whether the action was successful.
+
 ### Examples
 
 ```javascript

diff --git a/...src/main/java/org/openhab/binding/fronius/internal/action/FroniusSymoInverterActions.java b/...src/main/java/org/openhab/binding/fronius/internal/action/FroniusSymoInverterActions.java
@@ -21,6 +21,7 @@
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.binding.fronius.internal.handler.FroniusSymoInverterHandler;
 import org.openhab.core.automation.annotation.ActionInput;
+import org.openhab.core.automation.annotation.ActionOutput;
 import org.openhab.core.automation.annotation.RuleAction;
 import org.openhab.core.library.types.QuantityType;
 import org.openhab.core.thing.binding.ThingActions;
@@ -41,59 +42,59 @@
 public class FroniusSymoInverterActions implements ThingActions {
     private @Nullable FroniusSymoInverterHandler handler;
 
-    public static void resetBatteryControl(ThingActions actions) {
+    public static boolean resetBatteryControl(ThingActions actions) {
         if (actions instanceof FroniusSymoInverterActions froniusSymoInverterActions) {
-            froniusSymoInverterActions.resetBatteryControl();
+            return froniusSymoInverterActions.resetBatteryControl();
         } else {
             throw new IllegalArgumentException(
                     "The 'actions' argument is not an instance of FroniusSymoInverterActions");
         }
     }
 
-    public static void holdBatteryCharge(ThingActions actions) {
+    public static boolean holdBatteryCharge(ThingActions actions) {
         if (actions instanceof FroniusSymoInverterActions froniusSymoInverterActions) {
-            froniusSymoInverterActions.holdBatteryCharge();
+            return froniusSymoInverterActions.holdBatteryCharge();
         } else {
             throw new IllegalArgumentException(
                     "The 'actions' argument is not an instance of FroniusSymoInverterActions");
         }
     }
 
-    public static void addHoldBatteryChargeSchedule(ThingActions actions, LocalTime from, LocalTime until) {
+    public static boolean addHoldBatteryChargeSchedule(ThingActions actions, LocalTime from, LocalTime until) {
         if (actions instanceof FroniusSymoInverterActions froniusSymoInverterActions) {
-            froniusSymoInverterActions.addHoldBatteryChargeSchedule(from, until);
+            return froniusSymoInverterActions.addHoldBatteryChargeSchedule(from, until);
         } else {
             throw new IllegalArgumentException(
                     "The 'actions' argument is not an instance of FroniusSymoInverterActions");
         }
     }
 
-    public static void addHoldBatteryChargeSchedule(ThingActions actions, ZonedDateTime from, ZonedDateTime until) {
-        addHoldBatteryChargeSchedule(actions, from.toLocalTime(), until.toLocalTime());
+    public static boolean addHoldBatteryChargeSchedule(ThingActions actions, ZonedDateTime from, ZonedDateTime until) {
+        return addHoldBatteryChargeSchedule(actions, from.toLocalTime(), until.toLocalTime());
     }
 
-    public static void forceBatteryCharging(ThingActions actions, QuantityType<Power> power) {
+    public static boolean forceBatteryCharging(ThingActions actions, QuantityType<Power> power) {
         if (actions instanceof FroniusSymoInverterActions froniusSymoInverterActions) {
-            froniusSymoInverterActions.forceBatteryCharging(power);
+            return froniusSymoInverterActions.forceBatteryCharging(power);
         } else {
             throw new IllegalArgumentException(
                     "The 'actions' argument is not an instance of FroniusSymoInverterActions");
         }
     }
 
-    public static void addForcedBatteryChargingSchedule(ThingActions actions, LocalTime from, LocalTime until,
+    public static boolean addForcedBatteryChargingSchedule(ThingActions actions, LocalTime from, LocalTime until,
             QuantityType<Power> power) {
         if (actions instanceof FroniusSymoInverterActions froniusSymoInverterActions) {
-            froniusSymoInverterActions.addForcedBatteryChargingSchedule(from, until, power);
+            return froniusSymoInverterActions.addForcedBatteryChargingSchedule(from, until, power);
         } else {
             throw new IllegalArgumentException(
                     "The 'actions' argument is not an instance of FroniusSymoInverterActions");
         }
     }
 
-    public static void addForcedBatteryChargingSchedule(ThingActions actions, ZonedDateTime from, ZonedDateTime until,
-            QuantityType<Power> power) {
-        addForcedBatteryChargingSchedule(actions, from.toLocalTime(), until.toLocalTime(), power);
+    public static boolean addForcedBatteryChargingSchedule(ThingActions actions, ZonedDateTime from,
+            ZonedDateTime until, QuantityType<Power> power) {
+        return addForcedBatteryChargingSchedule(actions, from.toLocalTime(), until.toLocalTime(), power);
     }
 
     @Override
@@ -107,56 +108,62 @@ public void setThingHandler(@Nullable ThingHandler handler) {
     }
 
     @RuleAction(label = "@text/actions.reset-battery-control.label", description = "@text/actions.reset-battery-control.description")
-    public void resetBatteryControl() {
+    public @ActionOutput(type = "boolean", label = "Success") boolean resetBatteryControl() {
         FroniusSymoInverterHandler handler = this.handler;
         if (handler != null) {
-            handler.resetBatteryControl();
+            return handler.resetBatteryControl();
         }
+        return false;
     }
 
     @RuleAction(label = "@text/actions.hold-battery-charge.label", description = "@text/actions.hold-battery-charge.description")
-    public void holdBatteryCharge() {
+    public @ActionOutput(type = "boolean", label = "Success") boolean holdBatteryCharge() {
         FroniusSymoInverterHandler handler = this.handler;
         if (handler != null) {
-            handler.holdBatteryCharge();
+            return handler.holdBatteryCharge();
         }
+        return false;
     }
 
     @RuleAction(label = "@text/actions.add-hold-battery-charge-schedule.label", description = "@text/actions.add-hold-battery-charge-schedule.description")
-    public void addHoldBatteryChargeSchedule(
-            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description") LocalTime from,
-            @ActionInput(name = "until", label = "@text/actions.until.label", description = "@text/actions.until.description") LocalTime until) {
+    public @ActionOutput(type = "boolean", label = "Success") boolean addHoldBatteryChargeSchedule(
+            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description", required = true) LocalTime from,
+            @ActionInput(name = "until", label = "@text/actions.until.label", description = "@text/actions.until.description", required = true) LocalTime until) {
         FroniusSymoInverterHandler handler = this.handler;
         if (handler != null) {
-            handler.addHoldBatteryChargeSchedule(from, until);
+            return handler.addHoldBatteryChargeSchedule(from, until);
         }
+        return false;
     }
 
-    public void addHoldBatteryChargeSchedule(ZonedDateTime from, ZonedDateTime until) {
-        addHoldBatteryChargeSchedule(from.toLocalTime(), until.toLocalTime());
+    public boolean addHoldBatteryChargeSchedule(ZonedDateTime from, ZonedDateTime until) {
+        return addHoldBatteryChargeSchedule(from.toLocalTime(), until.toLocalTime());
     }
 
     @RuleAction(label = "@text/actions.force-battery-charging.label", description = "@text/actions.force-battery-charging.description")
-    public void forceBatteryCharging(
-            @ActionInput(name = "power", label = "@text/actions.power.label", description = "@text/actions.power.label", type = "QuantityType<Power>") QuantityType<Power> power) {
+    public @ActionOutput(type = "boolean", label = "Success") boolean forceBatteryCharging(
+            @ActionInput(name = "power", label = "@text/actions.power.label", description = "@text/actions.power.label", type = "QuantityType<Power>", required = true) QuantityType<Power> power) {
         FroniusSymoInverterHandler handler = this.handler;
         if (handler != null) {
-            handler.forceBatteryCharging(power);
+            return handler.forceBatteryCharging(power);
         }
+        return false;
     }
 
     @RuleAction(label = "@text/actions.add-forced-battery-charging-schedule.label", description = "@text/actions.add-forced-battery-charging-schedule.description")
-    public void addForcedBatteryChargingSchedule(
-            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description") LocalTime from,
-            @ActionInput(name = "until", label = "@text/actions.until.label", description = "@text/actions.until.description") LocalTime until,
-            @ActionInput(name = "power", label = "@text/actions.power.label", description = "@text/actions.power.label", type = "QuantityType<Power>") QuantityType<Power> power) {
+    public @ActionOutput(type = "boolean", label = "Success") boolean addForcedBatteryChargingSchedule(
+            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description", required = true) LocalTime from,
+            @ActionInput(name = "until", label = "@text/actions.until.label", description = "@text/actions.until.description", required = true) LocalTime until,
+            @ActionInput(name = "power", label = "@text/actions.power.label", description = "@text/actions.power.label", type = "QuantityType<Power>", required = true) QuantityType<Power> power) {
         FroniusSymoInverterHandler handler = this.handler;
         if (handler != null) {
-            handler.addForcedBatteryChargingSchedule(from, until, power);
+            return handler.addForcedBatteryChargingSchedule(from, until, power);
         }
+        return false;
     }
 
-    public void addForcedBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until, QuantityType<Power> power) {
-        addForcedBatteryChargingSchedule(from.toLocalTime(), until.toLocalTime(), power);
+    public boolean addForcedBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until,
+            QuantityType<Power> power) {
+        return addForcedBatteryChargingSchedule(from.toLocalTime(), until.toLocalTime(), power);
     }
 }
diff --git a/...rc/main/java/org/openhab/binding/fronius/internal/handler/FroniusSymoInverterHandler.java b/...rc/main/java/org/openhab/binding/fronius/internal/handler/FroniusSymoInverterHandler.java
@@ -107,59 +107,69 @@ public Collection<Class<? extends ThingHandlerService>> getServices() {
         return batteryControl;
     }
 
-    public void resetBatteryControl() {
+    public boolean resetBatteryControl() {
         FroniusBatteryControl batteryControl = getBatteryControl();
         if (batteryControl != null) {
             try {
                 batteryControl.reset();
+                return true;
             } catch (FroniusCommunicationException e) {
                 logger.warn("Failed to reset battery control", e);
             }
         }
+        return false;
     }
 
-    public void holdBatteryCharge() {
+    public boolean holdBatteryCharge() {
         FroniusBatteryControl batteryControl = getBatteryControl();
         if (batteryControl != null) {
             try {
                 batteryControl.holdBatteryCharge();
+                return true;
             } catch (FroniusCommunicationException e) {
                 logger.warn("Failed to set battery control to hold battery charge", e);
             }
         }
+        return false;
     }
 
-    public void addHoldBatteryChargeSchedule(LocalTime from, LocalTime until) {
+    public boolean addHoldBatteryChargeSchedule(LocalTime from, LocalTime until) {
         FroniusBatteryControl batteryControl = getBatteryControl();
         if (batteryControl != null) {
             try {
                 batteryControl.addHoldBatteryChargeSchedule(from, until);
+                return true;
             } catch (FroniusCommunicationException e) {
                 logger.warn("Failed to add hold battery charge schedule to battery control", e);
             }
         }
+        return false;
     }
 
-    public void forceBatteryCharging(QuantityType<Power> power) {
+    public boolean forceBatteryCharging(QuantityType<Power> power) {
         FroniusBatteryControl batteryControl = getBatteryControl();
         if (batteryControl != null) {
             try {
                 batteryControl.forceBatteryCharging(power);
+                return true;
             } catch (FroniusCommunicationException e) {
                 logger.warn("Failed to set battery control to force battery charge", e);
             }
         }
+        return false;
     }
 
-    public void addForcedBatteryChargingSchedule(LocalTime from, LocalTime until, QuantityType<Power> power) {
+    public boolean addForcedBatteryChargingSchedule(LocalTime from, LocalTime until, QuantityType<Power> power) {
         FroniusBatteryControl batteryControl = getBatteryControl();
         if (batteryControl != null) {
             try {
                 batteryControl.addForcedBatteryChargingSchedule(from, until, power);
+                return true;
             } catch (FroniusCommunicationException e) {
                 logger.warn("Failed to add forced battery charge schedule to battery control", e);
             }
         }
+        return false;
     }
 
     /**