@sapui5/sap.ushell 1.140.0 → 1.141.0

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

@@ -2,12 +2,16 @@
 
 /**
  * @fileOverview This module exposes API endpoints for Generic Communication
- * @version 1.140.0
+ * @version 1.141.0
  */
 sap.ui.define([
+    "sap/ushell/services/MessageBroker/ClientAlias",
+    "sap/ushell/services/MessageBroker/ClientConnectionMessage",
     "sap/ushell/services/MessageBroker/MessageBrokerEngine",
     "sap/base/Log"
 ], (
+    ClientAlias,
+    ClientConnectionMessage,
     MessageBrokerEngine,
     Log
 ) => {
@@ -15,6 +19,45 @@ sap.ui.define([
 
     let oServiceConfig = {};
 
+    /**
+     * @typedef {object} sap.ushell.services.MessageBroker.Channel
+     * @param {string} channelId channel id.
+     *
+     * @since 1.110.0
+     * @private
+     * @ui5-restricted SAP internally public
+     */
+
+    /**
+     * @callback sap.ushell.services.MessageBroker.MessageCallback
+     * The message callback function of clients that are subscribed to a channel.
+     * It is called whenever a message is published to the channel.
+     *
+     * @param {string} sClientId The client id of the sender.
+     * @param {string} sChannelId The channel id.
+     * @param {string} sMessageName The message name.
+     * @param {object} oData The data of the message.
+     *
+     * @since 1.110.0
+     * @private
+     * @ui5-restricted SAP internally public
+     */
+
+    /**
+     * @callback sap.ushell.services.MessageBroker.ClientConnectionCallback
+     * The client connection callback function of clients.
+     * It is called initially when the client subscribes to a channel and
+     * whenever a client subscribes, unsubscribes or disconnects.
+     *
+     * @param {sap.ushell.services.MessageBroker.ClientConnectionMessage} sMessageName The message name.
+     * @param {string} sClientId The client id.
+     * @param {sap.ushell.services.MessageBroker.Channel[]} aSubscribedChannels The channels the client is subscribed to.
+     *
+     * @since 1.110.0
+     * @private
+     * @ui5-restricted SAP internally public
+     */
+
     /**
      * @alias sap.ushell.services.MessageBroker
      * @class
@@ -31,64 +74,88 @@ sap.ui.define([
      * @hideconstructor
      *
      * @param {object} oContainerInterface the container interface, not in use.
-     * @param {object} sParameters the parameter string, not in use.
+     * @param {string} sParameters the parameter string, not in use.
      * @param {object} oServiceConfiguration the service configuration.
      *
      * @since 1.72.0
      * @private
+     * @ui5-restricted SAP internally public
      */
     function MessageBroker (oContainerInterface, sParameters, oServiceConfiguration) {
         oServiceConfig = oServiceConfiguration?.config || {};
         MessageBrokerEngine.setEnabled(this.isEnabled());
         if (!this.isEnabled()) {
             Log.warning("FLP's message broker service is disabled by shell configuration");
+            return;
         }
     }
 
+    // Expose enums
+    MessageBroker.prototype.ClientConnectionMessage = ClientConnectionMessage;
+    MessageBroker.prototype.ClientAlias = ClientAlias;
+
+    /**
+     * Returns whether the service is enabled or not.
+     * @returns {boolean} true if the service is enabled, false otherwise.
+     *
+     * @since 1.110.0
+     * @private
+     */
     MessageBroker.prototype.isEnabled = function () {
-        return oServiceConfig.enabled || oServiceConfig.enabled === undefined;
+        return oServiceConfig.enabled ?? true;
     };
 
     /**
-     *
+     * Connects the client to the message broker.
+     * When the client connects, it will receive the information about all other clients that are already subscribed to channels.
+     * Additionally, the client is informed about _any_ new subscription and unsubscription to a channel.
      * @param {string} sClientId client id.
-     * @returns {Promise} Promise result.
+     * @param {sap.ushell.services.MessageBroker.ClientConnectionCallback} fnClientConnectionCallback
+     * Callback function that is called whenever the client subscribes or unsubscribes to a channel.
+     * @returns {Promise} Resolves once the client is connected.
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
-    MessageBroker.prototype.connect = function (sClientId) {
-        return MessageBrokerEngine.connect(sClientId);
+    MessageBroker.prototype.connect = async function (sClientId, fnClientConnectionCallback) {
+        await MessageBrokerEngine.connect(sClientId, fnClientConnectionCallback);
     };
 
     /**
-     *
-     * @param {string} sClientId client ID.
-     * @returns {Promise} Promise result.
+     * Disconnects the client.
+     * If the client was subscribed to channels, it will be unsubscribed from all channels.
+     * @param {string} sClientId client id.
+     * @returns {Promise} Resolves once the client is disconnected.
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
-    MessageBroker.prototype.disconnect = function (sClientId) {
-        return MessageBrokerEngine.disconnect(sClientId);
+    MessageBroker.prototype.disconnect = async function (sClientId) {
+        await MessageBrokerEngine.disconnect(sClientId);
     };
 
     /**
-     *
+     * Subscribe to a channel.
+     * Before subscribing, the client must be connected.
+     * Afterwards, the client receives messages for the subscribed channels.
      * @param {string} sClientId client id.
-     * @param {Array<*>} aSubscribedChannels array of channel-objects.
-     * @param {function} fnMessageCallback callback function returns promise.
-     * @param {function} fnClientConnectionCallback callback function returns promise.
-     * @returns {Promise} Promise result.
+     * @param {sap.ushell.services.MessageBroker.Channel[]} aSubscribedChannels array of channel-objects.
+     * @param {sap.ushell.services.MessageBroker.MessageCallback} fnMessageCallback
+     * Callback function that is called whenever a message is published to subscribed channels.
+     * The message callback is overwritten on subsequent calls to subscribe.
+     * Every channel can has its own message callback.
+     * @param {sap.ushell.services.MessageBroker.ClientConnectionCallback} fnClientConnectionCallback
+     * <b>DEPRECATED</b> Should be provided as part of {@link #connect}.
+     * @returns {Promise} Resolves once the client is subscribed to the channels.
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
-    MessageBroker.prototype.subscribe = function (sClientId, aSubscribedChannels, fnMessageCallback, fnClientConnectionCallback) {
-        return MessageBrokerEngine.subscribe(
+    MessageBroker.prototype.subscribe = async function (sClientId, aSubscribedChannels, fnMessageCallback, fnClientConnectionCallback) {
+        await MessageBrokerEngine.subscribe(
             sClientId,
             aSubscribedChannels,
             fnMessageCallback,
@@ -97,75 +164,86 @@ sap.ui.define([
     };
 
     /**
-     *
-     * @param {string} sClientId client ID.
-     * @param {Array<*>} aUnsubscribedChannels channels to unsubscribe from.
-     * @returns {Promise} Promise result.
+     * Unsubscribes the client from the specified channels.
+     * @param {string} sClientId client id.
+     * @param {sap.ushell.services.MessageBroker.Channel[]} aUnsubscribedChannels channels to unsubscribe from.
+     * @returns {Promise} Resolves once the client is unsubscribed from the channels.
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
-    MessageBroker.prototype.unsubscribe = function (sClientId, aUnsubscribedChannels) {
-        return MessageBrokerEngine.unsubscribe(sClientId, aUnsubscribedChannels);
+    MessageBroker.prototype.unsubscribe = async function (sClientId, aUnsubscribedChannels) {
+        await MessageBrokerEngine.unsubscribe(sClientId, aUnsubscribedChannels);
     };
 
     /**
-     *
-     * @param {string} sChannelId channel Id.
-     * @param {string} sClientId client Id.
-     * @param {string} sMessageId message Id.
-     * @param {string} sMessageName message name.
-     * @param {Array<*>} aTargetClientIds array of target clients Ids.
-     * @param {object} data additional data.
-     * @returns {Promise} Promise result.
+     * Publishes a message to a channel.
+     * All clients that are subscribed to the channel will receive the message.
+     * The message is NOT sent to the client that published it.
+     *
+     * @param {string} sChannelId channel id.
+     * @param {string} sClientId The client id of the sender.
+     * @param {string} sMessageId
+     * <b>DEPRECATED</b> Should not be provided.
+     * @param {string} sMessageName message name. Can be used to identify the message type or as a topic.
+     * @param {string[]|sap.ushell.services.MessageBroker.ClientAlias.AllClients} vTargetClientIds
+     * list of target client ids. Can include the wildcard "*" to send the message to all clients subscribed to the channel.
+     * If the wildcard is used, the other client ids are ignored.
+     * @param {object} oData additional data.
+     * @returns {Promise} Resolves once the message is published successfully.
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
-    MessageBroker.prototype.publish = function (sChannelId, sClientId, sMessageId, sMessageName, aTargetClientIds, data) {
-        return MessageBrokerEngine.publish(
+    MessageBroker.prototype.publish = async function (sChannelId, sClientId, sMessageId, sMessageName, vTargetClientIds, oData) {
+        await MessageBrokerEngine.publish(
             sChannelId,
             sClientId,
             sMessageId,
             sMessageName,
-            aTargetClientIds,
-            data
+            vTargetClientIds,
+            oData
         );
     };
 
     /**
+     * Adds the iframe origin to the list of accepted origins.
+     * The port is automatically added based on the protocol (HTTP/HTTPS).
      *
-     * @param {string} sOrigin iframe src.
+     * @param {string} sOrigin The iframe origin (e.g https://www.example.com:443)
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
     MessageBroker.prototype.addAcceptedOrigin = function (sOrigin) {
         MessageBrokerEngine.addAcceptedOrigin(sOrigin);
     };
 
     /**
+     * Removes the iframe origin from the list of accepted origins.
+     * Also removes the origin with or without port based on the protocol (HTTP/HTTPS).
      *
-     * @param {string} sOrigin iframe src.
+     * @param {string} sOrigin The iframe origin (e.g https://www.example.com:443)
      *
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
     MessageBroker.prototype.removeAcceptedOrigin = function (sOrigin) {
         MessageBrokerEngine.removeAcceptedOrigin(sOrigin);
     };
 
     /**
+     * Returns the current list of accepted origins.
+     * @returns {string[]} The list of accepted origins.
      *
-     * @returns {Promise} Promise result.
      * @since 1.110.0
      * @private
+     * @ui5-restricted SAP internally public
      */
-
     MessageBroker.prototype.getAcceptedOrigins = function () {
         return MessageBrokerEngine.getAcceptedOrigins();
     };

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

@@ -4,7 +4,7 @@
  * @fileOverview The Unified Shell's message service.
  * This is a private service replacing the depercated Message service, as the functionality is used thoughout the ushell.
  *
- * @version 1.140.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/base/Log",
@@ -200,7 +200,7 @@ sap.ui.define([
 
                 const bSuccessful = document.execCommand("copy");
                 sMessageToastText = bSuccessful ? "CopyWasSuccessful" : "CopyWasNotSuccessful";
-            } catch (oException) {
+            } catch (oError) {
                 sMessageToastText = "CopyWasNotSuccessful";
             } finally {
                 this.buildAndSendMessageToast(resources.i18n.getText(sMessageToastText));

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

@@ -109,7 +109,7 @@ sap.ui.define([
         this._resolveHashFragmentClientSide = function (sHashFragment) {
             const oHashValidationResult = this._validateHashFragment(sHashFragment);
             if (!oHashValidationResult.success) {
-                return new jQuery.Deferred().reject(`${sHashFragment} is not a valid hash fragment`).promise();
+                return new jQuery.Deferred().reject(new Error(`${sHashFragment} is not a valid hash fragment`)).promise();
             }
 
             const sFragmentNoHash = oHashValidationResult.hashFragmentWithoutHash;
@@ -716,7 +716,7 @@ sap.ui.define([
                 "sap.ushell.services.NavTargetResolutionInternal"
             );
 
-            return oDeferred.reject("Cannot execute getDistinctSemanticObjects").promise();
+            return oDeferred.reject(new Error("Cannot execute getDistinctSemanticObjects")).promise();
         };
 
         this._getLinksClientSide = function (oArgs) {
@@ -1229,14 +1229,14 @@ sap.ui.define([
                         // eslint-disable-next-line max-len
                         Log.info(`NavTargetResolutionInternal: No configured app for ${sHashFragment} found ( local storage or url params sap-ushell-test-local1-url  sap-ushell-test-local1-additionalInfo  not supplied? `);
                         Log.info("NavTargetResolutionInternal: Defaulting to config app ...\n");
-                        oDeferred.reject("URL is not resolvable");
+                        oDeferred.reject(new Error("URL is not resolvable"));
                         return oDeferred.promise();
                     }
                     oLocal.url = localURL(oLocal.url);
                     res = oLocal;
                 }
                 if (res.url === undefined) {
-                    oDeferred.reject("URL is not resolvable");
+                    oDeferred.reject(new Error("URL is not resolvable"));
                     return oDeferred.promise();
                 }
                 // eslint-disable-next-line max-len

package/src/main/js/sap/ushell/services/Navigation/compatibility.js

@@ -4,7 +4,7 @@
  * compatible with the CrossApplicationNavigation service.
  * This shall only be used for the AppRuntime to enable 1.x inner shell running in 2.x host.
  *
- * @version 1.140.0
+ * @version 1.141.0
  */
 
 sap.ui.define([
@@ -136,7 +136,6 @@ sap.ui.define([
      */
     compatibility.getSemanticObjectLinks = async function (vSemanticObjectOrMultipleArgs, oParameters, bIgnoreFormFactor, oComponent, sAppStateKey, bCompactIntents) {
         const Navigation = await Container.getServiceAsync("Navigation");
-        // todo: [FLPCOREANDUX-10024] check whether this is still true
         // require lazy to avoid circular dependency
         const [ AppLifeCycleAI ] = await ushellUtils.requireAsync(["sap/ushell/appIntegration/AppLifeCycle"]);
 

package/src/main/js/sap/ushell/services/Navigation/utils.js

@@ -2,7 +2,7 @@
 /**
  * @fileOverview Navigation utility functions
  *
- * @version 1.140.0
+ * @version 1.141.0
  */
 
 sap.ui.define([
@@ -197,10 +197,10 @@ sap.ui.define([
     navigationUtils._safeParseToObject = function (sObject) {
         try {
             return JSON.parse(sObject);
-        } catch (e) {
+        } catch (oError) {
             Log.error(
                 "Cannot parse the given string to object",
-                sObject
+                oError
             );
         }
 

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

@@ -5,7 +5,7 @@
  * This file exposes an API to perform (invoke) Navigation for applications.
  * It exposes interfaces to perform a hash change and trigger a navigation.
  *
- * @version 1.140.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/base/Log",
@@ -122,7 +122,7 @@ sap.ui.define([
          *   to be a valid intent, i.e. in the format <code>"#SO-Action?P1=a&P2=x&/route?RPV=1"</code>.
          *  The generic syntax consists of the semantic object, the action and an optional part:
          * <pre>Intent = "#" semanticObject "-" action ["?" intentParameters "&/" innerAppRoute + "?" + innerAppRouteParameters]</pre>
-         * The intent compries of the fthe following parts:
+         * The intent comprises of the following parts:
          * <ul>
          *  <li>semanticObject:
          * Semantic object as defined in an app launcher tile.
@@ -1026,7 +1026,7 @@ sap.ui.define([
          */
         this.isUrlSupported = async function (sUrl) {
             if (typeof sUrl !== "string") {
-                return Promise.reject();
+                throw new Error("Url is not supported: It is not a string.");
             }
 
             if (UrlParsing.isIntentUrl(sUrl)) {
@@ -1038,7 +1038,7 @@ sap.ui.define([
                 };
                 const oResult = await this.isNavigationSupported([oTarget]);
                 if (!oResult[0].supported) {
-                    return Promise.reject();
+                    throw new Error("Url is not supported: No matching intent was found.");
                 }
             }
         };
@@ -1060,7 +1060,7 @@ sap.ui.define([
          */
         this.createEmptyAppState = async function (oAppComponent, bTransientEnforced, sPersistencyMethod, oPersistencySettings) {
             if (!BaseObject.isObjectA(oAppComponent, "sap.ui.core.UIComponent")) {
-                return Promise.reject("The passed oAppComponent must be a UI5 Component.");
+                throw new Error("The passed oAppComponent must be a UI5 Component.");
             }
 
             const AppState = await Container.getServiceAsync("AppState");

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

@@ -9,12 +9,17 @@
  *
  * Configured with the ClientSideTargetResolutionAdapter.
  *
- * @version 1.140.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/ushell/resources",
-    "sap/ushell/utils"
-], (resources, ushellUtils) => {
+    "sap/ushell/utils",
+    "sap/ushell/utils/LaunchpadError"
+], (
+    ushellResources,
+    ushellUtils,
+    LaunchpadError
+) => {
     "use strict";
 
     /**
@@ -82,13 +87,17 @@ sap.ui.define([
                         inbounds: aInbounds
                     });
                 })
-                .catch((error) => {
-                    const oError = {
-                        component: this.S_COMPONENT_NAME,
-                        description: resources.i18n.getText("NavigationDataProvider.CannotLoadData"),
-                        detail: error
-                    };
-                    reject(oError);
+                .catch((oError) => {
+                    const oEnhancedError = new LaunchpadError(
+                        oError.message,
+                        {
+                            component: this.S_COMPONENT_NAME,
+                            description: ushellResources.i18n.getText("NavigationDataProvider.CannotLoadData"),
+                            detail: oError
+                        },
+                        oError
+                    );
+                    reject(oEnhancedError);
                 });
         });
     };