class sap.ui.model.odata.v4.ODataContextBinding

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

Context binding for an OData V4 model. An event handler can only be attached to this binding for the following events: 'AggregatedDataStateChange', 'change', 'dataReceived', 'dataRequested', 'DataStateChange', 'patchCompleted', and 'patchSent'. For other events, an error is thrown.

A context binding can also be used as an operation binding to support bound actions, action imports, bound functions and function imports. If you want to control the execution time of an operation, for example a function import named "GetNumberOfAvailableItems", create a context binding for the path "/GetNumberOfAvailableItems(...)" (as specified here, including the three dots). Such an operation binding is deferred, meaning that it does not request automatically, but only when you call #execute. #refresh is always ignored for actions and action imports. For bound functions and function imports, it is ignored if #execute has not yet been called. Afterwards it results in another call of the function with the parameter values of the last execute.

The binding parameter for bound actions or bound functions may be given in the binding path, for example "/SalesOrderList('42')/name.space.SalesOrder_Confirm". This can be used if the exact entity for the binding parameter is known in advance. If you use a relative binding instead, the operation path is a concatenation of the parent context's canonical path and the deferred binding's path.

Example: You have a table with a list binding to "/SalesOrderList". In each row you have a button to confirm the sales order, with the relative binding "name.space.SalesOrder_Confirm(...)". Then the parent context for such a button refers to an entity in "SalesOrderList", so its canonical path is "/SalesOrderList('SalesOrderID')" and the resulting path for the action is "/SalesOrderList('SalesOrderID')/name.space.SalesOrder_Confirm".

This also works if the relative path of the deferred operation binding starts with a navigation property. Then this navigation property will be part of the operation's resource path, which is still valid.

A deferred operation binding is not allowed to have another deferred operation binding as parent.


Constructor


Events Overview

Event Description
change

The 'change' event is fired when the binding is initialized or its parent context is changed. It is to be used by controls to get notified about changes to the bound context of this context binding. Registered event handlers are called with the change reason as parameter.

Since: 1.37.0.

dataReceived

The 'dataReceived' event is fired after the back-end data has been processed. It is only fired for GET requests. The 'dataReceived' event is to be used by applications, for example to switch off a busy indicator or to process an error. In case of a deferred operation binding, 'dataReceived' is not fired: Whatever should happen in the event handler attached to that event, can instead be done once the oPromise returned by #execute fulfills or rejects (using oPromise.then(function () {...}, function () {...})).

If back-end requests are successful, the event has almost no parameters. For compatibility with sap.ui.model.Binding#event:dataReceived, an event parameter data : {} is provided: "In error cases it will be undefined", but otherwise it is not. Use the binding's bound context via oEvent.getSource().getBoundContext() to access the response data. Note that controls bound to this data may not yet have been updated, meaning it is not safe for registered event handlers to access data via control APIs.

If a back-end request fails, the 'dataReceived' event provides an Error in the 'error' event parameter.

Since: 1.37.0.

dataRequested

The 'dataRequested' event is fired directly after data has been requested from a back end. It is only fired for GET requests. The 'dataRequested' event is to be used by applications, for example to switch on a busy indicator. Registered event handlers are called without parameters. In case of a deferred operation binding, 'dataRequested' is not fired: Whatever should happen in the event handler attached to that event, can instead be done before calling #execute.

Since: 1.37.0.

patchCompleted

The 'patchCompleted' event is fired when the back end has responded to the last PATCH request for this binding. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchCompleted' event. For each 'patchSent' event, a 'patchCompleted' event is fired.

Since: 1.59.0.

patchSent

The 'patchSent' event is fired when the first PATCH request for this binding is sent to the back end. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchSent' event. For each 'patchSent' event, a 'patchCompleted' event is fired.

Since: 1.59.0.

change

The 'change' event is fired when the binding is initialized or its parent context is changed. It is to be used by controls to get notified about changes to the bound context of this context binding. Registered event handlers are called with the change reason as parameter.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event
getParameters() object
reason sap.ui.model.ChangeReason

The reason for the 'change' event could be

dataReceived

The 'dataReceived' event is fired after the back-end data has been processed. It is only fired for GET requests. The 'dataReceived' event is to be used by applications, for example to switch off a busy indicator or to process an error. In case of a deferred operation binding, 'dataReceived' is not fired: Whatever should happen in the event handler attached to that event, can instead be done once the oPromise returned by #execute fulfills or rejects (using oPromise.then(function () {...}, function () {...})).

