[pushover] Migration of Pushover OH1 action to OH3 binding (#8586)

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

CODEOWNERS

@@ -201,6 +201,7 @@
 /bundles/org.openhab.binding.powermax/ @lolodomo
 /bundles/org.openhab.binding.pulseaudio/ @peuter
 /bundles/org.openhab.binding.pushbullet/ @hakan42
+/bundles/org.openhab.binding.pushover/ @cweitkamp
 /bundles/org.openhab.binding.radiothermostat/ @mlobstein
 /bundles/org.openhab.binding.regoheatpump/ @crnjan
 /bundles/org.openhab.binding.revogi/ @andibraeu

bom/openhab-addons/pom.xml

@@ -996,6 +996,11 @@
       <artifactId>org.openhab.binding.pushbullet</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.pushover</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.radiothermostat</artifactId>

bundles/org.openhab.binding.pushover/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

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

@@ -0,0 +1,78 @@
+# Pushover Binding
+
+The Pushover binding allows you to notify mobile devices of a message using the [Pushover REST API](https://pushover.net/api).
+To get started you first need to register (a free process) to get an API token.
+Initially you have to create an application, set its name and optionally upload an icon, and get the API token in return.
+Once you have the token, you need a user key (or group key) and optionally a device name for each user to which you want to push notifications.
+
+## Supported Things
+
+There is only one Thing available - the `pushover-account`.
+You are able to create multiple instances of this Thing to broadcast to different users, groups or devices.
+
+## Thing Configuration
+
+| Configuration Parameter | Type    | Description                                                                                                                                          |
+|-------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `apikey`                | text    | Your API token / key (APP_TOKEN) to access the Pushover Message API. **mandatory**                                                                   |
+| `user`                  | text    | Your user key or group key (USER_KEY) to which you want to push notifications. **mandatory**                                                         |
+| `title`                 | text    | The default title of a message (default: `openHAB`).                                                                                                 |
+| `format`                | text    | The default format (`none`, `HTML` or `monospace`) of a message (default: `none`).                                                                   |
+| `sound`                 | text    | The default notification sound on target device (default: `default`) (see [supported notification sounds](https://pushover.net/api#sounds)).         |
+| `retry`                 | integer | The retry parameter specifies how often (in seconds) the Pushover servers will send the same notification to the user (default: `300`). **advanced** |
+| `expire`                | integer | The expire parameter specifies how long (in seconds) your notification will continue to be retried (default: `3600`). **advanced**                   |
+
+The `retry` and `expire` parameters are only used for emergency-priority notifications.
+
+## Channels
+
+Currently the binding does not support any Channels.
+
+## Thing Actions
+
+All actions return a `Boolean` value to indicate if the message - parameter `message` **mandatory** - was sent successfully or not.
+The `title` parameter defaults to whatever value you defined in the `title` related configuration parameter.
+
+`sendMessage(String message, @Nullable String title)` - This method is used to send a plain text message.
+`sendHtmlMessage(String message, @Nullable String title)` - This method is used to send a HTML message.
+`sendMonospaceMessage(String message, @Nullable String title)` - This method is used to send a monospace message.
+`sendAttachmentMessage(String message, @Nullable String title, String attachment, @Nullable String contentType)` - This method is used to send a message with an attachment. It takes a (local) path  (`attachment` **mandatory**) to the attachment and an optional parameter `contentType` to define the content-type of the attachment (default: `image/jpeg`).
+`sendURLMessage(String message, @Nullable String title, String url, @Nullable String urlTitle)` - This method is used to send a message with an URL. A supplementary `url` to show with the message and a `urlTitle` for the URL, otherwise just the URL is shown.
+`sendMessageToDevice(String device, String message, @Nullable String title)` - This method is used to send a message to a specific device. Parameter `device` **mandatory** is the name of a specific device (multiple devices may be separated by a comma).
+
+The `sendPriorityMessage` action returns a `String` value (the `receipt`) if the message was sent successfully, otherwise `null`.
+
+`sendPriorityMessage(String message, @Nullable String title, @Nullable Integer priority)` - This method is used to send a priority message. Parameter `priority` is the priority (`-2`, `-1`, `0`, `1`, `2`) to be used (default: `2`).
+
+`cancelPriorityMessage` returns a `Boolean` value to indicate if the message was cancelled successfully or not.
+
+`cancelPriorityMessage(String receipt)` - This method is used to cancel a priority message.
+
+## Full Example
+
+demo.things:
+
+```java
+Thing pushover:pushover-account:account [ apikey="APP_TOKEN", user="USER_KEY" ]
+```
+
+demo.rules:
+
+```java
+val actions = getActions("pushover", "pushover:pushover-account:account")
+// send HTML message
+actions.sendHtmlMessage("Hello <font color='green'>World</font>!", "openHAB")
+```
+
+```java
+val actions = getActions("pushover", "pushover:pushover-account:account")
+// send priority message
+var receipt = actions.sendPriorityMessage("Hello <font color='green'>World</font>!", "openHAB", 3)
+
+// wait for your cancel condition
+
+if( receipt !== null ) {
+    actions.cancelPriorityMessage(receipt)
+    receipt = null
+}
+```

bundles/org.openhab.binding.pushover/pom.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>3.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.pushover</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Pushover Binding</name>
+
+</project>

bundles/org.openhab.binding.pushover/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.pushover-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-pushover" description="Pushover Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.pushover/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.pushover/src/main/java/org/openhab/binding/pushover/internal/PushoverBindingConstants.java

@@ -0,0 +1,34 @@
+/**
+ * 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.pushover.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link PushoverBindingConstants} class defines common constants, which are used across the whole binding.
+ *
+ * @author Christoph Weitkamp - Initial contribution
+ */
+@NonNullByDefault
+public class PushoverBindingConstants {
+
+    private static final String BINDING_ID = "pushover";
+
+    public static final ThingTypeUID PUSHOVER_ACCOUNT = new ThingTypeUID(BINDING_ID, "pushover-account");
+
+    public static final String CONFIG_SOUND = "sound";
+
+    public static final String DEFAULT_SOUND = "default";
+    public static final String DEFAULT_TITLE = "openHAB";
+}