@openui5/sap.ui.core 1.97.1 → 1.100.0

package/src/sap/ui/model/odata/v4/ODataBinding.js

@@ -165,6 +165,19 @@ sap.ui.define([
 						throw new Error("Unsupported operation mode: " + vValue);
 					}
 					break;
+				case "$$getKeepAliveContext":
+					if (that.isRelative() && !mParameters.$$ownRequest) {
+						throw new Error(
+							"$$getKeepAliveContext requires $$ownRequest in a relative binding");
+					}
+					["$$aggregation", "$$canonicalPath", "$$sharedRequest"]
+						.forEach(function (sForbidden) {
+							if (sForbidden in mParameters) {
+								throw new Error("Cannot combine $$getKeepAliveContext and "
+									+ sForbidden);
+							}
+						});
+					// falls through
 				case "$$canonicalPath":
 				case "$$noPatch":
 				case "$$ownRequest":
@@ -214,15 +227,13 @@ sap.ui.define([
 	 */
 	// @override sap.ui.model.Binding#checkUpdate
 	ODataBinding.prototype.checkUpdate = function (bForceUpdate) {
-		var that = this;
-
 		if (arguments.length > 1) {
 			throw new Error("Only the parameter bForceUpdate is supported");
 		}
 
-		this.checkUpdateInternal(bForceUpdate).catch(function (oError) {
-			that.oModel.reportError("Failed to update " + that, sClassName, oError);
-		});
+		this.checkUpdateInternal(bForceUpdate).catch(this.oModel.getReporter());
+		// do not rethrow, ManagedObject doesn't react on this either
+		// throwing an error would cause "Uncaught (in promise)" in Chrome
 	};
 
 	/**
@@ -234,7 +245,7 @@ sap.ui.define([
 	 *   Whether the change event is fired in any case (only allowed for property bindings)
 	 * @returns {sap.ui.base.SyncPromise}
 	 *   A promise resolving without a defined result when the check is finished, or rejecting in
-	 *   case of an error (e.g. thrown by the change event handler of a control)
+	 *   case of an error
 	 * @throws {Error} If called with illegal parameters
 	 *
 	 * @abstract
@@ -255,17 +266,18 @@ sap.ui.define([
 	 *   The resource path
 	 * @param {sap.ui.model.Context} [oContext]
 	 *   The context instance to be used, undefined for absolute bindings
-	 * @param {boolean} [bOldCacheReadOnly]
-	 *   Whether the old cache is read-only and must be kept intact - not reset and reused!
+	 * @param {boolean} [bKeepCreated]
+	 *   Whether created persisted elements shall be kept in place
 	 * @param {sap.ui.model.odata.v4.lib._Cache} [oOldCache]
 	 *   The old cache, in case it may be reused
 	 * @returns {sap.ui.model.odata.v4.lib._Cache}
-	 *   The cache
+	 *   The cache or <code>null</code> if the binding is relative and the given context is
+	 *   transient
 	 *
 	 * @private
 	 */
 	ODataBinding.prototype.createAndSetCache = function (mQueryOptions, sResourcePath, oContext,
-			bOldCacheReadOnly, oOldCache) {
+			bKeepCreated, oOldCache) {
 		var oCache, sDeepResourcePath, iGeneration;
 
 		this.mCacheQueryOptions = Object.assign({}, this.oModel.mUriParameters, mQueryOptions);
@@ -287,9 +299,9 @@ sap.ui.define([
 			if (oCache && oCache.$generation >= iGeneration) {
 				oCache.setActive(true);
 			} else {
-				sDeepResourcePath = _Helper.buildPath(oContext.getPath(), this.sPath).slice(1);
+				sDeepResourcePath = this.oModel.resolve(this.sPath, oContext).slice(1);
 				oCache = this.doCreateCache(sResourcePath, this.mCacheQueryOptions, oContext,
-					sDeepResourcePath, bOldCacheReadOnly, oOldCache);
+					sDeepResourcePath, bKeepCreated, oOldCache);
 				if (!(this.mParameters && this.mParameters.$$sharedRequest)) {
 					this.mCacheByResourcePath = this.mCacheByResourcePath || {};
 					this.mCacheByResourcePath[sResourcePath] = oCache;
@@ -299,15 +311,13 @@ sap.ui.define([
 			}
 		} else { // absolute binding
 			oCache = this.doCreateCache(sResourcePath, this.mCacheQueryOptions, undefined,
-				undefined, bOldCacheReadOnly, oOldCache);
+				undefined, bKeepCreated, oOldCache);
 		}
-		if (oOldCache !== oCache) {
-			if (oOldCache) {
-				oOldCache.setActive(false);
-			}
-			if (this.mLateQueryOptions) {
-				oCache.setLateQueryOptions(this.mLateQueryOptions);
-			}
+		if (oOldCache && oOldCache !== oCache) {
+			oOldCache.setActive(false);
+		}
+		if (this.mLateQueryOptions) {
+			oCache.setLateQueryOptions(this.mLateQueryOptions);
 		}
 		this.oCache = oCache;
 
@@ -348,8 +358,8 @@ sap.ui.define([
 	 *   The context instance to be used, must be <code>undefined</code> for absolute bindings
 	 * @param {string} [sDeepResourcePath=sResourcePath]
 	 *   The deep resource path to be used to build the target path for bound messages
-	 * @param {boolean} [bOldCacheReadOnly]
-	 *   Whether the old cache is read-only and must be kept intact - not reset and reused!
+	 * @param {boolean} [bKeepCreated]
+	 *   Whether created persisted elements shall be kept in place
 	 * @param {sap.ui.model.odata.v4.lib._Cache} [oOldCache]
 	 *   The old cache, in case it may be reused
 	 * @returns {sap.ui.model.odata.v4.lib._Cache}
@@ -402,9 +412,8 @@ sap.ui.define([
 	 * @param {boolean} [bKeepQueryOptions]
 	 *   Whether to keep existing (late) query options and not to run auto-$expand/$select again
 	 *   (cannot be combined with <code>bIgnoreParentCache</code>!)
-	 * @param {boolean} [bKeepCacheOnError]
-	 *   If <code>true</code>, the binding data remains unchanged if the refresh fails. This implies
-	 *   that the old cache must be kept intact - not reset and reused!
+	 * @param {boolean} [bKeepCreated]
+	 *   Whether created persisted elements shall be kept in place
 	 * @throws {Error}
 	 *   If auto-$expand/$select is still running and query options shall be kept (this case is just
 	 *   not yet implemented and should not be needed)
@@ -412,7 +421,7 @@ sap.ui.define([
 	 * @private
 	 */
 	ODataBinding.prototype.fetchCache = function (oContext, bIgnoreParentCache, bKeepQueryOptions,
-		bKeepCacheOnError) {
+		bKeepCreated) {
 		var oCache = this.oCache,
 			oCallToken = {
 				// propagate old cache from first call of fetchCache to the latest call
@@ -435,10 +444,10 @@ sap.ui.define([
 		this.oCache = undefined;
 		this.oFetchCacheCallToken = oCallToken;
 		if (bKeepQueryOptions) {
-			// asynchronously re-create an equivalent cache
+			// asynchronously re-create an equivalent cache, but skip auto-$expand/$select
 			this.oCachePromise = SyncPromise.resolve(Promise.resolve()).then(function () {
 				return that.createAndSetCache(that.mCacheQueryOptions, oCache.getResourcePath(),
-					oContext, bKeepCacheOnError, oCache);
+					oContext, bKeepCreated, oCache);
 			});
 			return;
 		}
@@ -465,7 +474,7 @@ sap.ui.define([
 						throw oError;
 					}
 					return that.createAndSetCache(mQueryOptions, sResourcePath, oContext,
-						bKeepCacheOnError, oCallToken.oOldCache);
+						bKeepCreated, oCallToken.oOldCache);
 				});
 			}
 			that.oCache = null;
@@ -534,7 +543,7 @@ sap.ui.define([
 		// With $$aggregation, no auto-$expand/$select is needed
 		oQueryOptionsPromise = this.doFetchQueryOptions(oContext);
 		if (this.oModel.bAutoExpandSelect && this.aChildCanUseCachePromises
-				&& !(this.mParameters && this.mParameters.$$aggregation)) {
+				&& !this.mParameters.$$aggregation) {
 			// For auto-$expand/$select, wait for query options of dependent bindings:
 			// Promise.resolve() ensures all dependent bindings are created and have sent their
 			// query options promise to this binding via fetchIfChildCanUseCache.
@@ -553,7 +562,7 @@ sap.ui.define([
 		}
 
 		// parent cache is ignored or (quasi-)absolute binding
-		if (bIgnoreParentCache || !this.bRelative || !oContext.fetchValue)  {
+		if (bIgnoreParentCache || !this.bRelative || !oContext.fetchValue) {
 			// the binding shall create its own cache
 			return wrapQueryOptions(oQueryOptionsPromise);
 		}
@@ -568,7 +577,8 @@ sap.ui.define([
 				return wrapQueryOptions(oQueryOptionsPromise);
 			}
 			return oContext.getBinding()
-				.fetchIfChildCanUseCache(oContext, that.sPath, oQueryOptionsPromise)
+				.fetchIfChildCanUseCache(oContext, that.sPath, oQueryOptionsPromise,
+					!this.mParameters) // duck typing for property binding
 				.then(function (sReducedPath) {
 					return wrapQueryOptions(sReducedPath ? undefined : oQueryOptionsPromise,
 						sReducedPath);
@@ -679,7 +689,7 @@ sap.ui.define([
 	 *
 	 * @param {string} sPath
 	 *   A path (absolute or relative to this binding)
-	 * @returns {string}
+	 * @returns {string|undefined}
 	 *   The given path, if it is already relative; otherwise the path relative to the binding's
 	 *   resolved path or return value context path; <code>undefined</code> if the path does not
 	 *   start with either of these paths.
@@ -707,7 +717,7 @@ sap.ui.define([
 	 * Returns the "strongest" change reason that {@link #resume} would fire for this binding or any
 	 * of its dependents.
 	 *
-	 * @returns {sap.ui.model.ChangeReason}
+	 * @returns {sap.ui.model.ChangeReason|undefined}
 	 *   The "strongest" change reason, or <code>undefined</code>
 	 *
 	 * @private
@@ -732,7 +742,7 @@ sap.ui.define([
 	/**
 	 * Returns a promise which resolves as soon as this binding is resumed.
 	 *
-	 * @returns {sap.ui.base.SyncPromise}
+	 * @returns {sap.ui.base.SyncPromise|undefined}
 	 *   This binding's current promise for {@link sap.ui.model.odata.v4.ODataParentBinding#resume},
 	 *   or <code>undefined</code> in case it is not currently suspended.
 	 *
@@ -747,7 +757,8 @@ sap.ui.define([
 	 * Returns the root binding of this binding's hierarchy, see binding
 	 * {@link topic:54e0ddf695af4a6c978472cecb01c64d Initialization and Read Requests}.
 	 *
-	 * @returns {sap.ui.model.odata.v4.ODataContextBinding|sap.ui.model.odata.v4.ODataListBinding|sap.ui.model.odata.v4.ODataPropertyBinding}
+	 * @returns {sap.ui.model.odata.v4.ODataContextBinding|sap.ui.model.odata.v4.ODataListBinding|
+	 *      sap.ui.model.odata.v4.ODataPropertyBinding|undefined}
 	 *   The root binding or <code>undefined</code> if this binding is unresolved (see
 	 *   {@link sap.ui.model.Binding#isResolved}).
 	 *
@@ -814,7 +825,8 @@ sap.ui.define([
 	 * changes or created entities which have not been sent successfully to the server. This
 	 * function does not take into account the deletion of entities (see
 	 * {@link sap.ui.model.odata.v4.Context#delete}) and the execution of OData operations
-	 * (see {@link sap.ui.model.odata.v4.ODataContextBinding#execute}).
+	 * (see {@link sap.ui.model.odata.v4.ODataContextBinding#execute}). Since 1.98.0,
+	 * {@link sap.ui.model.odata.v4.Context#isInactive inactive} contexts are ignored.
 	 *
 	 * Note: If this binding is relative, its data is cached separately for each parent context
 	 * path. This method returns <code>true</code> if there are pending changes for the current
@@ -823,11 +835,16 @@ sap.ui.define([
 	 *
 	 * @param {boolean} [bIgnoreKeptAlive]
 	 *   Whether to ignore changes which will not be lost by APIs like
-	 *  {@link sap.ui.model.odata.v4.ODataListBinding#changeParameters changeParameters},
-	 *  {@link sap.ui.model.odata.v4.ODataListBinding#filter filter},
-	 *  {@link sap.ui.model.odata.v4.ODataListBinding#sort sort}, or
-	 *  {@link sap.ui.model.odata.v4.ODataListBinding#suspend suspend} because they relate to a
-	 *  {@link sap.ui.model.odata.v4.Context#setKeepAlive kept-alive} context of this binding.
+	 *   {@link sap.ui.model.odata.v4.ODataListBinding#changeParameters changeParameters},
+	 *   {@link sap.ui.model.odata.v4.ODataListBinding#filter filter},
+	 *   {@link sap.ui.model.odata.v4.ODataListBinding#refresh refresh} (since 1.100.0),
+	 *   {@link sap.ui.model.odata.v4.ODataListBinding#sort sort}, or
+	 *   {@link sap.ui.model.odata.v4.ODataListBinding#suspend suspend} because they relate to a
+	 *   {@link sap.ui.model.odata.v4.Context#setKeepAlive kept-alive} context of this binding
+	 *   (since 1.97.0). Since 1.98.0, {@link sap.ui.model.odata.v4.Context#isTransient transient}
+	 *   contexts of a {@link #getRootBinding root binding} are treated as kept-alive by this flag.
+	 *   Since 1.99.0, the same happens for bindings using the <code>$$ownRequest</code> parameter
+	 *   (see {@link sap.ui.model.odata.v4.ODataModel#bindList}).
 	 * @returns {boolean}
 	 *   <code>true</code> if the binding is resolved and has pending changes
 	 *
@@ -855,8 +872,9 @@ sap.ui.define([
 	 * @private
 	 */
 	ODataBinding.prototype.hasPendingChangesForPath = function (sPath, bIgnoreKeptAlive) {
-		return this.withCache(function (oCache, sCachePath) {
-				return oCache.hasPendingChangesForPath(sCachePath, bIgnoreKeptAlive);
+		return this.withCache(function (oCache, sCachePath, oBinding) {
+				return oCache.hasPendingChangesForPath(sCachePath, bIgnoreKeptAlive,
+					bIgnoreKeptAlive && (oBinding.isRoot() || oBinding.mParameters.$$ownRequest));
 			}, sPath, true).unwrap();
 	};
 
@@ -888,11 +906,11 @@ sap.ui.define([
 	/**
 	 * Returns whether any dependent binding of this binding has pending changes
 	 *
-	 * @returns {boolean}
-	 *   <code>true</code> if this binding has pending changes
 	 * @param {boolean} [bIgnoreKeptAlive]
 	 *   Whether to ignore changes which will not be lost by APIs like sort or filter because they
 	 *   relate to a context which is kept alive.
+	 * @returns {boolean}
+	 *   <code>true</code> if this binding has pending changes
 	 *
 	 * @abstract
 	 * @function
@@ -982,8 +1000,8 @@ sap.ui.define([
 	 * the last call determines the binding's data; it is <b>independent</b> of the order of calls
 	 * to {@link sap.ui.model.odata.v4.ODataModel#submitBatch} with the given group ID.
 	 *
-	 * If there are pending changes, an error is thrown. Use {@link #hasPendingChanges} to check if
-	 * there are pending changes. If there are changes, call
+	 * If there are pending changes that cannot be ignored, an error is thrown. Use
+	 * {@link #hasPendingChanges} to check if there are such pending changes. If there are, call
 	 * {@link sap.ui.model.odata.v4.ODataModel#submitBatch} to submit the changes or
 	 * {@link sap.ui.model.odata.v4.ODataModel#resetChanges} to reset the changes before calling
 	 * {@link #refresh}.
@@ -998,10 +1016,18 @@ sap.ui.define([
 	 *
 	 *   Valid values are <code>undefined</code>, '$auto', '$auto.*', '$direct' or application group
 	 *   IDs as specified in {@link sap.ui.model.odata.v4.ODataModel}.
-	 * @throws {Error}
-	 *   If the given group ID is invalid, the binding has pending changes, refresh on this
-	 *   binding is not supported, a group ID different from the binding's group ID is specified
-	 *   for a suspended binding, or a value of type boolean is given.
+	 * @throws {Error} If
+	 *   <ul>
+	 *     <li> the given group ID is invalid,
+	 *     <li> there are pending changes that cannot be ignored,
+	 *     <li> refresh on this binding is not supported,
+	 *     <li> a group ID different from the binding's group ID is specified for a suspended
+	 *       binding,
+	 *     <li> or a value of type boolean is given.
+	 *   </ul> Since 1.100.0, pending changes are ignored if they relate to a
+	 *   {@link sap.ui.model.odata.v4.Context#setKeepAlive kept-alive} context of this binding, and
+	 *   {@link sap.ui.model.odata.v4.Context#isTransient transient} contexts of a
+	 *   {@link #getRootBinding root binding} do not count as pending changes.
 	 *
 	 * @public
 	 * @see sap.ui.model.Binding#refresh
@@ -1044,6 +1070,24 @@ sap.ui.define([
 	 * @private
 	 */
 
+	/**
+	 * Refreshes the binding; expects it to be suspended.
+	 *
+	 * @param {string} sGroupId
+	 *   The group ID to be used for the refresh
+	 * @throws {Error}
+	 *   If a group ID different from the binding's group ID is given
+
+	 * @private
+	 */
+	ODataBinding.prototype.refreshSuspended = function (sGroupId) {
+		if (sGroupId && sGroupId !== this.getGroupId()) {
+			throw new Error(this + ": Cannot refresh a suspended binding with group ID '"
+				+ sGroupId + "' (own group ID is '" + this.getGroupId() + "')");
+		}
+		this.setResumeChangeReason(ChangeReason.Refresh);
+	};
+
 	/**
 	 * Remove this binding's caches and non-persistent messages. The binding's active cache removes
 	 * only its own messages. Inactive caches with a deep resource path starting with the given
@@ -1084,7 +1128,7 @@ sap.ui.define([
 	 *   The effective group ID
 	 * @param {string[]} aAbsolutePaths
 	 *   The absolute paths to request side effects for
-	 * @returns {sap.ui.base.SyncPromise}
+	 * @returns {sap.ui.base.SyncPromise|undefined}
 	 *   A promise resolving without a defined result, or rejecting with an error if loading of side
 	 *   effects fails, or <code>undefined</code> if there is nothing to do
 	 *
@@ -1133,7 +1177,7 @@ sap.ui.define([
 		if (!this.isRoot()) {
 			throw new Error("Refresh on this binding is not supported");
 		}
-		if (this.hasPendingChanges()) {
+		if (this.hasPendingChanges(true)) {
 			throw new Error("Cannot refresh due to pending changes");
 		}
 		this.oModel.checkGroupId(sGroupId);
@@ -1235,7 +1279,7 @@ sap.ui.define([
 	 * @since 1.37.0
 	 */
 	ODataBinding.prototype.toString = function () {
-		return this.getMetadata().getName() + ": " + (this.bRelative  ? this.oContext + "|" : "")
+		return this.getMetadata().getName() + ": " + (this.bRelative ? this.oContext + "|" : "")
 			+ this.sPath;
 	};