@sapui5/sap.ushell 1.120.7 → 1.121.0

package/src/main/js/sap/ushell/services/Notifications.js

@@ -1,5 +1,8 @@
 // Copyright (c) 2009-2023 SAP SE, All Rights Reserved
-
+/**
+ * @fileoverview Notifications service
+ * @deprecated As of version 1.120, please use NotificationsV2
+ */
 sap.ui.define([
     "sap/ui/thirdparty/jquery",
     "sap/ushell/services/NotificationsV2" // preload NotificationsV2 early
@@ -14,6 +17,10 @@ sap.ui.define([
      * @classdesc UShell service for fetching user notification data from the Notification center/service<br>
      * and exposing them to the Unified Shell and Fiori applications UI controls.
      *
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("ClientSideTargetResolution")</code>. For details, see
+     * {@link sap.ushell.Container#getServiceAsync}.
+     *
      * In order to get user notifications, Unified Shell notification service issues OData requests<br>
      * to the service defined by the configuration property <code>serviceUrl</code>,<br>
      * for example: "/sap/opu/odata4/iwngw/notification/default/iwngw/notification_srv/0001"<br>.
@@ -31,16 +38,17 @@ sap.ui.define([
      *   - Execution of a notification actions
      *   - Marking user notifications as seen
      *
-     * @hideconstructor
-     *
      * @param {object} oContainerInterface The interface provided by the container
      * @param {object} sParameters Not used in this service
      * @param {object} oServiceConfiguration configuration
      *
-     * @see sap.ushell.services.Container#getServiceAsync
+     * @augments sap.ushell.services.Service
+     * @hideconstructor
+     *
+     * @see sap.ushell.Container#getServiceAsync
      * @since 1.32.0
-     * @deprecated since 1.119. Please use {@link sap.ushell.services.NotificationsV2} instead.
      * @public
+     * @deprecated since 1.119. Please use {@link sap.ushell.services.NotificationsV2} instead.
      */
     function Notifications (oContainerInterface, sParameters, oServiceConfiguration) {
 
@@ -55,7 +63,7 @@ sap.ui.define([
             return this.oNotificationsV2Promise;
         };
 
-        // Wrap Promise into jQuery.Deferred.promise
+        // Wrap Promise into jQuery.Deferred
         this._proxyV2 = function (sMethod, aArguments) {
             var oDeferred = new jQuery.Deferred();
             this._getNotificationsV2()
@@ -82,9 +90,9 @@ sap.ui.define([
          * The service configuration must also include serviceUrl attribute.<br>
          *
          * @returns {boolean} A boolean value indicating whether the notifications service is enabled
+         *
          * @since 1.32.0
          * @public
-         * @alias sap.ushell.services.Notifications#isEnabled
          */
         this.isEnabled = function () {
             var oServiceConfig = oServiceConfiguration && oServiceConfiguration.config;
@@ -107,7 +115,6 @@ sap.ui.define([
          *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#init
          */
         this.init = function () {
             this._proxyV2("init");
@@ -117,10 +124,10 @@ sap.ui.define([
          * Returns the number of unseen notifications<br>
          * e.g. Notifications that the user hasn't seen yet.
          *
-         * @returns {jQuery.Deferred.promise} Promise object that on success - returns the number of unread notifications of the user
+         * @returns {jQuery.Promise} Resolves the number of unread notifications of the user
+         *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#getUnseenNotificationsCount
          */
         this.getUnseenNotificationsCount = function () {
             return this._proxyV2("getUnseenNotificationsCount");
@@ -131,9 +138,9 @@ sap.ui.define([
          * e.g. Notifications for user.
          *
          * @returns {int} Returns the number of notifications of the user
+         *
          * @since 1.44
          * @public
-         * @alias sap.ushell.services.Notifications#getNotificationsCount
          */
         this.getNotificationsCount = function () {
             return this._proxyV2sync("getNotificationsCount", "0");
@@ -142,10 +149,10 @@ sap.ui.define([
         /**
          * Returns the notifications of the user sorted by type include the group headers and the notifications
          *
-         * @returns {jQuery.Deferred.promise} Promise object that - on success - returns all notification items
+         * @returns {jQuery.Promise} Resolves all notification items
+         *
          * @since 1.38
          * @public
-         * @alias sap.ushell.services.Notifications#getNotificationsByTypeWithGroupHeaders
          */
         this.getNotificationsByTypeWithGroupHeaders = function () {
             return this._proxyV2("getNotificationsByTypeWithGroupHeaders");
@@ -154,10 +161,10 @@ sap.ui.define([
         /**
          * Returns the group headers of the user notifications
          *
-         * @returns {jQuery.Deferred.promise} Promise object that - on success - returns all group headers
+         * @returns {jQuery.Promise} Resolves all group headers
+         *
          * @since 1.44
          * @public
-         * @alias sap.ushell.services.Notifications#getNotificationsGroupHeaders
          */
         this.getNotificationsGroupHeaders = function () {
             return this._proxyV2("getNotificationsGroupHeaders");
@@ -175,9 +182,9 @@ sap.ui.define([
          * Returns the 10 most recent notifications of the user
          *
          * @returns {Promise} Promise object that on success - returns the 10 most recent user notification items
+         *
          * @since 1.32
          * @private
-         * @alias sap.ushell.services.Notifications#getNotifications
          */
         this.getNotifications = function () {
             return this._proxyV2("getNotifications", arguments);
@@ -190,9 +197,9 @@ sap.ui.define([
          * @param {string} sNotificationGroupId The ID of the notification header/group whose action is being executed
          * @param {string} sActionId The ID of the action that is being executed
          * @returns {Promise<undefined>} Promise object that on success resolves to undefined or it is rejected with failed notifications
+         *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#executeBulkAction
          */
         this.executeBulkAction = function (sNotificationGroupId, sActionId) {
             return this._proxyV2("executeBulkAction", arguments);
@@ -219,10 +226,10 @@ sap.ui.define([
          * After launching the action, the function gets updated notification data in order to push the updated data to the consumers.
          *
          * @param {string} sNotificationId The ID of the notification whose action is being executed
-         * @returns {jQuery.Deferred.promise} Promise object that on success resolves to undefined or it is rejected with a message object
+         * @returns {jQuery.Promise} Resolves to undefined or it is rejected with a message object
+         *
          * @since 1.34
          * @public
-         * @alias sap.ushell.services.Notifications#markRead
          */
         this.markRead = function (sNotificationId) {
             return this._proxyV2("markRead", arguments);
@@ -232,10 +239,10 @@ sap.ui.define([
          * Launches dismiss notification call.<br>
          *
          * @param {string} sNotificationId The ID of the notification whose action is being executed
-         * @returns {jQuery.Deferred.promise} Promise object that on success resolves to undefined or it is rejected with a message object
+         * @returns {jQuery.Promise} Resolves to undefined or it is rejected with a message object
+         *
          * @since 1.34
          * @public
-         * @alias sap.ushell.services.Notifications#dismissNotification
          */
         this.dismissNotification = function (sNotificationId) {
             return this._proxyV2("dismissNotification", arguments);
@@ -245,9 +252,9 @@ sap.ui.define([
          * Gets a callback function that will be called when updated notifications data is available.
          *
          * @param {function} callback The callback function that is registered and called on data update.
+         *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#registerNotificationsUpdateCallback
          */
         this.registerNotificationsUpdateCallback = function (callback) {
             this._proxyV2("registerNotificationsUpdateCallback", arguments);
@@ -275,9 +282,9 @@ sap.ui.define([
          * Gets a callback function that will be called when updated unseen notifications count is available.
          *
          * @param {function} callback The callback function that is registered and called on data update.
+         *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#registerNotificationCountUpdateCallback
          */
         this.registerNotificationCountUpdateCallback = function (callback) {
             this._proxyV2("registerNotificationCountUpdateCallback", arguments);
@@ -289,7 +296,6 @@ sap.ui.define([
          *
          * @since 1.32
          * @public
-         * @alias sap.ushell.services.Notifications#notificationsSeen
          */
         this.notificationsSeen = function () {
             this._setNotificationsAsSeen();
@@ -297,16 +303,17 @@ sap.ui.define([
 
         /**
          * @returns {boolean} boolean value whether first request was already performed and data was returned.<br>
+         *
          * @since 1.38
          * @public
-         * @alias sap.ushell.services.Notifications#isFirstDataLoaded
          */
         this.isFirstDataLoaded = function () {
             return this._proxyV2sync("isFirstDataLoaded", false);
         };
 
         /**
-         * @returns {Promise} Promise object that is resolved with the settings from the sever
+         * @returns {jQuery.Promise} Resolves with the settings from the server.
+         *
          * @since 1.41
          * @private
          */
@@ -315,7 +322,8 @@ sap.ui.define([
         };
 
         /**
-         * @returns {object} oPromise
+         * @returns {jQuery.Promise} Resolves once the settings were saved.
+         *
          * @since 1.41
          * @private
          */
@@ -324,7 +332,8 @@ sap.ui.define([
         };
 
         /**
-         * @returns {object} promise
+         * @returns {jQuery.Promise} Resolves the user settings flag.
+         *
          * @since 1.41
          * @private
          */
@@ -342,6 +351,7 @@ sap.ui.define([
 
         /**
          * @returns {boolean} value indicating whether the Push to Mobile capability is supported by the Notification channel
+         *
          * @since 1.43
          * @private
          */
@@ -350,7 +360,8 @@ sap.ui.define([
         };
 
         /**
-         * @returns {Array} dismissed notifications
+         * @returns {Array<*>} dismissed notifications
+         *
          * @since 1.43
          * @private
          */
@@ -363,7 +374,7 @@ sap.ui.define([
         };
 
         /**
-         * adds an item to the array of dissmissed notifications
+         * adds an item to the array of dismissed notifications
          *
          * @since 1.43
          * @private
@@ -373,7 +384,7 @@ sap.ui.define([
         };
 
         /**
-         * initialize array of dissmissed notifications
+         * initialize array of dismissed notifications
          *
          * @since 1.43
          * @private
@@ -384,6 +395,7 @@ sap.ui.define([
 
         /**
          * @returns {boolean} value indicating whether the Push to Mobile capability is supported by the Notification channel
+         *
          * @since 1.43
          * @private
          */
@@ -409,7 +421,8 @@ sap.ui.define([
          * In the future the two functions will be sent together in a single batch request, when batch is supported.
          *
          * @param {boolean} bUpdateCustomers boolean parameter indicating whether to update the registered consumers or not
-         * @returns {object} promise
+         * @returns {jQuery.Promise} Resolves the unseen notifications count.
+         *
          * @private
          */
         this._readUnseenNotificationsCount = function (bUpdateCustomers) {
@@ -418,14 +431,17 @@ sap.ui.define([
 
         /**
          * Fetching the number of notifications for user<br>
-         * @returns {object} promise
+         * @returns {jQuery.Promise} Resolves the notifications count.
+         *
+         * @private
          */
         this.readNotificationsCount = function () {
             return this._proxyV2("readNotificationsCount", arguments);
         };
 
         /**
-         * @returns {Promise} Returns promise object that is resolved if Notification settings data is available, and rejected if not
+         * @returns {jQuery.Promise} Resolves if Notification settings data is available, and rejected if not.
+         *
          * @private
          */
         this._getNotificationSettingsAvailability = function () {
@@ -449,7 +465,8 @@ sap.ui.define([
          *   - Dependent consumers are updated (i.e. call that._updateDependentNotificationsConsumers())
          *
          * @param {boolean} bUpdateConsumers value indicating whether the consumers should be updated
-         * @returns {object} oDeferred.promise() object, indicating success of both read actions
+         * @returns {jQuery.Promise} Resolves if both read actions were successful.
+         *
          * @private
          */
         this._readNotificationsData = function (bUpdateConsumers) {
@@ -482,7 +499,7 @@ sap.ui.define([
         /**
          * Verifying whether the "push notifications to mobile" feature is supported.
          *
-         * @returns {object} A Deferred.promise object that is always resolved even if the request failed.<br>
+         * @returns {Promise} Resolves always even if the request failed.<br>
          *   In case of failure - the response property successStatus gets the value <code>false</code>
          */
         this._readMobileSettingsFromServer = function () {
@@ -492,7 +509,7 @@ sap.ui.define([
         /**
          * Verifying whether the "push notifications to mobile" feature is supported.
          *
-         * @returns {object} A Deferred.promise object that is always resolved even if the request failed.<br>
+         * @returns {Promise} Resolves always even if the request failed.<br>
          *   In case of failure - the response property successStatus gets the value <code>false</code>
          */
         this._readEmailSettingsFromServer = function () {
@@ -506,7 +523,7 @@ sap.ui.define([
         /**
          * Verifying whether the WebSocket is active (while it is already opened)
          *
-         * @returns {object} A Deferred.promise object that is always resolved even if the request fails.<br>
+         * @returns {jQuery.Promise} Resolves always even if the request fails.<br>
          *   The actual response is returned as the done function's boolean parameter:<br>
          *   In case of active WebSocket - the value <code>true</code> is returned, and <code>false</code> otherwise.
          */