[tr064] add rule action for phonebook (#9505)

* add rule action for phonebook
* address review comments

Signed-off-by: Jan N. Klug <jan.n.klug@rub.de>

bundles/org.openhab.binding.tr064/README.md

@@ -131,4 +131,23 @@ If only a specific phonebook from the device should be used, this can be specifi
 The default is to use all available phonebooks from the specified thing.
 In case the format of the number in the phonebook and the format of the number from the channel are different (e.g. regarding country prefixes), the `matchCount` parameter can be used.
 The configured `matchCount` is counted from the right end and denotes the number of matching characters needed to consider this number as matching.
+A `matchCount` of `0` is considered as "match everything".
 
+## Rule Action
+
+The phonebooks of a `fritzbox` thing can be used to lookup a number from rules via a thing action:
+
+`String name = phonebookLookup(String number, String phonebook, int matchCount)`
+
+`phonebook` and `matchCount` are optional parameters.
+You can omit one or both of these parameters.
+The configured `matchCount` is counted from the right end and denotes the number of matching characters needed to consider this number as matching.
+A `matchCount` of `0` is considered as "match everything" and is used as default if no other value is given.
+The return value is either the phonebook entry (if found) or the input number.
+
+Example (use all phonebooks, match 5 digits from right):
+
+```
+val tr064Actions = getActions("tr064","tr064:fritzbox:2a28aee1ee")
+val result = tr064Actions.phonebookLookup("49157712341234", 5)
+```

bundles/org.openhab.binding.tr064/src/main/java/org/openhab/binding/tr064/internal/Tr064RootHandler.java

@@ -38,6 +38,7 @@ import org.openhab.binding.tr064.internal.dto.scpd.root.SCPDDeviceType;
 import org.openhab.binding.tr064.internal.dto.scpd.root.SCPDServiceType;
 import org.openhab.binding.tr064.internal.dto.scpd.service.SCPDActionType;
 import org.openhab.binding.tr064.internal.phonebook.Phonebook;
+import org.openhab.binding.tr064.internal.phonebook.PhonebookActions;
 import org.openhab.binding.tr064.internal.phonebook.PhonebookProvider;
 import org.openhab.binding.tr064.internal.phonebook.Tr064PhonebookImpl;
 import org.openhab.binding.tr064.internal.soap.SOAPConnector;
@@ -391,6 +392,6 @@ public class Tr064RootHandler extends BaseBridgeHandler implements PhonebookProv
 
     @Override
     public Collection<Class<? extends ThingHandlerService>> getServices() {
-        return Set.of(Tr064DiscoveryService.class);
+        return Set.of(Tr064DiscoveryService.class, PhonebookActions.class);
     }
 }

