[fronius] Thing actions: Return boolean & Annotate all inputs as required (#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 <dev@florianhotze.com>
Signed-off-by: Ciprian Pascu <contact@ciprianpascu.ro>

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

bundles/org.openhab.binding.fronius/src/main/java/org/openhab/binding/fronius/internal/action/FroniusSymoInverterActions.java

@@ -21,6 +21,7 @@ import org.eclipse.jdt.annotation.NonNullByDefault;
 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 @@ import org.osgi.service.component.annotations.ServiceScope;
 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) {
+    public static boolean addHoldBatteryChargeSchedule(ThingActions actions, ZonedDateTime from, ZonedDateTime until) {
-        addHoldBatteryChargeSchedule(actions, from.toLocalTime(), until.toLocalTime());
+        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,
+    public static boolean addForcedBatteryChargingSchedule(ThingActions actions, ZonedDateTime from,
-            QuantityType<Power> power) {
+            ZonedDateTime until, QuantityType<Power> power) {
-        addForcedBatteryChargingSchedule(actions, from.toLocalTime(), until.toLocalTime(), power);
+        return addForcedBatteryChargingSchedule(actions, from.toLocalTime(), until.toLocalTime(), power);
     }
 
     @Override
@@ -107,56 +108,62 @@ public class FroniusSymoInverterActions implements ThingActions {
     }
 
     @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(
+    public @ActionOutput(type = "boolean", label = "Success") boolean addHoldBatteryChargeSchedule(
-            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description") LocalTime from,
+            @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") LocalTime until) {
+            @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) {
+    public boolean addHoldBatteryChargeSchedule(ZonedDateTime from, ZonedDateTime until) {
-        addHoldBatteryChargeSchedule(from.toLocalTime(), until.toLocalTime());
+        return addHoldBatteryChargeSchedule(from.toLocalTime(), until.toLocalTime());
     }
 
     @RuleAction(label = "@text/actions.force-battery-charging.label", description = "@text/actions.force-battery-charging.description")
-    public void forceBatteryCharging(
+    public @ActionOutput(type = "boolean", label = "Success") boolean forceBatteryCharging(
-            @ActionInput(name = "power", label = "@text/actions.power.label", description = "@text/actions.power.label", type = "QuantityType<Power>") QuantityType<Power> power) {
+            @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(
+    public @ActionOutput(type = "boolean", label = "Success") boolean addForcedBatteryChargingSchedule(
-            @ActionInput(name = "from", label = "@text/actions.from.label", description = "@text/actions.from.description") LocalTime from,
+            @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") LocalTime until,
+            @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>") QuantityType<Power> power) {
+            @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) {
+    public boolean addForcedBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until,
-        addForcedBatteryChargingSchedule(from.toLocalTime(), until.toLocalTime(), power);
+            QuantityType<Power> power) {
+        return addForcedBatteryChargingSchedule(from.toLocalTime(), until.toLocalTime(), power);
     }
 }

bundles/org.openhab.binding.fronius/src/main/java/org/openhab/binding/fronius/internal/handler/FroniusSymoInverterHandler.java

@@ -107,59 +107,69 @@ public class FroniusSymoInverterHandler extends FroniusBaseThingHandler {
         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;
     }
 
     /**