@openui5/sap.ui.core 1.99.0 → 1.100.0

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

@@ -52,6 +52,8 @@ sap.ui.define([
 		// system query options allowed within a $expand query option
 		aExpandQueryOptions = ["$count", "$expand", "$filter", "$levels", "$orderby", "$search",
 			"$select"],
+		// binding-specific parameters allowed in getKeepAliveContext
+		aGetKeepAliveParameters = ["$$groupId", "$$patchWithoutSideEffects", "$$updateGroupId"],
 		rGroupID = /^(\$auto(\.\w+)?|\$direct|\w+)$/,
 		MessageType = coreLibrary.MessageType,
 		aMessageTypes = [
@@ -210,7 +212,7 @@ sap.ui.define([
 		 * @extends sap.ui.model.Model
 		 * @public
 		 * @since 1.37.0
-		 * @version 1.99.0
+		 * @version 1.100.0
 		 */
 		ODataModel = Model.extend("sap.ui.model.odata.v4.ODataModel",
 			/** @lends sap.ui.model.odata.v4.ODataModel.prototype */{
@@ -331,6 +333,8 @@ sap.ui.define([
 				that.fireEvent("sessionTimeout");
 			},
 			getGroupProperty : this.getGroupProperty.bind(this),
+			getOptimisticBatchEnabler : this.getOptimisticBatchEnabler.bind(this),
+			getReporter : this.getReporter.bind(this),
 			onCreateGroup : function (sGroupId) {
 				if (that.isAutoGroup(sGroupId)) {
 					that.addPrerenderingTask(that._submitBatch.bind(that, sGroupId, true));
@@ -342,12 +346,16 @@ sap.ui.define([
 		this.oRequestor = _Requestor.create(this.sServiceUrl, this.oInterface, this.mHeaders,
 			mUriParameters, sODataVersion);
 		this.changeHttpHeaders(mParameters.httpHeaders);
-		if (mParameters.earlyRequests) {
+		this.bEarlyRequests = mParameters.earlyRequests;
+		if (this.bEarlyRequests) {
 			this.oMetaModel.fetchEntityContainer(true);
 			this.initializeSecurityToken();
+			this.oRequestor.sendOptimisticBatch();
 		}
 
 		this.aAllBindings = [];
+		// The bindings holding keep-alive contexts without a $$getKeepAlive binding
+		this.mKeepAliveBindingsByPath = {};
 		this.mSupportedBindingModes = {
 			OneTime : true,
 			OneWay : true
@@ -359,6 +367,7 @@ sap.ui.define([
 			this.mSupportedBindingModes.TwoWay = true;
 		}
 		this.aPrerenderingTasks = null; // @see #addPrerenderingTask
+		this.fnOptimisticBatchEnabler = null;
 	}
 
 	/**
@@ -660,7 +669,10 @@ sap.ui.define([
 	 *   <code>true</code> is allowed.
 	 * @param {boolean} [mParameters.$$getKeepAliveContext]
 	 *   Whether this binding is considered for a match when {@link #getKeepAliveContext} is called;
-	 *   only the value <code>true</code> is allowed. Supported since 1.99.0
+	 *   only the value <code>true</code> is allowed. Must not be combined with <code>$apply</code>,
+	 *   <code>$$aggregation</code>, <code>$$canonicalPath</code>, or <code>$$sharedRequest</code>.
+	 *   If the binding is relative, <code>$$ownRequest</code> must be set as well.
+	 *   Supported since 1.99.0
 	 * @param {string} [mParameters.$$groupId]
 	 *   The group ID to be used for <b>read</b> requests triggered by this binding; if not
 	 *   specified, either the parent binding's group ID (if the binding is relative) or the
@@ -1498,53 +1510,111 @@ sap.ui.define([
 
 	/**
 	 * Returns a context with the given path belonging to a matching list binding that has been
-	 * marked with <code>$$getKeepAliveContext</code> (see {@link #bindList}). If such a context
-	 * exists, it is returned and kept alive (see
-	 * {@link sap.ui.model.odata.v4.Context#setKeepAlive}).
+	 * marked with <code>$$getKeepAliveContext</code> (see {@link #bindList}). If such a matching
+	 * binding can be found, a context is returned and kept alive (see
+	 * {@link sap.ui.model.odata.v4.ODataListBinding#getKeepAliveContext}). Since 1.100.0 a
+	 * temporary binding is used if no such binding could be found. If such a binding is created or
+	 * resolved later, the context and its data are transferred to it, and the temporary binding is
+	 * destroyed again.
+	 *
+	 * A <code>$$getKeepAliveContext</code> binding matches if its resolved binding path is the
+	 * collection path of the context. If the context is created using a temporary binding and the
+	 * parameters of the <code>$$getKeepAliveContext</code> binding differ from the given
+	 * <code>mParameters</code> (except <code>$$groupId</code> which is especially used for the
+	 * context), that binding later runs into an error when trying to read data.
+	 *
+	 * <b>Note</b>: The context received by this function may change its
+	 * {@link sap.ui.model.odata.v4.Context#getBinding binding} during its lifetime.
 	 *
 	 * @param {string} sPath
 	 *   A list context path to an entity
 	 * @param {boolean} [bRequestMessages]
 	 *   Whether to request messages for the context's entity
+	 * @param {object} [mParameters]
+	 *   Parameters for the context or the temporary binding; supported since 1.100.0. All custom
+	 *   query options and the following binding-specific parameters for a list binding may be given
+	 *   (see {@link #bindList} for details).
+	 * @param {string} [mParameters.$$groupId]
+	 *   The group ID used for read requests for the context's entity or its properties. If not
+	 *   given, the model's {@link #getGroupId group ID} is used
+	 * @param {boolean} [mParameters.$$patchWithoutSideEffects]
+	 *   Whether implicit loading of side effects via PATCH requests is switched off
+	 * @param {string} [mParameters.$$updateGroupId]
+	 *   The group ID to be used for <b>update</b> requests triggered by the context's binding
 	 * @returns {sap.ui.model.odata.v4.Context|undefined}
-	 *   The context, or <code>undefined</code> if such a binding does not exist or does not have
-	 *   such a context
+	 *   The context, or <code>undefined</code> if a binding with a suspended root binding matches
+	 *   and has no context with that path.
 	 * @throws {Error} If
 	 *   <ul>
 	 *     <li> the model does not use the <code>autoExpandSelect</code> parameter,
+	 *     <li> an invalid parameter was supplied,
 	 *     <li> the path is not a list context path to an entity,
 	 *     <li> multiple list bindings with <code>$$getKeepAliveContext</code> match, or
 	 *     <li> {@link sap.ui.model.odata.v4.Context#setKeepAlive} fails
 	 *   </ul>
 	 *
 	 * @public
-	 * @see sap.ui.model.odata.v4.ODataListBinding#getKeepAliveContext
 	 * @since 1.99.0
 	 */
-	ODataModel.prototype.getKeepAliveContext = function (sPath, bRequestMessages) {
-		var aListBindings,
-			sListPath,
-			iPredicateIndex = sPath.indexOf("(", sPath.lastIndexOf("/")),
-			that = this;
+	ODataModel.prototype.getKeepAliveContext = function (sPath, bRequestMessages, mParameters) {
+		var oListBinding,
+			aListBindings,
+			sListPath;
 
 		if (!this.bAutoExpandSelect) {
 			throw new Error("Missing parameter autoExpandSelect");
 		}
-		if (sPath[0] !== "/" || iPredicateIndex < 0 || !sPath.endsWith(")")) {
+		if (sPath[0] !== "/") {
 			throw new Error("Not a list context path to an entity: " + sPath);
 		}
-		sListPath = sPath.slice(0, iPredicateIndex);
-		aListBindings = this.aAllBindings.filter(function (oBinding) {
-			return oBinding.mParameters && oBinding.mParameters.$$getKeepAliveContext
-				&& that.resolve(oBinding.getPath(), oBinding.getContext()) === sListPath;
+		mParameters = mParameters || {};
+		// Only excess parameters are rejected here; the correctness is checked by ODLB
+		Object.keys(mParameters).forEach(function (sParameter) {
+			if (sParameter.startsWith("sap-") && !sParameter.startsWith("sap-valid-")
+					|| sParameter[0] === "$" && !aGetKeepAliveParameters.includes(sParameter)) {
+				throw new Error("Invalid parameter: " + sParameter);
+			}
 		});
-
-		if (aListBindings.length > 1) {
-			throw new Error("Multiple bindings with $$getKeepAliveContext for: " + sPath);
+		sListPath = sPath.slice(0, this.getPredicateIndex(sPath));
+		oListBinding = this.mKeepAliveBindingsByPath[sListPath];
+		if (!oListBinding) {
+			aListBindings = this.aAllBindings.filter(function (oBinding) {
+				if (oBinding.mParameters && oBinding.mParameters.$$getKeepAliveContext) {
+					oBinding.removeCachesAndMessages(sListPath.slice(1), true);
+				}
+				return oBinding.isKeepAliveBindingFor && oBinding.isKeepAliveBindingFor(sListPath);
+			});
+			if (aListBindings.length > 1) {
+				throw new Error("Multiple bindings with $$getKeepAliveContext for: " + sPath);
+			}
+			oListBinding = aListBindings[0];
+			if (!oListBinding) {
+				oListBinding = this.bindList(sListPath, undefined, undefined, undefined,
+					mParameters);
+				this.mKeepAliveBindingsByPath[sListPath] = oListBinding;
+			}
 		}
-		if (aListBindings.length) {
-			return aListBindings[0].getKeepAliveContext(sPath, bRequestMessages);
+
+		return oListBinding.getKeepAliveContext(sPath, bRequestMessages, mParameters.$$groupId);
+	};
+
+	/**
+	 * Returns the index of the key predicate in the last segment of the given path.
+	 *
+	 * @param {string} sPath - The path
+	 * @returns {number} The index of the key predicate
+	 * @throws {Error} If the last segment contains no key predicate
+	 *
+	 * @private
+	 */
+	ODataModel.prototype.getPredicateIndex = function (sPath) {
+		var iPredicateIndex = sPath.indexOf("(", sPath.lastIndexOf("/"));
+
+		if (iPredicateIndex < 0 || !sPath.endsWith(")")) {
+			throw new Error("Not a list context path to an entity: " + sPath);
 		}
+
+		return iPredicateIndex;
 	};
 
 	/**
@@ -1755,6 +1825,24 @@ sap.ui.define([
 		});
 	};
 
+	/**
+	 * Returns and releases the temporary keep-alive binding for the given path.
+	 *
+	 * @param {string} sPath - The path
+	 * @returns {sap.ui.model.odata.v4.ODataListBinding|undefined}
+	 *   The binding or <code>undefined</code> if there is none
+	 *
+	 * @private
+	 */
+	ODataModel.prototype.releaseKeepAliveBinding = function (sPath) {
+		var oBinding = this.mKeepAliveBindingsByPath[sPath];
+
+		if (oBinding) {
+			delete this.mKeepAliveBindingsByPath[sPath];
+			return oBinding;
+		}
+	};
+
 	/**
 	 * Reports a technical error by firing a <code>messageChange</code> event with a new message and
 	 * logging the error to the console. Takes care that the error is only reported once via the
@@ -2032,6 +2120,79 @@ sap.ui.define([
 		throw new Error("Unsupported operation: v4.ODataModel#setLegacySyntax");
 	};
 
+	/**
+	 * Getter for the optimistic batch enabler callback function; see
+	 * {@link sap.ui.model.odata.v4.ODataModel#setOptimisticBatchEnabler}.
+	 *
+	 *
+	 * @returns {function(string)}
+	 *   The optimistic batch enabler callback function
+	 *
+	 * @experimental As of version 1.100.0
+	 * @private
+	 * @ui5-restricted sap.fe
+	 */
+	ODataModel.prototype.getOptimisticBatchEnabler = function () {
+		return this.fnOptimisticBatchEnabler;
+	};
+
+	/**
+	 * Setter for the optimistic batch enabler callback function. Setting this callback activates
+	 * the optimistic batch feature. Via the callback the optimistic batch behavior can be enabled
+	 * or disabled by returning either a boolean or a promise resolving with a boolean.
+	 * As its first argument the callback gets the <code>window.location.href</code> at the point in
+	 * time when the OData model is instantiated.
+	 *
+	 * If the callback returns or resolves with <code>true</code>, the OData model remembers the
+	 * first sent $batch request. With the next model instantiation for the same key, this
+	 * remembered $batch request will be sent at the earliest point in time in order to have the
+	 * response already available when the first $batch request is triggered from the UI or the
+	 * binding. If the returned promise is rejected, this error will be reported and the optimistic
+	 * batch will be disabled.
+	 *
+	 * There are several preconditions on the usage of this API:
+	 * <ul>
+	 *   <li> Optimistic batch handling requires the "earlyRequests" model parameter; see
+	 *     {@link sap.ui.model.odata.v4.ODataModel#constructor},
+	 *   <li> the setter has to be called before the first $batch request is sent,
+	 *   <li> the setter may only be called once for an OData model,
+	 *   <li> the callback has to return a boolean, or a <code>Promise</code> resolving with a
+	 *     boolean
+	 *   <li> the callback is not called if the first $batch request is modifying, means that it
+	 *     contains not only GET requests.
+	 * </ul>
+	 *
+	 * @param {function(string):Promise<boolean>|boolean} fnOptimisticBatchEnabler
+	 *   The optimistic batch enabler callback controlling whether optimistic batch should be used
+	 * @throws {Error} If
+	 * <ul>
+	 *   <li> the earlyRequests model parameter is not set,
+	 *   <li> the setter is called after the first $batch request is sent,
+	 *   <li> the given <code>fnOptimisticBatchEnabler</code> parameter is not a function
+	 *   <li> the setter is called more than once
+	 * </ul>
+	 *
+	 * @experimental As of version 1.100.0
+	 * @private
+	 * @ui5-restricted sap.fe
+	 */
+	ODataModel.prototype.setOptimisticBatchEnabler = function (fnOptimisticBatchEnabler) {
+		if (!this.bEarlyRequests) {
+			throw new Error("The earlyRequests model parameter is not set");
+		}
+		if (this.oRequestor.isFirstBatchSent()) {
+			throw new Error("The setter is called after the first $batch request is sent");
+		}
+		if (typeof fnOptimisticBatchEnabler !== "function") {
+			throw new Error("The given fnOptimisticBatchEnabler parameter is not a function");
+		}
+		if (this.fnOptimisticBatchEnabler) {
+			throw new Error("The setter is called more than once");
+		}
+
+		this.fnOptimisticBatchEnabler = fnOptimisticBatchEnabler;
+	};
+
 	/**
 	 * Submits the requests associated with the given group ID in one batch request. Requests from
 	 * subsequent calls to this method for the same group ID may be combined in one batch request

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

@@ -176,20 +176,20 @@ sap.ui.define([
 
 	/**
 	 * Decides whether the given query options can be fulfilled by this binding and merges them into
-	 * this binding's aggregated query options if necessary.
+	 * this binding's <code>mAggregatedQueryOptions</code> if necessary.
 	 *
 	 * The query options cannot be fulfilled if there are conflicts. A conflict is an option other
-	 * than $expand, $select and $count which has different values in the aggregate and the options
-	 * to be merged. This is checked recursively.
+	 * than <code>$expand</code>, <code>$select</code> and <code>$count</code> which has different
+	 * values in the aggregate and the options to be merged. This is checked recursively.
 	 *
-	 * Merging is not necessary if the binding's cache has already requested its data and the query
-	 * options would extend $select. In this case the binding's cache will request the resp.
-	 * property and add it when it is accessed.
+	 * If the cache is already immutable the query options are aggregated into
+	 * <code>mLateQueryOptions</code>. Then they also cannot be fulfilled if they contain a
+	 * <code>$expand</code> using a collection-valued navigation property.
 	 *
-	 * Note: * is an item in $select and $expand just as others, that is it must be part of the
-	 * array of items and one must not ignore the other items if * is provided. See
-	 * "5.1.2 System Query Option $expand" and "5.1.3 System Query Option $select" in specification
-	 * "OData Version 4.0 Part 2: URL Conventions".
+	 * Note: * is an item in <code>$select</code> and <code>$expand</code> just as others, that is
+	 * it must be part of the array of items and one must not ignore the other items if * is
+	 * provided. See "5.1.2 System Query Option $expand" and "5.1.3 System Query Option $select" in
+	 * specification "OData Version 4.0 Part 2: URL Conventions".
 	 *
 	 * @param {object} mQueryOptions - The query options to be merged
 	 * @param {string} sBaseMetaPath - This binding's meta path
@@ -203,7 +203,6 @@ sap.ui.define([
 			bCacheImmutable, bIsProperty) {
 		var mAggregatedQueryOptionsClone = _Helper.merge({},
 				bCacheImmutable && this.mLateQueryOptions || this.mAggregatedQueryOptions),
-			bChanged = false,
 			that = this;
 
 		/*
@@ -235,7 +234,6 @@ sap.ui.define([
 							.fetchObject(sExpandMetaPath).getResult().$isCollection) {
 						return false;
 					}
-					bChanged = true;
 				}
 				return merge(mAggregatedQueryOptions.$expand[sExpandPath],
 					mQueryOptions0.$expand[sExpandPath], sExpandMetaPath, true, bAddExpand);
@@ -249,7 +247,6 @@ sap.ui.define([
 			 */
 			function mergeSelectPath(sSelectPath) {
 				if (mAggregatedQueryOptions.$select.indexOf(sSelectPath) < 0) {
-					bChanged = true;
 					mAggregatedQueryOptions.$select.push(sSelectPath);
 				}
 				return true;
@@ -290,7 +287,7 @@ sap.ui.define([
 		if (merge(mAggregatedQueryOptionsClone, mQueryOptions, sBaseMetaPath)) {
 			if (!bCacheImmutable) {
 				this.mAggregatedQueryOptions = mAggregatedQueryOptionsClone;
-			} else if (bChanged) {
+			} else {
 				this.mLateQueryOptions = mAggregatedQueryOptionsClone;
 			}
 			return true;
@@ -819,7 +816,8 @@ sap.ui.define([
 
 				// Note: in operation bindings mAggregatedQueryOptions misses the options from
 				// $$inheritExpandSelect
-				if (oCache && !oCache.hasSentRequest() && !that.oOperation) {
+				// If the cache is immutable, only mLateQueryOptions may have changed
+				if (!bCacheImmutable && oCache && !oCache.hasSentRequest() && !that.oOperation) {
 					if (that.bSharedRequest) {
 						oCache.setActive(false);
 						oCache = that.createAndSetCache(that.mAggregatedQueryOptions,
@@ -1020,8 +1018,8 @@ sap.ui.define([
 			}
 			if (oCache !== undefined) {
 				// Pending changes for this cache are only possible when there is a cache already
-				if (oCache && oCache.hasPendingChangesForPath("", false,
-						bIgnoreKeptAlive && oDependent.mParameters.$$ownRequest)) {
+				if (oCache && oCache.hasPendingChangesForPath("", false, bIgnoreKeptAlive
+						&& oDependent.mParameters && oDependent.mParameters.$$ownRequest)) {
 					return true;
 				}
 			} else if (oDependent.hasPendingChangesForPath("")) {
@@ -1069,36 +1067,6 @@ sap.ui.define([
 		return false;
 	};
 
-	/**
-	 * Refreshes all dependent bindings with the given parameters and waits for them to have
-	 * finished.
-	 *
-	 * @param {string} sResourcePathPrefix
-	 *   The resource path prefix which is used to delete the dependent caches and corresponding
-	 *   messages; may be "" but not <code>undefined</code>
-	 * @param {string} [sGroupId]
-	 *   The group ID to be used for refresh
-	 * @param {boolean} [bCheckUpdate]
-	 *   If <code>true</code>, a property binding is expected to check for updates
-	 * @param {boolean} [bKeepCacheOnError]
-	 *   If <code>true</code>, the binding data remains unchanged if the refresh fails
-	 * @returns {sap.ui.base.SyncPromise}
-	 *   A promise resolving when all dependent bindings are refreshed; it is rejected
-	 *   when the refresh fails; the promise is resolved immediately on a suspended binding
-	 * @throws {Error}
-	 *   If the binding's root binding is suspended and a group ID different from the binding's
-	 *   group ID is given
-	 *
-	 * @private
-	 */
-	ODataParentBinding.prototype.refreshDependentBindings = function (sResourcePathPrefix, sGroupId,
-			bCheckUpdate, bKeepCacheOnError) {
-		return SyncPromise.all(this.getDependentBindings().map(function (oDependentBinding) {
-			return oDependentBinding.refreshInternal(sResourcePathPrefix, sGroupId, bCheckUpdate,
-				bKeepCacheOnError);
-		}));
-	};
-
 	/**
 	 * Recursively refreshes all dependent list bindings that have no own cache.
 	 *
@@ -1278,10 +1246,10 @@ sap.ui.define([
 	 * @throws {Error}
 	 *   If this binding
 	 *   <ul>
-	 *   <li>is relative to a {@link sap.ui.model.odata.v4.Context},</li>
-	 *   <li>is an operation binding,</li>
-	 *   <li>has {@link sap.ui.model.Binding#isSuspended} set to <code>false</code>,</li>
-	 *   <li>is not a root binding. Use {@link #getRootBinding} to determine the root binding.</li>
+	 *   <li>is relative to a {@link sap.ui.model.odata.v4.Context},
+	 *   <li>is an operation binding,
+	 *   <li>has {@link sap.ui.model.Binding#isSuspended} set to <code>false</code>,
+	 *   <li>is not a root binding. Use {@link #getRootBinding} to determine the root binding.
 	 *   </ul>
 	 *
 	 * @public
@@ -1341,12 +1309,12 @@ sap.ui.define([
 	 *
 	 * @throws {Error}
 	 *   If this binding
-	 *  <ul>
-	 *   <li>is relative to a {@link sap.ui.model.odata.v4.Context},</li>
-	 *   <li>is an operation binding,</li>
-	 *   <li>has {@link sap.ui.model.Binding#isSuspended} set to <code>true</code>,</li>
-	 *   <li>has pending changes that cannot be ignored,</li>
-	 *   <li>is not a root binding. Use {@link #getRootBinding} to determine the root binding.</li>
+	 *   <ul>
+	 *   <li>is relative to a {@link sap.ui.model.odata.v4.Context},
+	 *   <li>is an operation binding,
+	 *   <li>has {@link sap.ui.model.Binding#isSuspended} set to <code>true</code>,
+	 *   <li>has pending changes that cannot be ignored,
+	 *   <li>is not a root binding. Use {@link #getRootBinding} to determine the root binding.
 	 *   </ul>
 	 *
 	 * @public

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

@@ -42,7 +42,7 @@ sap.ui.define([
 		 * @mixes sap.ui.model.odata.v4.ODataBinding
 		 * @public
 		 * @since 1.37.0
-		 * @version 1.99.0
+		 * @version 1.100.0
 		 * @borrows sap.ui.model.odata.v4.ODataBinding#getGroupId as #getGroupId
 		 * @borrows sap.ui.model.odata.v4.ODataBinding#getRootBinding as #getRootBinding
 		 * @borrows sap.ui.model.odata.v4.ODataBinding#getUpdateGroupId as #getUpdateGroupId
@@ -269,7 +269,8 @@ sap.ui.define([
 				&& !bIsMeta) {
 			vType = oMetaModel.fetchUI5Type(sResolvedPath);
 		}
-		if (arguments.length < 4) {
+		if (vValue === undefined) {
+			// if called via #onChange, we need to fetch implicit values
 			vValue = this.oCachePromise.then(function (oCache) {
 				var sDataPath, sMetaPath;