class sap.ui.model.odata.v4.Context

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/model/odata/v4/Context
Application Component: CA-UI5-COR

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.


Constructor


Methods Overview

Method Description
collapse

Collapses the group node that this context points to.

References:

  • #expand
  • #isExpanded

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.

References:

  • sap.ui.base.Object#destroy

expand

Expands the group node that this context points to.

References:

  • #collapse
  • #isExpanded

sap.ui.model.odata.v4.Context.extend

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.

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 bAtEnd, and when a context representing a created entity is deleted again.

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 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:

  • sap.ui.model.Context#getObject

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 undefined if the data is not (yet) available; no request is triggered. Use #requestProperty for asynchronous access.

References:

  • sap.ui.model.Context#getProperty
  • sap.ui.model.odata.v4.ODataMetaModel#requestUI5Type

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.

References:

  • #collapse
  • #expand

isKeepAlive

Returns whether this context is kept alive.

References:

  • #setKeepAlive

isTransient

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.

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 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:

  • #getBinding
  • sap.ui.model.odata.v4.ODataContextBinding#refresh
  • sap.ui.model.odata.v4.ODataListBinding#refresh

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.

References:

  • sap.ui.model.odata.v4.ODataMetaModel#requestUI5Type

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 $$patchWithoutSideEffects. The method can be called on

  • the bound context of a context binding,
  • the return value context of an operation binding,
  • a context of a list binding representing a single entity,
  • the header context of a list binding; side effects are loaded for the whole binding in this case.
Key predicates must be available in this context's path. Avoid navigation properties as part of a binding's $select system query option as they may trigger pointless requests. There must be only context bindings between this context and its first ancestor binding which uses own data service requests.

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...

  • 'dataRequested', can instead be done before calling #requestSideEffects.
  • 'dataReceived', can instead be done once the oPromise returned by #requestSideEffects fulfills or rejects (using oPromise.then(function () {...}, function () {...})).


References:
  • sap.ui.model.odata.v4.ODataContextBinding#execute
  • sap.ui.model.odata.v4.ODataContextBinding#getBoundContext
  • sap.ui.model.odata.v4.ODataListBinding#getHeaderContext
  • sap.ui.model.odata.v4.ODataModel#bindContext

setKeepAlive

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:

  • #isKeepAlive

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.

References:

  • #getProperty
  • sap.ui.model.odata.v4.ODataContextBinding#event:patchSent
  • sap.ui.model.odata.v4.ODataContextBinding#event:patchCompleted
  • sap.ui.model.odata.v4.ODataListBinding#event:patchSent
  • sap.ui.model.odata.v4.ODataListBinding#event:patchCompleted

toString

Returns a string representation of this object including the binding path.

collapse

Collapses the group node that this context points to.

References:

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.

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.

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.

References:

expand

Expands the group node that this context points to.

References:

sap.ui.model.odata.v4.Context.extend

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

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 bAtEnd, and when a context representing a created entity is deleted again.

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 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

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 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 true, the value is returned in external format using a UI5 type for the given property path that formats corresponding to the property's EDM type and constraints. If the type is not yet available, undefined is returned.

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.

References:

isKeepAlive

Returns whether this context is kept alive.

References:

isTransient

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.

refresh

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 fnOnBeforeDestroy callback passed with #setKeepAlive) is called.

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 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

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.

References:

Param Type DefaultValue Description
vPath string string[]

One or multiple paths relative to this context

bExternalFormat boolean

If true, the values are returned in external format using UI5 types for the given property paths that format corresponding to the properties' EDM types and constraints

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.

Param Type DefaultValue Description
sGroupId string

The group ID to be used

bAllowRemoval boolean

Allows to remove the context

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 $$patchWithoutSideEffects. The method can be called on

Key predicates must be available in this context's path. Avoid navigation properties as part of a binding's $select system query option as they may trigger pointless requests. There must be only context bindings between this context and its first ancestor binding which uses own data service requests.

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:

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 [{$PropertyPath : "TEAM_ID"}, {$NavigationPropertyPath : "EMPLOYEE_2_MANAGER"}, {$PropertyPath : "EMPLOYEE_2_TEAM/Team_Id"}]. An empty navigation property path means that the whole entity may have changed, including its navigation properties. Since 1.75, a property path may end with a "*" segment to indicate that all structural properties may have changed, but no navigation properties (unless listed explicitly), for example [{$PropertyPath : "*"}, {$NavigationPropertyPath : "EMPLOYEE_2_MANAGER"}] or [{$PropertyPath : "EMPLOYEE_2_MANAGER/*"}].

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.

setKeepAlive

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 bKeepAlive is true. The binding keeps requesting messages until it is destroyed. Supported since 1.92.0

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.

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 null to prevent the PATCH request.

bRetry boolean

Since 1.85.0, if true the property is not reset if the PATCH request failed. It contributes to the pending changes instead (see sap.ui.model.odata.v4.ODataModel#hasPendingChanges, sap.ui.model.odata.v4.ODataContextBinding#hasPendingChanges and sap.ui.model.odata.v4.ODataListBinding#hasPendingChanges) and can be reset via the corresponding resetChanges methods.

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.

toString

Returns a string representation of this object including the binding path.