Implementation of an OData V4 model's context.
The context is a pointer to model data as returned by a query from a sap.ui.model.odata.v4.ODataContextBinding or a sap.ui.model.odata.v4.ODataListBinding. Contexts are always and only created by such bindings. A context for a context binding points to the complete query result. A context for a list binding points to one specific entry in the binding's collection. A property binding does not have a context, you can access its value via sap.ui.model.odata.v4.ODataPropertyBinding#getValue.
Applications can access model data only via a context, either synchronously with the risk that the values are not available yet (#getProperty and #getObject) or asynchronously (#requestProperty and #requestObject).
Context instances are immutable except for their indexes.
Method | Description |
---|---|
collapse |
Collapses the group node that this context points to.
|
created |
Returns a promise that is resolved without data when the entity represented by this context has been created in the back end and all selected properties of this entity are available. Expanded navigation properties are only available if the context's binding is refreshable. sap.ui.model.odata.v4.ODataBinding#refresh describes which bindings are refreshable. As long as the promise is not yet resolved or rejected, the entity represented by this context is transient. Once the promise is resolved, #getPath returns a path including the key predicate of the new entity. This requires that all key properties are available. |
delete |
Deletes the OData entity this context points to. The context must not be used anymore after successful deletion. |
destroy |
Destroys this context, that is, it removes this context from all dependent bindings and drops references to binding and model, so that the context cannot be used anymore; it keeps path and index for debugging purposes.
|
expand |
Expands the group node that this context points to.
|
sap.ui.model.odata.v4.Context.extend |
Creates a new subclass of class sap.ui.model.odata.v4.Context with name
|
getBinding |
Returns the binding this context belongs to. |
getCanonicalPath |
Returns the "canonical path" of the entity for this context. According to "4.3.1 Canonical URL" of the specification "OData Version 4.0 Part 2: URL Conventions", this is the "name of the entity set associated with the entity followed by the key predicate identifying the entity within the collection". Use the canonical path in sap.ui.core.Element#bindElement to create an element binding. Note: For a transient context (see #isTransient) a wrong path is returned unless all key properties are available within the initial data. |
getGroupId |
Returns the group ID of the context's binding that is used for read requests. See sap.ui.model.odata.v4.ODataListBinding#getGroupId and sap.ui.model.odata.v4.ODataContextBinding#getGroupId. |
getIndex |
Returns the context's index within the binding's collection. The return value changes when a new entity is added via sap.ui.model.odata.v4.ODataListBinding#create without |
sap.ui.model.odata.v4.Context.getMetadata |
Returns a metadata object for class sap.ui.model.odata.v4.Context. |
getObject |
Returns the value for the given path relative to this context. The function allows access to the complete data the context points to (if Returns
|
getProperty |
Returns the property value for the given path relative to this context. The path is expected to point to a structural property with primitive type. Returns
|
getUpdateGroupId |
Returns the group ID of the context's binding that is used for update requests. See sap.ui.model.odata.v4.ODataListBinding#getUpdateGroupId and sap.ui.model.odata.v4.ODataContextBinding#getUpdateGroupId. |
hasPendingChanges |
Returns whether there are pending changes for bindings dependent on this context, or for unresolved bindings (see sap.ui.model.Binding#isResolved) which were dependent on this context at the time the pending change was created. This includes the context itself being transient (see #isTransient). |
isExpanded |
Tells whether the group node that this context points to is expanded.
|
isKeepAlive |
Returns whether this context is kept alive.
|
isTransient |
For a context created using sap.ui.model.odata.v4.ODataListBinding#create, the method returns |
refresh |
Refreshes the single entity represented by this context. Use #requestRefresh if you want to wait for the refresh. |
requestCanonicalPath |
Returns a promise for the "canonical path" of the entity for this context. According to "4.3.1 Canonical URL" of the specification "OData Version 4.0 Part 2: URL Conventions", this is the "name of the entity set associated with the entity followed by the key predicate identifying the entity within the collection". Use the canonical path in sap.ui.core.Element#bindElement to create an element binding. Note: For a transient context (see #isTransient) a wrong path is returned unless all key properties are available within the initial data. |
requestObject |
Returns a promise on the value for the given path relative to this context. The function allows access to the complete data the context points to (if If you want #requestObject to read fresh data, call #refresh first.
|
requestProperty |
Returns a promise on the property value for the given path relative to this context. The path is expected to point to a structural property with primitive type. Since 1.81.1 it is possible to request more than one property. Property values that are not cached yet are requested from the back end.
|
requestRefresh |
Refreshes the single entity represented by this context and returns a promise to wait for it. See #refresh for details. Use #refresh if you do not need the promise. |
requestSideEffects |
Loads side effects for this context using the given "14.5.11 Expression edm:NavigationPropertyPath" or "14.5.13 Expression edm:PropertyPath" objects. Use this method to explicitly load side effects in case implicit loading is switched off via the binding-specific parameter
If the first ancestor binding has an empty path, it is a context binding. In this case, we look for the farthest ancestor binding with the following characteristics: It uses own data service requests, it can be reached via a sequence of only empty paths, and it is actually being used. This way, side effects are loaded also for siblings of that first ancestor binding which show the same data, but useless requests are avoided. By default, the request uses the update group ID for this context's binding; this way, it can easily be part of the same batch request as the corresponding update. Caution: If a dependent binding uses a different update group ID, it may lose its pending changes. The same will happen if a different group ID is provided, and the side effects affect properties for which there are pending changes. All failed updates or creates for the group ID are repeated within the same batch request. If the group ID has submit mode sap.ui.model.odata.v4.SubmitMode.Auto and there are currently running updates or creates this method first waits for them to be processed. The events 'dataRequested' and 'dataReceived' are not fired. Whatever should happen in the event handler attached to...
References:
|
setKeepAlive |
Sets this context's
|
setProperty |
Sets a new value for the property identified by the given path. The path is relative to this context and is expected to point to a structural property with primitive type or, since 1.85.0, to an instance annotation.
|
toString |
Returns a string representation of this object including the binding path. |
Returns a promise that is resolved without data when the entity represented by this context has been created in the back end and all selected properties of this entity are available. Expanded navigation properties are only available if the context's binding is refreshable. sap.ui.model.odata.v4.ODataBinding#refresh describes which bindings are refreshable.
As long as the promise is not yet resolved or rejected, the entity represented by this context is transient.
Once the promise is resolved, #getPath returns a path including the key predicate of the new entity. This requires that all key properties are available.
Deletes the OData entity this context points to.
The context must not be used anymore after successful deletion.
Param | Type | DefaultValue | Description |
---|---|---|---|
sGroupId | string |
The group ID to be used for the DELETE request; if not specified, the update group ID for the context's binding is used, see #getUpdateGroupId; the resulting group ID must not have sap.ui.model.odata.v4.SubmitMode.API. Since 1.81, if this context is transient (see #isTransient), no group ID needs to be specified. |
Destroys this context, that is, it removes this context from all dependent bindings and drops references to binding and model, so that the context cannot be used anymore; it keeps path and index for debugging purposes.
References:
Creates a new subclass of class sap.ui.model.odata.v4.Context with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.ui.model.Context.extend.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
Name of the class being created |
|
oClassInfo | object |
Object literal with information about the class |
|
FNMetaImpl | function |
Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class |
Returns the "canonical path" of the entity for this context. According to "4.3.1 Canonical URL" of the specification "OData Version 4.0 Part 2: URL Conventions", this is the "name of the entity set associated with the entity followed by the key predicate identifying the entity within the collection". Use the canonical path in sap.ui.core.Element#bindElement to create an element binding. Note: For a transient context (see #isTransient) a wrong path is returned unless all key properties are available within the initial data.
Returns the group ID of the context's binding that is used for read requests. See sap.ui.model.odata.v4.ODataListBinding#getGroupId and sap.ui.model.odata.v4.ODataContextBinding#getGroupId.
Returns the context's index within the binding's collection. The return value changes when a new entity is added via sap.ui.model.odata.v4.ODataListBinding#create without bAtEnd
, and when a context representing a created entity is deleted again.
Returns a metadata object for class sap.ui.model.odata.v4.Context.
Returns the value for the given path relative to this context. The function allows access to the complete data the context points to (if sPath
is "") or any part thereof. The data is a JSON structure as described in "OData JSON Format Version 4.0". Note that the function clones the result. Modify values via sap.ui.model.odata.v4.ODataPropertyBinding#setValue.
Returns undefined
if the data is not (yet) available; no request is triggered. Use #requestObject for asynchronous access.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string | "" |
A path relative to this context |
Returns the property value for the given path relative to this context. The path is expected to point to a structural property with primitive type. Returns undefined
if the data is not (yet) available; no request is triggered. Use #requestProperty for asynchronous access.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string |
A path relative to this context |
|
bExternalFormat | boolean |
If |
Returns the group ID of the context's binding that is used for update requests. See sap.ui.model.odata.v4.ODataListBinding#getUpdateGroupId and sap.ui.model.odata.v4.ODataContextBinding#getUpdateGroupId.
Returns whether there are pending changes for bindings dependent on this context, or for unresolved bindings (see sap.ui.model.Binding#isResolved) which were dependent on this context at the time the pending change was created. This includes the context itself being transient (see #isTransient).
Tells whether the group node that this context points to is expanded.
References:
For a context created using sap.ui.model.odata.v4.ODataListBinding#create, the method returns true
if the context is transient, meaning that the promise returned by #created is not yet resolved or rejected, and returns false
if the context is not transient. The result of this function can also be accessed via instance annotation "@$ui5.context.isTransient" at the entity.
Refreshes the single entity represented by this context. Use #requestRefresh if you want to wait for the refresh.
Param | Type | DefaultValue | Description |
---|---|---|---|
sGroupId | string |
The group ID to be used for the refresh; if not specified, the group ID for the context's binding is used, see #getGroupId. |
|
bAllowRemoval | boolean |
If the context belongs to a list binding, the parameter allows the list binding to remove the context from the list binding's collection because the entity does not match the binding's filter anymore, see sap.ui.model.odata.v4.ODataListBinding#filter; a removed context is destroyed, see #destroy. If the context belongs to a context binding, the parameter must not be used. Supported since 1.55.0 Since 1.84.0, if this context is kept alive (see #isKeepAlive), it is only destroyed if the corresponding entity does no longer exist in the back end. In this case, the |
Returns a promise for the "canonical path" of the entity for this context. According to "4.3.1 Canonical URL" of the specification "OData Version 4.0 Part 2: URL Conventions", this is the "name of the entity set associated with the entity followed by the key predicate identifying the entity within the collection". Use the canonical path in sap.ui.core.Element#bindElement to create an element binding. Note: For a transient context (see #isTransient) a wrong path is returned unless all key properties are available within the initial data.
Returns a promise on the value for the given path relative to this context. The function allows access to the complete data the context points to (if sPath
is "") or any part thereof. The data is a JSON structure as described in "OData JSON Format Version 4.0". Note that the function clones the result. Modify values via sap.ui.model.odata.v4.Context#setProperty.
If you want #requestObject to read fresh data, call #refresh first.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string | "" |
A path relative to this context |
Returns a promise on the property value for the given path relative to this context. The path is expected to point to a structural property with primitive type. Since 1.81.1 it is possible to request more than one property. Property values that are not cached yet are requested from the back end.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
vPath | string string[] |
One or multiple paths relative to this context |
|
bExternalFormat | boolean |
If |
Refreshes the single entity represented by this context and returns a promise to wait for it. See #refresh for details. Use #refresh if you do not need the promise.
Param | Type | DefaultValue | Description |
---|---|---|---|
sGroupId | string |
The group ID to be used |
|
bAllowRemoval | boolean |
Allows to remove the context |
Loads side effects for this context using the given "14.5.11 Expression edm:NavigationPropertyPath" or "14.5.13 Expression edm:PropertyPath" objects. Use this method to explicitly load side effects in case implicit loading is switched off via the binding-specific parameter $$patchWithoutSideEffects
. The method can be called on
If the first ancestor binding has an empty path, it is a context binding. In this case, we look for the farthest ancestor binding with the following characteristics: It uses own data service requests, it can be reached via a sequence of only empty paths, and it is actually being used. This way, side effects are loaded also for siblings of that first ancestor binding which show the same data, but useless requests are avoided.
By default, the request uses the update group ID for this context's binding; this way, it can easily be part of the same batch request as the corresponding update. Caution: If a dependent binding uses a different update group ID, it may lose its pending changes. The same will happen if a different group ID is provided, and the side effects affect properties for which there are pending changes.
All failed updates or creates for the group ID are repeated within the same batch request. If the group ID has submit mode sap.ui.model.odata.v4.SubmitMode.Auto and there are currently running updates or creates this method first waits for them to be processed.
The events 'dataRequested' and 'dataReceived' are not fired. Whatever should happen in the event handler attached to...
oPromise
returned by #requestSideEffects fulfills or rejects (using oPromise.then(function () {...}, function () {...})
). Param | Type | DefaultValue | Description |
---|---|---|---|
aPathExpressions | object[] string[] |
The "14.5.11 Expression edm:NavigationPropertyPath" or "14.5.13 Expression edm:PropertyPath" objects describing which properties need to be loaded because they may have changed due to side effects of a previous update, for example Since 1.82.0 absolute paths are supported. Absolute paths must start with the entity container (example "/com.sap.gateway.default.iwbep.tea_busi.v0001.Container/TEAMS") of the service. All (navigation) properties in the complete model matching such an absolute path are updated. Since 1.85.0, "14.4.11 Expression edm:String" is accepted as well. |
|
sGroupId | string |
The group ID to be used (since 1.69.0); if not specified, the update group ID for the context's binding is used, see #getUpdateGroupId. If a different group ID is specified, make sure that #requestSideEffects is called after the corresponding updates have been successfully processed by the server and that there are no pending changes for the affected properties. |
Sets this context's keepAlive
attribute. If true
the context is kept alive even when it is removed from its binding's collection, for example if a filter is applied and the entity represented by this context does not match the filter criteria.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
bKeepAlive | boolean |
Whether to keep the context alive |
|
fnOnBeforeDestroy | function |
Callback function that is executed once for a kept-alive context just before it is destroyed, see #destroy. Supported since 1.84.0 |
|
bRequestMessages | boolean |
Whether to request messages for this entity. Only used if |
Sets a new value for the property identified by the given path. The path is relative to this context and is expected to point to a structural property with primitive type or, since 1.85.0, to an instance annotation.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string |
A path relative to this context |
|
vValue | any |
The new value which must be primitive |
|
sGroupId | string |
The group ID to be used for the PATCH request; if not specified, the update group ID for the context's binding is used, see #getUpdateGroupId. Since 1.74.0, you can use |
|
bRetry | boolean |
Since 1.85.0, if The PATCH is automatically repeated with the next call of sap.ui.model.odata.v4.ODataModel#submitBatch if the group ID has sap.ui.model.odata.v4.SubmitMode.API. Otherwise it is repeated when the property is modified again. Each time the PATCH request is sent to the server, a 'patchSent' event is fired on the binding sending the request. When the response for this request is received, a 'patchCompleted' with a boolean parameter 'success' is fired. |