If back-end requests are successful, the event has almost no parameters. For compatibility with sap.ui.model.Binding#event:dataReceived, an event parameter data : {} is provided: "In error cases it will be undefined", but otherwise it is not. Use the binding's bound context via oEvent.getSource().getBoundContext() to access the response data. Note that controls bound to this data may not yet have been updated, meaning it is not safe for registered event handlers to access data via control APIs.

If a back-end request fails, the 'dataReceived' event provides an Error in the 'error' event parameter.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event
getParameters() object
data object

An empty data object if a back-end request succeeds

error Error

The error object if a back-end request failed. If there are multiple failed back-end requests, the error of the first one is provided.

dataRequested

The 'dataRequested' event is fired directly after data has been requested from a back end. It is only fired for GET requests. The 'dataRequested' event is to be used by applications, for example to switch on a busy indicator. Registered event handlers are called without parameters. In case of a deferred operation binding, 'dataRequested' is not fired: Whatever should happen in the event handler attached to that event, can instead be done before calling #execute.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event

patchCompleted

The 'patchCompleted' event is fired when the back end has responded to the last PATCH request for this binding. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchCompleted' event. For each 'patchSent' event, a 'patchCompleted' event is fired.

Since: 1.59.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataContextBinding

This binding

getParameters() object

Object containing all event parameters

success boolean

Whether all PATCHes are successfully processed

patchSent

The 'patchSent' event is fired when the first PATCH request for this binding is sent to the back end. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchSent' event. For each 'patchSent' event, a 'patchCompleted' event is fired.

Since: 1.59.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataContextBinding

This binding


Methods Overview

Method Description
attachEvent

See sap.ui.base.EventProvider#attachEvent

References:

  • sap.ui.base.EventProvider#attachEvent

attachPatchCompleted

Attach event handler fnFunction to the 'patchCompleted' event of this binding.

attachPatchSent

Attach event handler fnFunction to the 'patchSent' event of this binding.

changeParameters

Changes this binding's parameters and refreshes the binding.

If there are pending changes an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #changeParameters.

The parameters are changed according to the given map of parameters: Parameters with an undefined value are removed, the other parameters are set, and missing parameters remain unchanged.

destroy

Destroys the object. The object must not be used anymore after this function was called.

References:

  • sap.ui.model.Binding#destroy

detachPatchCompleted

Detach event handler fnFunction from the 'patchCompleted' event of this binding.

detachPatchSent

Detach event handler fnFunction from the 'patchSent' event of this binding.

execute

Calls the OData operation that corresponds to this operation binding.

Parameters for the operation must be set via #setParameter beforehand.

The value of this binding is the result of the operation. To access a result of primitive type, bind a control to the path "value", for example <Text text="{value}"/>. If the result has a complex or entity type, you can bind properties as usual, for example <Text text="{street}"/>.

sap.ui.model.odata.v4.ODataContextBinding.extend

Creates a new subclass of class sap.ui.model.odata.v4.ODataContextBinding 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.ContextBinding.extend.

getBoundContext

Returns the bound context.

getGroupId

Returns the group ID of the binding that is used for read requests. The group ID of the binding is alternatively defined by

sap.ui.model.odata.v4.ODataContextBinding.getMetadata

Returns a metadata object for class sap.ui.model.odata.v4.ODataContextBinding.

getParameterContext

Returns the context pointing to the parameters of a deferred operation binding.

getRootBinding

Returns the root binding of this binding's hierarchy, see binding Initialization and Read Requests.

getUpdateGroupId

Returns the group ID of the binding that is used for update requests. The update group ID of the binding is alternatively defined by

hasPendingChanges

Returns true if this binding or its dependent bindings have pending property 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 sap.ui.model.odata.v4.Context#delete) and the execution of OData operations (see sap.ui.model.odata.v4.ODataContextBinding#execute).

