git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2024 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.io.openhabcloud;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.openhab.core.model.script.engine.action.ActionDoc;
  18 import org.openhab.io.openhabcloud.internal.CloudService;
  19 import org.slf4j.Logger;
  20 import org.slf4j.LoggerFactory;
  21
  22 /**
  23  * This class provides static methods that can be used in automation rules
  24  * for sending notifications to the native apps.
  25  *
  26  * @author Victor Belov - Initial contribution
  27  * @author Kai Kreuzer - migrated code to ESH APIs
  28  * @author Dan Cunningham - Extended notification enhancements
  29  */
  30 @NonNullByDefault
  31 public class NotificationAction {
  32
  33     private static final Logger logger = LoggerFactory.getLogger(NotificationAction.class);
  34
  35     public static @Nullable CloudService cloudService;
  36
  37     /**
  38      * Sends a simple push notification to mobile devices of user
  39      *
  40      * @param userId the cloud user id of the recipient
  41      * @param message the body of the notification
  42      *
  43      */
  44     @ActionDoc(text = "Sends a push notification to mobile devices of user with userId")
  45     public static void sendNotification(String userId, String message) {
  46         sendNotification(userId, message, null, null);
  47     }
  48
  49     /**
  50      * Sends an advanced push notification to mobile devices of user
  51      *
  52      * @param userId the cloud user id of the recipient
  53      * @param message the body of the notification
  54      * @param icon name for the notification
  55      * @param tag for the notification (formerly severity)
  56      *
  57      */
  58     @ActionDoc(text = "Sends a push notification to mobile devices of user with userId")
  59     public static void sendNotification(String userId, String message, @Nullable String icon, @Nullable String tag) {
  60         sendNotification(userId, message, icon, tag, null, null, null, null, null, null, null);
  61     }
  62
  63     /**
  64      * Sends an advanced push notification to mobile devices of user
  65      *
  66      * @param userId the cloud user id of the recipient
  67      * @param message the body of the notification
  68      * @param icon name for the notification
  69      * @param tag for the notification
  70      * @param title for the notification
  71      * @param referenceId an identifier used to collapse and hide notifications
  72      * @param onClickAction the action to perform when clicked
  73      * @param mediaAttachmentUrl the media to attach to a notification
  74      * @param actionButton1 an action button in the format "Title=Action"
  75      * @param actionButton2 an action button in the format "Title=Action"
  76      * @param actionButton3 an action button in the format "Title=Action"
  77      *
  78      */
  79     @ActionDoc(text = "Sends a push notification to mobile devices of user with userId")
  80     public static void sendNotification(String userId, String message, @Nullable String icon, @Nullable String tag,
  81             @Nullable String title, @Nullable String referenceId, @Nullable String onClickAction,
  82             @Nullable String mediaAttachmentUrl, @Nullable String actionButton1, @Nullable String actionButton2,
  83             @Nullable String actionButton3) {
  84         logger.debug("sending notification '{}' to user {}", message, userId);
  85         if (cloudService != null) {
  86             cloudService.sendNotification(userId, message, icon, tag, title, referenceId, onClickAction,
  87                     mediaAttachmentUrl, actionButton1, actionButton2, actionButton3);
  88         }
  89     }
  90
  91     /**
  92      * Sends a simple notification to log. Log notifications are not pushed to user
  93      * devices but are shown to all account users in notifications log.
  94      *
  95      * @param message the body of the notification
  96      *
  97      */
  98     @ActionDoc(text = "Sends a log notification which is shown in notifications log to all account users")
  99     public static void sendLogNotification(String message) {
 100         sendLogNotification(message, null, null);
 101     }
 102
 103     /**
 104      * Sends an advanced notification to log. Log notifications are not pushed to user
 105      * devices but are shown to all account users in notifications log.
 106      *
 107      * @param message the body of the notification
 108      * @param icon name for the notification
 109      * @param tag for the notification (formerly severity)
 110      *
 111      */
 112     @ActionDoc(text = "Sends a log notification which is shown in notifications log to all account users")
 113     public static void sendLogNotification(String message, @Nullable String icon, @Nullable String tag) {
 114         logger.debug("sending log notification '{}'", message);
 115         if (cloudService != null) {
 116             cloudService.sendLogNotification(message, icon, tag);
 117         }
 118     }
 119
 120     /**
 121      * Sends a simple broadcast notification. Broadcast notifications are pushed to all
 122      * mobile devices of all users of the account
 123      *
 124      * @param message the body of the notification
 125      *
 126      */
 127     @ActionDoc(text = "Sends a broadcast notification to all mobile devices of all account users")
 128     public static void sendBroadcastNotification(String message) {
 129         sendBroadcastNotification(message, null, null);
 130     }
 131
 132     /**
 133      * Sends an advanced broadcast notification. Broadcast notifications are pushed to all
 134      * mobile devices of all users of the account
 135      *
 136      * @param message the body of the notification
 137      * @param icon name for the notification
 138      * @param tag for the notification (formerly severity)
 139      *
 140      */
 141     @ActionDoc(text = "Sends a broadcast notification to all mobile devices of all account users")
 142     public static void sendBroadcastNotification(String message, @Nullable String icon, @Nullable String tag) {
 143         sendBroadcastNotification(message, icon, tag, null, null, null, null, null, null, null);
 144     }
 145
 146     /**
 147      * Sends an advanced broadcast notification. Broadcast notifications are pushed to all
 148      * mobile devices of all users of the account
 149      *
 150      * @param message the body of the notification
 151      * @param icon name for the notification
 152      * @param tag for the notification
 153      * @param title for the notification
 154      * @param referenceId an identifier used to collapse and hide notifications
 155      * @param onClickAction the action to perform when clicked
 156      * @param mediaAttachmentUrl the media to attach to a notification
 157      * @param actionButton1 an action button in the format "Title=Action"
 158      * @param actionButton2 an action button in the format "Title=Action"
 159      * @param actionButton3 an action button in the format "Title=Action"
 160      *
 161      */
 162     @ActionDoc(text = "Sends a broadcast notification to all mobile devices of all account users")
 163     public static void sendBroadcastNotification(String message, @Nullable String icon, @Nullable String tag,
 164             @Nullable String title, @Nullable String referenceId, @Nullable String onClickAction,
 165             @Nullable String mediaAttachmentUrl, @Nullable String actionButton1, @Nullable String actionButton2,
 166             @Nullable String actionButton3) {
 167         logger.debug("sending broadcast notification '{}' to all users", message);
 168         if (cloudService != null) {
 169             cloudService.sendBroadcastNotification(message, icon, tag, title, referenceId, onClickAction,
 170                     mediaAttachmentUrl, actionButton1, actionButton2, actionButton3);
 171         }
 172     }
 173
 174     /**
 175      * Hides notifications that contains a matching reference id to all mobile devices of a single user.
 176      *
 177      * @param userId the cloud user id of the recipient
 178      * @param referenceId the user reference id
 179      *
 180      */
 181     @ActionDoc(text = "Hides notifications that contain the reference id on mobile devices of user with userId")
 182     public static void hideNotificationByReferenceId(String userId, String referenceId) {
 183         if (cloudService != null) {
 184             cloudService.hideNotificationByReferenceId(userId, referenceId);
 185         }
 186     }
 187
 188     /**
 189      * Hides notifications that contains a matching reference id to all mobile devices of all users of the account
 190      *
 191      * @param referenceId the user reference id
 192      *
 193      */
 194     @ActionDoc(text = "Hides notifications that contain the reference id on all mobile devices of all account users")
 195     public static void hideBroadcastNotificationByReferenceId(String referenceId) {
 196         if (cloudService != null) {
 197             cloudService.hideBroadcastNotificationByReferenceId(referenceId);
 198         }
 199     }
 200
 201     /**
 202      * Hides notifications that are associated with a tag to all mobile devices of a single user.
 203      *
 204      * @param userId the cloud user id of the recipient
 205      * @param tag the tag associated with notifications
 206      *
 207      */
 208     @ActionDoc(text = "Hides notifications that are associated with a tag on mobile devices of user with userId")
 209     public static void hideNotificationByTag(String userId, String tag) {
 210         if (cloudService != null) {
 211             cloudService.hideNotificationByTag(userId, tag);
 212         }
 213     }
 214
 215     /**
 216      * Hides notifications that are associated with a tag to all mobile devices of all users of the account
 217      *
 218      * @param tag the tag associated with notifications
 219      *
 220      */
 221     @ActionDoc(text = "Hides notifications that are associated with a tag on all mobile devices of all account users")
 222     public static void hideBroadcastNotificationByTag(String tag) {
 223         if (cloudService != null) {
 224             cloudService.hideBroadcastNotificationByTag(tag);
 225         }
 226     }
 227 }