bundles/org.openhab.binding.tr064/src/main/java/org/openhab/binding/tr064/internal/phonebook/PhonebookActions.java

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2010-2020 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.tr064.internal.phonebook;
+
+import java.util.*;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.tr064.internal.Tr064RootHandler;
+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.thing.binding.ThingActions;
+import org.openhab.core.thing.binding.ThingActionsScope;
+import org.openhab.core.thing.binding.ThingHandler;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The {@link PhonebookActions} is responsible for handling phonebook actions
+ *
+ * @author Jan N. Klug - Initial contribution
+ */
+@ThingActionsScope(name = "tr064")
+@NonNullByDefault
+@SuppressWarnings("unused")
+public class PhonebookActions implements ThingActions {
+    private final Logger logger = LoggerFactory.getLogger(PhonebookActions.class);
+
+    private @Nullable Tr064RootHandler handler;
+
+    @RuleAction(label = "@text/phonebookLookupActionLabel", description = "@text/phonebookLookupActionDescription")
+    public @ActionOutput(name = "name", type = "java.lang.String") String phonebookLookup(
+            @ActionInput(name = "phonenumber") @Nullable String phonenumber,
+            @ActionInput(name = "matches") @Nullable Integer matchCount) {
+        return phonebookLookup(phonenumber, null, matchCount);
+    }
+
+    @RuleAction(label = "@text/phonebookLookupActionLabel", description = "@text/phonebookLookupActionDescription")
+    public @ActionOutput(name = "name", type = "java.lang.String") String phonebookLookup(
+            @ActionInput(name = "phonenumber") @Nullable String phonenumber) {
+        return phonebookLookup(phonenumber, null, null);
+    }
+
+    @RuleAction(label = "@text/phonebookLookupActionLabel", description = "@text/phonebookLookupActionDescription")
+    public @ActionOutput(name = "name", type = "java.lang.String") String phonebookLookup(
+            @ActionInput(name = "phonenumber") @Nullable String phonenumber,
+            @ActionInput(name = "phonebook") @Nullable String phonebook) {
+        return phonebookLookup(phonenumber, phonebook, null);
+    }
+
+    @RuleAction(label = "@text/phonebookLookupActionLabel", description = "@text/phonebookLookupActionDescription")
+    public @ActionOutput(name = "name", type = "java.lang.String") String phonebookLookup(
+            @ActionInput(name = "phonenumber") @Nullable String phonenumber,
+            @ActionInput(name = "phonebook") @Nullable String phonebook,
+            @ActionInput(name = "matches") @Nullable Integer matchCount) {
+        if (phonenumber == null) {
+            logger.warn("Cannot lookup a missing number.");
+            return "";
+        }
+
+        final Tr064RootHandler handler = this.handler;
+        if (handler == null) {
+            logger.info("Handler is null, cannot lookup number.");
+            return phonenumber;
+        } else {
+            int matchCountInt = matchCount == null ? 0 : matchCount;
+            if (phonebook != null && !phonebook.isEmpty()) {
+                return handler.getPhonebookByName(phonebook).flatMap(p -> p.lookupNumber(phonenumber, matchCountInt))
+                        .orElse(phonenumber);
+            } else {
+                Collection<Phonebook> phonebooks = handler.getPhonebooks();
+                return phonebooks.stream().map(p -> p.lookupNumber(phonenumber, matchCountInt))
+                        .filter(Optional::isPresent).map(Optional::get).findAny().orElse(phonenumber);
+            }
+        }
+    }
+
+    public static String phonebookLookup(ThingActions actions, @Nullable String phonenumber,
+            @Nullable Integer matchCount) {
+        return phonebookLookup(actions, phonenumber, null, matchCount);
+    }
+
+    public static String phonebookLookup(ThingActions actions, @Nullable String phonenumber) {
+        return phonebookLookup(actions, phonenumber, null, null);
+    }
+
+    public static String phonebookLookup(ThingActions actions, @Nullable String phonenumber,
+            @Nullable String phonebook) {
+        return phonebookLookup(actions, phonenumber, phonebook, null);
+    }
+
+    public static String phonebookLookup(ThingActions actions, @Nullable String phonenumber, @Nullable String phonebook,
+            @Nullable Integer matchCount) {
+        return ((PhonebookActions) actions).phonebookLookup(phonenumber, phonebook, matchCount);
+    }
+
+    @Override
+    public void setThingHandler(@Nullable ThingHandler handler) {
+        if (handler instanceof Tr064RootHandler) {
+            this.handler = (Tr064RootHandler) handler;
+        }
+    }
+
+    @Override
+    public @Nullable ThingHandler getThingHandler() {
+        return handler;
+    }
+}

bundles/org.openhab.binding.tr064/src/main/resources/OH-INF/i18n/tr064.properties

@@ -0,0 +1,3 @@
+# actions
+phonebookLookupActionLabel = lookup a phonenumber
+phonebookLookupActionDescription = Lookup a phone number.

bundles/org.openhab.binding.tr064/src/main/resources/OH-INF/i18n/tr064_de.properties

@@ -5,3 +5,7 @@ profile.config.transform.PHONEBOOK.matchCount.label =
 profile.config.transform.PHONEBOOK.matchCount.description = Die Anzahl der Ziffern, die mit dem eingehenden Wert übereinstimmen, von rechts gezählt (Vorgabe ist 0 = alle müssen übereinstimmen).
 profile.config.transform.PHONEBOOK.phoneNumberIndex.label = Telefonnummern-Index
 profile.config.transform.PHONEBOOK.phoneNumberIndex.description = Der Index der Telefonnummer, die aus einem CallItem-State (StringListType) aufgelöst werden soll, 0 oder 1 (Vorgabe ist 0).
+
+# actions
+phonebookLookupActionLabel = schlage eine Telefonnummer nach
+phonebookLookupActionDescription = Schlägt eine Telefonnummer nach.