Note: If this binding is relative, its data is cached separately for each parent context path. This method returns true if there are pending changes for the current parent context path of this binding. If this binding is unresolved (see sap.ui.model.Binding#isResolved), it returns false.

initialize

Initializes the OData context binding: Fires a 'change' event in case the binding has a resolved path and its root binding is not suspended.

References:

  • #getRootBinding

isInitial

Method not supported

moveEntityTo

Moves the bound entity into the given list binding. This binding loses its data. The method may only be called when this binding has finished loading. You can verify this by calling oBinding.getBoundContext().requestObject(). If that promise resolves, the binding has finished loading.

refresh

Refreshes the binding. Prompts the model to retrieve data from the server using the given group ID and notifies the control that new data is available.

Refresh is supported for bindings which are not relative to a sap.ui.model.odata.v4.Context.

Note: When calling #refresh multiple times, the result of the request triggered by the last call determines the binding's data; it is independent of the order of calls to sap.ui.model.odata.v4.ODataModel#submitBatch with the given group ID.

If there are pending changes, an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #refresh.

Use #requestRefresh if you want to wait for the refresh.

References:

  • sap.ui.model.Binding#refresh
  • #getRootBinding
  • #suspend

requestObject

Returns a promise on the value for the given path relative to this binding. The function allows access to the complete data the binding 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 oBinding.refresh() first.

References:

  • sap.ui.model.odata.v4.Context#requestObject

requestRefresh

Refreshes the binding and returns a promise to wait for it. See #refresh for details. Use #refresh if you do not need the promise.

resetChanges

Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input.

resume

Resumes this binding. The binding can then again fire change events and trigger data service requests. Before 1.53.0, this method was not supported and threw an error.

References:

setParameter

Sets a parameter for an operation call.

suspend

Suspends this binding. A suspended binding does not fire change events nor does it trigger data service requests. Call #resume to resume the binding. Before 1.53.0, this method was not supported and threw an error.

References:

  • Suspend and Resume
  • sap.ui.model.Binding#suspend
  • sap.ui.model.odata.v4.ODataContextBinding#hasPendingChanges
  • sap.ui.model.odata.v4.ODataListBinding#hasPendingChanges
  • #resume

toString

Returns a string representation of this object including the binding path. If the binding is relative, the parent path is also given, separated by a '|'.

attachEvent

See sap.ui.base.EventProvider#attachEvent

References:

Param Type DefaultValue Description
sEventId string

The identifier of the event to listen for

_oData object
_fnFunction function
_oListener object

attachPatchCompleted

Attach event handler fnFunction to the 'patchCompleted' event of this binding.

Param Type DefaultValue Description
fnFunction function

The function to call when the event occurs

oListener object

Object on which to call the given function

attachPatchSent

Attach event handler fnFunction to the 'patchSent' event of this binding.

Param Type DefaultValue Description
fnFunction function

The function to call when the event occurs

oListener object

Object on which to call the given function

changeParameters

Changes this binding's parameters and refreshes the binding.

If there are pending changes an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #changeParameters.

The parameters are changed according to the given map of parameters: Parameters with an undefined value are removed, the other parameters are set, and missing parameters remain unchanged.

Param Type DefaultValue Description
mParameters object

Map of binding parameters, see sap.ui.model.odata.v4.ODataModel#bindList and sap.ui.model.odata.v4.ODataModel#bindContext

destroy

Destroys the object. The object must not be used anymore after this function was called.

References:

detachPatchCompleted

Detach event handler fnFunction from the 'patchCompleted' event of this binding.

Param Type DefaultValue Description
fnFunction function

The function to call when the event occurs

oListener object

Object on which to call the given function

detachPatchSent

Detach event handler fnFunction from the 'patchSent' event of this binding.

Param Type DefaultValue Description
fnFunction function

The function to call when the event occurs

oListener object

Object on which to call the given function

execute

Calls the OData operation that corresponds to this operation binding.

Parameters for the operation must be set via #setParameter beforehand.

The value of this binding is the result of the operation. To access a result of primitive type, bind a control to the path "value", for example <Text text="{value}"/>. If the result has a complex or entity type, you can bind properties as usual, for example <Text text="{street}"/>.

Param Type DefaultValue Description
sGroupId string

The group ID to be used for the request; if not specified, the group ID for this binding is used, see sap.ui.model.odata.v4.ODataContextBinding#constructor and #getGroupId. To use the update group ID, see #getUpdateGroupId, it needs to be specified explicitly. Valid values are undefined, '$auto', '$auto.*', '$direct' or application group IDs as specified in sap.ui.model.odata.v4.ODataModel.

bIgnoreETag boolean

Whether the entity's ETag should be actively ignored (If-Match:*); supported for bound actions only, since 1.90.0. Ignored if there is no ETag (since 1.93.0).

fnOnStrictHandlingFailed function

If this callback is given for an action, the preference "handling=strict" is applied. If the service responds with the HTTP status code 412 and a "Preference-applied: handling=strict" header, the details from the OData error response are extracted and passed to the callback as an array of sap.ui.core.message.Message items. The callback has to return a Promise resolving with a boolean value in order to indicate whether the bound action should either be repeated without applying the preference or rejected with an Error instance oError where oError.canceled === true. Since 1.92.0.

sap.ui.model.odata.v4.ODataContextBinding.extend

Creates a new subclass of class sap.ui.model.odata.v4.ODataContextBinding 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.ContextBinding.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

getBoundContext

Returns the bound context.

getGroupId

Returns the group ID of the binding that is used for read requests. The group ID of the binding is alternatively defined by

sap.ui.model.odata.v4.ODataContextBinding.getMetadata

Returns a metadata object for class sap.ui.model.odata.v4.ODataContextBinding.

getParameterContext

Returns the context pointing to the parameters of a deferred operation binding.

getRootBinding

Returns the root binding of this binding's hierarchy, see binding Initialization and Read Requests.

getUpdateGroupId

Returns the group ID of the binding that is used for update requests. The update group ID of the binding is alternatively defined by

hasPendingChanges

Returns true if this binding or its dependent bindings have pending property 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 sap.ui.model.odata.v4.Context#delete) and the execution of OData operations (see sap.ui.model.odata.v4.ODataContextBinding#execute).

Note: If this binding is relative, its data is cached separately for each parent context path. This method returns true if there are pending changes for the current parent context path of this binding. If this binding is unresolved (see sap.ui.model.Binding#isResolved), it returns false.

initialize

Initializes the OData context binding: Fires a 'change' event in case the binding has a resolved path and its root binding is not suspended.

References:

isInitial

Method not supported

moveEntityTo

Moves the bound entity into the given list binding. This binding loses its data. The method may only be called when this binding has finished loading. You can verify this by calling oBinding.getBoundContext().requestObject(). If that promise resolves, the binding has finished loading.

Param Type DefaultValue Description
oListBinding sap.ui.model.odata.v4.ODataListBinding

The list binding to take the entity

refresh

Refreshes the binding. Prompts the model to retrieve data from the server using the given group ID and notifies the control that new data is available.

Refresh is supported for bindings which are not relative to a sap.ui.model.odata.v4.Context.

Note: When calling #refresh multiple times, the result of the request triggered by the last call determines the binding's data; it is independent of the order of calls to sap.ui.model.odata.v4.ODataModel#submitBatch with the given group ID.

If there are pending changes, an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #refresh.

Use #requestRefresh if you want to wait for the refresh.

References:

Param Type DefaultValue Description
sGroupId string boolean

The group ID to be used for refresh; if not specified, the binding's group ID is used, see #getGroupId. For suspended bindings, only the binding's group ID is supported because #resume uses the binding's group ID. A value of type boolean is not accepted and an error will be thrown (a forced refresh is not supported).

Valid values are undefined, '$auto', '$auto.*', '$direct' or application group IDs as specified in sap.ui.model.odata.v4.ODataModel.

requestObject

Returns a promise on the value for the given path relative to this binding. The function allows access to the complete data the binding 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 oBinding.refresh() first.

References:

Param Type DefaultValue Description
sPath string ""

A path relative to this context binding

requestRefresh

Refreshes the binding 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

resetChanges

Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input.

resume

Resumes this binding. The binding can then again fire change events and trigger data service requests. Before 1.53.0, this method was not supported and threw an error.

References:

setParameter

Sets a parameter for an operation call.

Param Type DefaultValue Description
sParameterName string

The parameter name

vValue any

The parameter value

suspend

Suspends this binding. A suspended binding does not fire change events nor does it trigger data service requests. Call #resume to resume the binding. Before 1.53.0, this method was not supported and threw an error.

References:

toString

Returns a string representation of this object including the binding path. If the binding is relative, the parent path is also given, separated by a '|'.