class sap.ui.model.odata.v2.ODataModel

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

Model implementation based on the OData protocol.

See chapter OData V2 Model for a general introduction.

This model is not prepared to be inherited from.


Constructor

Constructor for a new ODataModel.

new sap.ui.model.odata.v2.ODataModel(vServiceUrl, mParameters?)
Param Type Default Value Description
vServiceUrl string object

Base URI of the service to request data from; additional URL parameters appended here will be appended to every request. If you pass an object, it will be interpreted as the parameter object (second parameter). Then mParameters.serviceUrl becomes a mandatory parameter.

mParameters? object

Map which contains the following parameter properties:

annotationURI? string string[]

The URL (or an array of URLs) from which the annotation metadata should be loaded

bindableResponseHeaders? string[]

Set this array to make custom response headers bindable via the entity's "__metadata/headers" property

canonicalRequests? boolean false

Whether the model tries to calculate canonical URLs to request the data.

For example: An application displays the details of a sales order in a form with an absolute binding path /SalesOrderSet("1"). The form embeds a table for the sales order line items with a relative binding path ToLineItems. If the user selects a sales order line item (e.g. Item "10"), the details of this sales order line item are displayed in another form, which also contains a table for the sales order line item's schedules with a relative binding path ToSchedules.

If the canonicalRequests parameter has the default value false, then the OData model would request the data for the sales order line item's details form with the following requests:

  GET /<serviceUrl>/SalesOrderSet("1")/ToLineItems(SalesOrderID="1",ItemPosition="10")
  GET /<serviceUrl>/SalesOrderSet("1")/ToLineItems(SalesOrderID="1",ItemPosition="10")/ToSchedules

Some back-end implementations do not support more than one navigation property in the resource URL. In this case, set the canonicalRequests parameter to true. The OData model then converts the long resource URLs to canonical URLs and requests the data for the sales order line item's details form with the following requests:

  GET /<serviceUrl>/SalesOrderLineItemsSet(SalesOrderID="1",ItemPosition="10")
  GET /<serviceUrl>/SalesOrderLineItemsSet(SalesOrderID="1",ItemPosition="10")/ToSchedules

defaultBindingMode? sap.ui.model.BindingMode OneWay

Sets the default binding mode for the model

defaultCountMode? sap.ui.model.odata.CountMode Request

Sets the default count mode for the model

defaultOperationMode? sap.ui.model.odata.OperationMode Default

Sets the default operation mode for the model

defaultUpdateMethod? sap.ui.model.odata.UpdateMethod Merge

Default update method which is used for all update requests

disableHeadRequestForToken? boolean false

Set this flag to true if your service does not support HEAD requests for fetching the service document (and thus the security token) to avoid sending a HEAD-request before falling back to GET

disableSoftStateHeader? boolean false

Set this flag to true if you don´t want to start a new soft state session with context ID (SID) through header mechanism. This is useful if you want to share a SID between different browser windows

earlyTokenRequest? boolean false

Whether the security token is requested at the earliest convenience, if parameter tokenHandling is true; supported since 1.79.0.

headers? Object<string,string>

Map of custom headers (name/value pairs) like {"myHeader":"myHeaderValue",...}

json? boolean true

If set to true, request payloads will be JSON, XML for false

loadAnnotationsJoined? boolean

Whether the metadataLoaded event will be fired only after all annotations have been loaded as well

maxDataServiceVersion? string '2.0'

Please use the following string format e.g. '2.0' or '3.0'. OData version supported by the ODataModel: '2.0'

metadataNamespaces? Object<string,string>

Map of namespace aliases (alias => URI) that can be used in metadata binding paths; each alias is mapped to a corresponding namespace URI; when an alias is used in a metadata binding path, it addresses a metadata extension that belongs to the corresponding namespace URI; if metadataNamespaces is not given, the following default mappings will be used:

  • "sap": "sap:"http://www.sap.com/Protocols/SAPData"
  • "m": "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
  • "": "http://schemas.microsoft.com/ado/2007/06/edmx

metadataUrlParams? Object<string,string>

Map of URL parameters for metadata requests - only attached to a $metadata request

persistTechnicalMessages? boolean

Whether technical messages should always be treated as persistent, since 1.83.0

preliminaryContext? boolean false

Whether a preliminary context will be created/used by a binding. When set to true, the model can bundle the OData calls for dependent bindings into fewer $batch requests. For more information, see Optimizing Dependent Bindings

refreshAfterChange? boolean true

Enable/disable automatic refresh after change operations

sequentializeRequests? boolean false

Whether to sequentialize all requests, needed in case the service cannot handle parallel requests

serviceUrl? string

Base URI of the service to request data from; this property is mandatory when the first method parameter serviceUrl is omitted, but ignored otherwise

serviceUrlParams? Object<string,string>

Map of URL parameters (name/value pairs) - these parameters will be attached to all requests, except for the $metadata request

skipMetadataAnnotationParsing? boolean

Whether to skip the automated loading of annotations from the metadata document. Loading annotations from metadata does not have any effects (except the lost performance by invoking the parser) if there are not annotations inside the metadata document

tokenHandling? boolean true

Enable/disable security token handling

tokenHandlingForGet? boolean false

Send security token for GET requests in case read access logging is activated for the OData Service in the backend.

useBatch? boolean true

Whether all requests should be sent in batch requests

withCredentials? boolean

Experimental - true when user credentials are to be included in a cross-origin request; please note that this only works if all requests are asynchronous

password? string

Deprecated for security reasons. Use strong server side authentication instead. Password for the service.

user? string

Deprecated for security reasons. Use strong server side authentication instead. UserID for the service.


Events Overview

Event Description
annotationsFailed

Fired, when the annotations document failed to loaded. Event is fired only once for all annotation documents.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

annotationsLoaded

Fired, when the annotations document was successfully loaded. If there are more than one annotation documents loaded then this event is fired if at least one document was successfully loaded. Event is fired only once for all annotation documents.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

batchRequestCompleted

Fired after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

batchRequestFailed

Fired, when a batch request failed.

batchRequestSent

Fired after a request has been sent to a backend.

metadataFailed

Fired, when the metadata document has failed to load.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

metadataLoaded

Fired, when the metadata document was successfully loaded.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

requestCompleted

Fired, after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

requestFailed

Fired, when data retrieval from a backend failed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

requestSent

Fired, after a request has been sent to a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

annotationsFailed

Fired, when the annotations document failed to loaded. Event is fired only once for all annotation documents.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
result Error[]

An array of Errors

annotationsLoaded

Fired, when the annotations document was successfully loaded. If there are more than one annotation documents loaded then this event is fired if at least one document was successfully loaded. Event is fired only once for all annotation documents.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
result sap.ui.model.odata.v2.ODataAnnotations.Source[]

An array consisting of one or several annotation sources and/or errors containing a source property and error details.

batchRequestCompleted

Fired after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

success boolean

Request was successful or not

async boolean

If the request is synchronous or asynchronous (if available)

requests array

Array of embedded requests ($batch) Each request object within the array contains the following properties: url, method, headers, response object

response object

The response object - empty object if no response: The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

batchRequestFailed

Fired, when a batch request failed.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

async boolean

If the request is synchronous or asynchronous (if available)

success boolean

Request was successful or not

response object

The response object - empty object if no response The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

requests array

Array of embedded requests ($batch) Each request object within the array contains the following properties: url, method, headers, response object

batchRequestSent

Fired after a request has been sent to a backend.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
url string

The URL which is sent to the backend

type string

The type of the request (if available)

async boolean

If the request is synchronous or asynchronous (if available)

requests array

Array of embedded requests ($batch) Each request object within the array contains the following properties: url, method, headers

metadataFailed

Fired, when the metadata document has failed to load.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
metadata string

The parsed metadata

message string

A text that describes the failure.

statusCode string

HTTP status code returned by the request (if available)

statusText string

The status as a text, details not specified, intended only for diagnosis output

responseText string

Response that has been received for the request, as a text string

response object

The response object - empty object if no response

metadataLoaded

Fired, when the metadata document was successfully loaded.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
metadata string

The parsed metadata

requestCompleted

Fired, after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

success boolean

Request was successful or not

async boolean

If the request is synchronous or asynchronous (if available)

response object

The response object - empty object if no response: The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

requestFailed

Fired, when data retrieval from a backend failed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

async boolean

If the request is synchronous or asynchronous (if available)

success boolean

Request was successful or not

response object

The response object - empty object if no response The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

requestSent

Fired, after a request has been sent to a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

async boolean

If the request is synchronous or asynchronous (if available)


Methods Overview

Method Description
addAnnotationUrl

Adds (a) new URL(s) whose content should be parsed as OData annotations, which are then merged into the annotations object which can be retrieved by calling the #getServiceAnnotations-method. If a $metadata URL is passed, the data will also be merged into the metadata object, which can be reached by calling the #getServiceMetadata method.

addAnnotationXML

Adds new XML content to be parsed for OData annotations, which are then merged into the annotations object which can be retrieved by calling the #getServiceAnnotations-method.

annotationsLoaded

Returns a promise that resolves with an array containing information about the initially loaded annotations.

Important: This covers the annotations that were given to the model constructor, not the ones that might have been added later on using the protected API method #addAnnotationUrl. In order to get information about those, the event annotationsLoaded can be used.

attachAnnotationsFailed

Attaches event handler fnFunction to the annotationsFailed event of this sap.ui.model.odata.v2.ODataModel.

attachAnnotationsLoaded

Attaches event handler fnFunction to the annotationsLoaded event of this sap.ui.model.odata.v2.ODataModel.

attachBatchRequestCompleted

Attaches event handler fnFunction to the batchRequestCompleted event of this sap.ui.model.odata.v2.ODataModel.

attachBatchRequestFailed

Attaches event handler fnFunction to the batchRequestFailed event of this sap.ui.model.odata.v2.ODataModel.

attachBatchRequestSent

Attaches event handler fnFunction to the batchRequestSent event of this sap.ui.model.odata.v2.ODataModel.

attachMetadataFailed

Attaches event handler fnFunction to the metadataFailed event of this sap.ui.model.odata.v2.ODataModel.

attachMetadataLoaded

Attaches event handler fnFunction to the metadataLoaded event of this sap.ui.model.odata.v2.ODataModel.

bindContext

Creates new context binding for this model.

References:

  • sap.ui.model.Model.prototype.bindContext

bindList

Creates a new list binding for this model.

References:

  • sap.ui.model.Model.prototype.bindList

bindProperty

Creates a new property binding for this model.

References:

  • sap.ui.model.Model.prototype.bindProperty

bindTree

Creates a new tree binding for this model.

Hierarchy Annotations

To use the v2.ODataTreeBinding with an OData service which exposes hierarchy annotations, see the "SAP Annotations for OData Version 2.0" specification. The required property annotations as well as accepted / default values are documented in this specification.

Services which include the hierarchy-node-descendant-count-for annotation and expose the data points sorted in a depth-first, pre-order manner, can use an optimized auto-expand feature by specifying the numberOfExpandedLevels in the binding parameters. This will pre-expand the hierarchy to the given number of levels, with only a single initial OData request.

For services without the hierarchy-node-descendant-count-for annotation, the numberOfExpandedLevels property is not supported and deprecated.

Operation Modes

For a full definition and explanation of all OData binding operation modes, see sap.ui.model.odata.OperationMode.

OperationMode.Server

Filtering on the ODataTreeBinding is only supported with application filters. Be aware that this applies only to filters which do not prevent the creation of a hierarchy. So filtering on a property (e.g. a "Customer") is fine, as long as the application ensures that the responses from the back end are sufficient to create a valid hierarchy on the client. Subsequent paging requests for sibling and child nodes must also return responses, since the filters are sent with every request. Using control-defined filters (see sap.ui.model.FilterType.Control) via the #filter function is not supported for the operation mode Server.

OperationMode.Client and OperationMode.Auto

The ODataTreeBinding supports control-defined filters only in operation modes Client and Auto. With these operation modes, the filters and sorters are applied on the client, like for the sap.ui.model.odata.v2.ODataListBinding.

The operation modes Client and Auto are only supported for services which expose the hierarchy annotations mentioned above, but do not expose the hierarchy-node-descendant-count-for annotation. Services with hierarchy annotations including the hierarchy-node-descendant-count-for annotation, do not support the operation modes Client and Auto.

References:

callFunction

Triggers a request for the given function import.

If the return type of the function import is either an entity type or a collection of an entity type, then this OData model's cache is updated with the values of the returned entities. Otherwise they are ignored, and the response can be processed in the success callback.

canonicalRequestsEnabled

Whether the canonical requests calculation is switched on, see the canonicalRequests parameter of the model constructor.

create

Trigger a POST request to the OData service that was specified in the model constructor.

Please note that deep creates are not supported and may not work.

createBindingContext

Creates a binding context for the given path.

If the data of the context is not yet available, it can not be created, but first the entity needs to be fetched from the server asynchronously. In case no callback function is provided, the request will not be triggered.

If a callback function is given, the created binding context for a fetched entity is passed as argument to the given callback function.

References:

  • sap.ui.model.Model.prototype.createBindingContext

createEntry

Creates a new entry object which is described by the metadata of the entity type of the specified sPath Name. A context object is returned which can be used to bind against the newly created object.

For each created entry a request is created and stored in a request queue. The request queue can be submitted by calling #submitChanges. As long as the context is transient (see sap.ui.model.odata.v2.Context#isTransient), sap.ui.model.odata.v2.ODataModel#resetChanges with the bDeleteCreatedEntities parameter set to true can be used to delete the created entity again.

If the creation of the entity on the server failed, it is repeated automatically.

The optional parameter mParameters.properties can be used as follows:

  • properties could be an array containing the property names which should be included in the new entry. Other properties defined in the entity type won't be included.
  • properties could be an object which includes the desired properties and the corresponding values which should be used for the created entry.
If properties is not specified, all properties in the entity type will be included in the created entry.

If there are no values specified, the properties will have undefined values.

The properties can be modified via property bindings relative to the returned context instance.

The parameter expand is supported since 1.78.0. If this parameter is set, the given navigation properties are expanded automatically with the same $batch request in which the POST request for the creation is contained. Ensure that the batch mode is used and the back-end service supports GET requests relative to a content ID outside the changeset. The success and error callback functions are called only once, even if there are two requests in the $batch related to a single call of #createEntry:

  • a POST request for creating an entity,
  • a GET request for requesting the navigation properties for the just created entity.
The following outcomes are possible:
  • If both requests succeed, the success handler is called with the merged data of the POST and the GET request and with the response of the POST request.
  • If the POST request fails, the GET request also fails. In that case the error callback handler is called with the error response of the POST request.
  • If the POST request succeeds but the GET request for the navigation properties fails, the success handler is called with the data and the response of the POST request. The response object of the success handler call and the response parameter of the corresponding requestFailed and requestCompleted events have an additional property expandAfterCreateFailed set to true.

Note: If a server requires a property in the request, you must supply this property in the initial data, for example if the server requires a unit for an amount. This also applies if this property has a default value.

Note: A deep create (including data defined by navigation properties) is not supported. The dependent entity has to be created using a second list binding, after this entity has been saved successfully in the back-end system.

createKey

Creates the key from the given collection name and property map.

Please make sure that the metadata document is loaded before using this function.

deleteCreatedEntry

Deletes a created entry from the request queue and from the model.

Note: Controls are not updated. Use #resetChanges instead to update also the controls, for example:
oModel.resetChanges([oContext.getPath()], undefined, true);

Since since 1.95.0; use {@link #resetChanges} instead
destroy

References:

  • sap.ui.model.Model.prototype.destroy

detachAnnotationsFailed

Detaches event handler fnFunction from the annotationsFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachAnnotationsLoaded

Detaches event handler fnFunction from the annotationsLoaded event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachBatchRequestCompleted

Detaches event handler fnFunction from the batchRequestCompleted event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachBatchRequestFailed

Detaches event handler fnFunction from the batchRequestFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachBatchRequestSent

Detaches event handler fnFunction from the batchRequestSent event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachMetadataFailed

Detaches event handler fnFunction from the metadataFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

detachMetadataLoaded

Detaches event handler fnFunction from the metadataLoaded event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

enableCanonicalRequests

Enable/Disable canonical requests calculation. When enabled, a given resource path will be shortened as much as possible.

sap.ui.model.odata.v2.ODataModel.extend

Creates a new subclass of class sap.ui.model.odata.v2.ODataModel 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.Model.extend.

fireAnnotationsFailed

Fires event annotationsFailed to attached listeners.

fireAnnotationsLoaded

Fires event annotationsLoaded to attached listeners.

fireBatchRequestCompleted

Fires event batchRequestCompleted to attached listeners.

fireBatchRequestFailed

Fires event batchRequestFailed to attached listeners.

fireBatchRequestSent

Fires event batchRequestSent to attached listeners.

fireMetadataFailed

Fires event metadataFailed to attached listeners.

fireMetadataLoaded

Fires event metadataLoaded to attached listeners.

forceEntityUpdate

Force the update on the server of an entity by setting its ETag to '*'.

ETag handling must be active so the force update will work.

getChangeBatchGroups

Returns the definition of batch groups per entity type for two-way binding changes.

Since 1.36 use {@link #getChangeGroups} instead
getChangeGroups

Returns the definition of groups per entity type for two-way binding changes

getData

Return requested data as object if the data has already been loaded and stored in the model.

Since 1.24 please use {@link #getProperty} instead
getDefaultCountMode

Returns the default count mode for retrieving the count of collections

getDeferredBatchGroups

Returns the array of batch group IDs that are set as deferred

Since 1.32 use {@link #getDeferredGroups} instead
getDeferredGroups

Returns the array of group IDs that are set as deferred.

getETag

Returns the ETag for a given binding path/context or data object.

getHeaders

Returns all headers and custom headers which are stored in this OData model.

getKey

Returns the key part for the given the canonical entry URI, model context or data object or undefined when the vValue can't be interpreted.

getMessageScope

Returns this model's message scope.

References:

  • sap.ui.model.odata.MessageScope

sap.ui.model.odata.v2.ODataModel.getMetadata

Returns a metadata object for class sap.ui.model.odata.v2.ODataModel.

getMetaModel

Returns an instance of an OData meta model which offers a unified access to both OData V2 metadata and V4 annotations. It uses the existing sap.ui.model.odata.ODataMetadata as a foundation and merges V4 annotations from the existing sap.ui.model.odata.v2.ODataAnnotations directly into the corresponding model element.

BEWARE: Access to this OData meta model will fail before the promise returned by loaded has been resolved!

getObject

Returns a JSON object that is a copy of the entity data referenced by the given sPath and oContext. It does not load any data and may not return all requested data if it is not available.

With the mParameters.select parameter it is possible to specify comma-separated property or navigation property names which should be included in the result object. This works like the OData $select URL parameter. With the mParameters.expand parameter it is possible to specify comma-separated navigation property names which should be included inline in the result object. This works like the OData $expand parameter.

Note: mParameters.expand can only be used if the corresponding navigation properties have been read via sap.ui.model.odata.v2.ODataModel#read using the OData $expand URL parameter. If a navigation property has not been read via the OData $expand URL parameter, it is left out in the result. Keep in mind that navigation properties referencing a collection are usually not loaded via the OData $expand URL parameter but directly via its navigation property.

Note: If mParameters.select is not specified, the returned object may contain model-internal attributes. This may lead to problems when submitting this data to the service for an update or create operation. To get a copy of the entity without internal attributes, use {select: "*"} instead.

Note: If mParameters.select is given and not all selected properties are available, this method returns undefined instead of incomplete data.

Note: If mParameters.select is not given, all properties and navigation properties available on the client are returned.

Example:
With mParameters given as {select: "Products/ProductName, Products", expand:"Products"} no properties of the entity itself are returned, but only the ProductName property of the Products navigation property. If Products/ProductName has not been loaded before, undefined is returned.

getOriginalProperty

Returns the original value for the property with the given path and context. The original value is the value that was last responded by the server.

getPendingChanges

Returns the changed properties of all changed entities in a map which are still pending. The key is the string name of the entity and the value is an object which contains the changed properties.

In contrast to the two related functions #hasPendingChanges and #resetChanges, only client data changes are supported.

getPersistTechnicalMessages

Gets the flag whether technical messages should always be treated as persistent.

getProperty

Returns the value for the property with the given sPath.

If the path points to a navigation property which has been loaded via $expand then the bIncludeExpandEntries parameter determines if the navigation property should be included in the returned value or not. Please note that this currently works for 1..1 navigation properties only.

getRefreshAfterChange
getSecurityToken

Returns the current security token.

If the token has not been requested from the server it will be requested first (synchronously).

getServiceAnnotations

Return the annotation object. Please note that the metadata is loaded asynchronously and this function might return undefined because the metadata has not been loaded yet. In this case attach to the annotationsLoaded event to get notified when the annotations are available and then call this function.

getServiceMetadata

Return the parsed XML metadata as a Javascript object.

Please note that the metadata is loaded asynchronously and this function might return undefined because the metadata has not been loaded yet. In this case attach to the metadataLoaded event to get notified when the metadata is available and then call this function.

hasPendingChanges

Checks if there exist pending changes in the model.

By default, only client data changes triggered through: #createEntry #setProperty are taken into account.

If bAll is set to true, also deferred requests triggered through: #create #update #remove are taken into account.

hasPendingRequests

Checks if there are pending requests, either ongoing or sequential.

invalidate

Invalidate the model data.

Mark all entries in the model cache as invalid. Next time a context or list is bound (binding), the respective entries will be detected as invalid and will be refreshed from the server.

To refresh all model data use sap.ui.model.odata.v2.ODataModel#refresh

invalidateEntityType

Invalidate all entries of the given entity type in the model data.

Mark entries of the provided entity type in the model cache as invalid. Next time a context binding or list binding is done, the entry will be detected as invalid and will be refreshed from the server.

invalidateEntry

Invalidate a single entry in the model data.

Mark the selected entry in the model cache as invalid. Next time a context binding or list binding is done, the entry will be detected as invalid and will be refreshed from the server.

isMetadataLoadingFailed

Checks whether metadata loading has failed in the past.

messageScopeSupported

Checks whether the service has set the OData V2 annotation "message-scope-supported" on the EntityContainer with the value true. This is a a precondition for the setting of sap.ui.model.odata.MessageScope.BusinessObject via #setMessageScope.

References:

  • sap.ui.model.odata.MessageScope

metadataLoaded

Returns a promise for the loaded state of the metadata.

The metadata needs to be loaded prior to performing OData calls. Chaining to the returned promise ensures that all required parameters have been loaded, e.g. the security token, see #getSecurityToken.

The returned promise depends on the optional parameter bRejectOnFailure.

bRejectOnFailure=false: The promise won't get rejected in case the metadata or annotation loading failed but is only resolved if

  1. the metadata are loaded successfully,
  2. the annotations are processed, provided the model parameter loadAnnotationsJoined has been set.
Use this promise for delaying OData calls until all required information is available, i.e. this promise is resolved.

bRejectOnFailure=true: Since 1.79, the parameter bRejectOnFailure allows to request a promise that is rejected when one of the following fails:

  • the loading of the metadata,
  • the loading of the annotations, provided the model parameter loadAnnotationsJoined has been set.
The promise is fulfilled upon successful loading of both. This promise can be used to start processing OData calls when it is fulfilled and to display an error message when it is rejected. See also the example below.

If the method refreshMetadata is called after the returned promise is already resolved or rejected, you should use the promise returned by refreshMetadata to get information about the refreshed state.

read

Trigger a GET request to the OData service that was specified in the model constructor.

The data will be stored in the model. The requested data is returned with the response.

refresh

Refresh the model.

This will reload all data stored in the model. This will check all bindings for updated data and update the controls if data has been changed.

Note: In contrast to an individual Binding refresh, the model refresh ignores Binding-specific parameters/queries.

refreshMetadata

Refreshes the metadata for this model, for example when the request for metadata has failed.

Note: Do not use refreshMetadata if the metadata is outdated or should be updated. This will lead to inconsistent data in the application.

Returns a new promise which can be resolved or rejected depending on the metadata loading state.

refreshSecurityToken

Refresh XSRF token by performing a GET request against the service root URL.

remove

Trigger a DELETE request to the OData service that was specified in the model constructor.

resetChanges

Resets pending changes and aborts corresponding requests.

By default, only changes triggered through #createEntry or #setProperty are taken into account. If bAll is set, also deferred requests triggered through #create, #update or #remove are taken into account.

If bDeleteCreatedEntities is set, the entity is completely removed, provided it has been created

securityTokenAvailable

Returns a promise, which will resolve with the security token as soon as it is available.

setChangeBatchGroups

Definition of batch groups per entity type for two-way binding changes.

Since 1.32 Use {@link #setChangeGroups} instead
setChangeGroups

Definition of groups per entity type for two-way binding changes.

setDefaultCountMode

Sets the default mode how to retrieve the item count for a collection in this model.

The count can be determined in the following ways

  • by sending a separate $count request
  • by adding parameter $inlinecount=allpages to one or all data requests
  • a combination of the previous two
  • not at all (questions about the size of the collection can't be answered then)
See sap.ui.model.odata.CountMode for all enumeration values and more details.

Note that a call to this method does not modify the count mode for existing list bindings, only bindings that are created afterwards will use the new mode when no mode is defined at their creation.

If no default count mode is set for an ODataModel (v2), the mode Request will be used.

setDeferredBatchGroups

Setting batch groups as deferred.

Requests that belong to a deferred batch group have to be sent by explicitly calling #submitChanges.

Since 1.32 use {@link #setDeferredGroups} instead
setDeferredGroups

Setting request groups as deferred.

Requests that belong to a deferred group will be sent by explicitly calling #submitChanges.

setHeaders

Set custom headers which are provided in a key/value map.

These headers are used for requests against the OData backend. Private headers which are set in the ODataModel cannot be modified. These private headers are: accept, accept-language, x-csrf-token, MaxDataServiceVersion, DataServiceVersion.

To remove these custom headers simply set the mHeaders parameter to null. Please also note that when calling this method again, all previous custom headers are removed unless they are specified again in the mHeaders parameter.

setMessageScope

Sets this model's message scope.

References:

  • sap.ui.model.odata.MessageScope

setPersistTechnicalMessages

Sets the flag whether technical messages should always be treated as persistent. Works only with sap.ui.model.odata.ODataMessageParser.

setProperty

Sets a new value for the given property sPath in the model.

If the changeBatchGroup for the changed entity type is set to deferred, changes could be submitted with #submitChanges. Otherwise the change will be submitted directly.

setRefreshAfterChange

Defines whether all bindings are updated after a change operation.

This flag can be overruled on request level by providing the refreshAfterChange parameter to the corresponding function (for example #update).

setTokenHandlingEnabled

Enable/Disable security token handling.

setUseBatch

Enable or disable batch mode for future requests.

submitChanges

Submits the collected changes which were collected by the #setProperty method and other deferred requests.

The update method is defined by the global defaultUpdateMethod parameter which is sap.ui.model.odata.UpdateMethod.Merge by default. In case of a sap.ui.model.odata.UpdateMethod.Merge request only the changed properties will be updated. If a URI with a $expand query option was used then the expand entries will be removed from the collected changes. Changes to this entries should be done on the entry itself. So no deep updates are supported.

Important: The success/error handler will only be called if batch support is enabled. If multiple batch groups are submitted the handlers will be called for every batch group. If there are no changes/requests or all contained requests are aborted before a batch request returns, the success handler will be called with an empty response object. If the abort method on the return object is called, all contained batch requests will be aborted and the error handler will be called for each of them.

update

Trigger a PUT/MERGE request to the OData service that was specified in the model constructor.

The update method used is defined by the global defaultUpdateMethod parameter which is sap.ui.model.odata.UpdateMethod.Merge by default. Please note that deep updates are not supported and may not work. These should be done separately and directly on the corresponding entry.

updateBindings

Update all bindings.

addAnnotationUrl

Adds (a) new URL(s) whose content should be parsed as OData annotations, which are then merged into the annotations object which can be retrieved by calling the #getServiceAnnotations-method. If a $metadata URL is passed, the data will also be merged into the metadata object, which can be reached by calling the #getServiceMetadata method.

Param Type DefaultValue Description
vUrl string string[]

Either one URL as string or an array of URL strings

addAnnotationXML

Adds new XML content to be parsed for OData annotations, which are then merged into the annotations object which can be retrieved by calling the #getServiceAnnotations-method.

Param Type DefaultValue Description
sXMLContent string

The string that should be parsed as annotation XML

bSuppressEvents boolean false

Whether not to fire annotationsLoaded event on the annotationParser

annotationsLoaded

Returns a promise that resolves with an array containing information about the initially loaded annotations.

Important: This covers the annotations that were given to the model constructor, not the ones that might have been added later on using the protected API method #addAnnotationUrl. In order to get information about those, the event annotationsLoaded can be used.

attachAnnotationsFailed

Attaches event handler fnFunction to the annotationsFailed event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachAnnotationsLoaded

Attaches event handler fnFunction to the annotationsLoaded event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachBatchRequestCompleted

Attaches event handler fnFunction to the batchRequestCompleted event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachBatchRequestFailed

Attaches event handler fnFunction to the batchRequestFailed event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachBatchRequestSent

Attaches event handler fnFunction to the batchRequestSent event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachMetadataFailed

Attaches event handler fnFunction to the metadataFailed event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

attachMetadataLoaded

Attaches event handler fnFunction to the metadataLoaded event of this sap.ui.model.odata.v2.ODataModel.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.odata.v2.ODataModel itself

bindContext

Creates new context binding for this model.

References:

Param Type DefaultValue Description
sPath string

Resolved path

oContext sap.ui.model.Context

Context object

mParameters Object<string,any>

Map of parameters

bindList

Creates a new list binding for this model.

References:

Param Type DefaultValue Description
sPath string

Binding path, either absolute or relative to a given oContext

oContext sap.ui.model.Context

Binding context referring to this model

aSorters sap.ui.model.Sorter sap.ui.model.Sorter[]

Initial sort order, can be either a sorter or an array of sorters

aFilters sap.ui.model.Filter sap.ui.model.Filter[]

Predefined filters, can be either a filter or an array of filters

mParameters object

Map which contains additional parameters for the binding

expand string

Value for the OData $expand query parameter which should be included in the request

select string

Value for the OData $select query parameter which should be included in the request

custom Object<string,string>

Optional map of custom query parameters (name/value pairs); names of custom parameters must not start with $

countMode sap.ui.model.odata.CountMode

Count mode for this binding; if not specified, the default count mode for this model is used

createdEntitiesKey string ""

A key used in combination with the resolved path of the binding to identify the entities created via the binding's #create method.

Note: Different controls or control aggregation bindings to the same collection must have different createdEntitiesKey values.

operationMode sap.ui.model.odata.OperationMode

Operation mode for this binding; if not specified, the default operation mode of this model is used

faultTolerant boolean

Turns on the fault tolerance mode, data is not reset if a backend request returns an error

batchGroupId string

Sets the batch group ID to be used for requests originating from this binding

threshold int

Threshold that defines how many entries should be fetched at least by the binding if operationMode is set to Auto (See documentation for sap.ui.model.odata.OperationMode.Auto)

bindProperty

Creates a new property binding for this model.

References:

Param Type DefaultValue Description
sPath string

Path pointing to the property that should be bound; either an absolute path or a path relative to a given oContext

oContext object

A context object for the new binding

mParameters Object<string,any>

Map of optional parameters for the binding

ignoreMessages boolean

Whether this binding does not propagate model messages to the control; supported since 1.82.0. Some composite types like sap.ui.model.type.Currency automatically ignore model messages for some of their parts depending on their format options; setting this parameter to true or false overrules the automatism of the type.

For example, a binding for a currency code is used in a composite binding for rendering the proper number of decimals, but the currency code is not displayed in the attached control. In that case, messages for the currency code shall not be displayed at that control, only messages for the amount.

bindTree

Creates a new tree binding for this model.

Hierarchy Annotations

To use the v2.ODataTreeBinding with an OData service which exposes hierarchy annotations, see the "SAP Annotations for OData Version 2.0" specification. The required property annotations as well as accepted / default values are documented in this specification.

Services which include the hierarchy-node-descendant-count-for annotation and expose the data points sorted in a depth-first, pre-order manner, can use an optimized auto-expand feature by specifying the numberOfExpandedLevels in the binding parameters. This will pre-expand the hierarchy to the given number of levels, with only a single initial OData request.

For services without the hierarchy-node-descendant-count-for annotation, the numberOfExpandedLevels property is not supported and deprecated.

Operation Modes

For a full definition and explanation of all OData binding operation modes, see sap.ui.model.odata.OperationMode.

OperationMode.Server

Filtering on the ODataTreeBinding is only supported with application filters. Be aware that this applies only to filters which do not prevent the creation of a hierarchy. So filtering on a property (e.g. a "Customer") is fine, as long as the application ensures that the responses from the back end are sufficient to create a valid hierarchy on the client. Subsequent paging requests for sibling and child nodes must also return responses, since the filters are sent with every request. Using control-defined filters (see sap.ui.model.FilterType.Control) via the #filter function is not supported for the operation mode Server.

OperationMode.Client and OperationMode.Auto

The ODataTreeBinding supports control-defined filters only in operation modes Client and Auto. With these operation modes, the filters and sorters are applied on the client, like for the sap.ui.model.odata.v2.ODataListBinding.

The operation modes Client and Auto are only supported for services which expose the hierarchy annotations mentioned above, but do not expose the hierarchy-node-descendant-count-for annotation. Services with hierarchy annotations including the hierarchy-node-descendant-count-for annotation, do not support the operation modes Client and Auto.

References:

Param Type DefaultValue Description
sPath string

The binding path, either absolute or relative to a given oContext

oContext sap.ui.model.Context

The parent context which is required as base for a relative path

vFilters sap.ui.model.Filter sap.ui.model.Filter[]

The application filters to be used initially; depending on the operation mode, there are restrictions for using filters, see above

mParameters object

Map of binding parameters

treeAnnotationProperties object

The mapping between data properties and the hierarchy used to visualize the tree, if not provided by the service's metadata. For the correct metadata annotations, check the "SAP Annotations for OData Version 2.0" specification

hierarchyLevelFor string

The property name in the same type holding the hierarchy level information; the type of the referenced property has to be an integer type

hierarchyNodeFor string

The property name in the same type holding the hierarchy node id

hierarchyParentNodeFor string

The property name in the same type holding the parent node id

hierarchyDrillStateFor string

The property name in the same type holding the drill state for the node; the referenced property may have the values "collapsed", "expanded" or "leaf"

hierarchyNodeDescendantCountFor string

The property name in the same type holding the descendant count for the node; the type of the referenced property has to be an integer type

numberOfExpandedLevels number 0

The number of levels that are auto-expanded initially. Setting this property might lead to multiple back-end requests. The auto-expand feature is deprecated for services without the hierarchy-node-descendant-count-for annotation

rootLevel number 0

The level of the topmost tree nodes

groupId string

The group id to be used for requests originating from this binding

operationMode sap.ui.model.odata.OperationMode

The operation mode for this binding; defaults to the model's default operation mode if not specified. OperationMode.Auto is only supported for services which expose the hierarchy annotations, yet do NOT expose the hierarchy-node-descendant-count-for annotation.

threshold number

The threshold used if the operation mode is set to OperationMode.Auto. The binding tries to fetch (at least) as many entries as specified by the threshold value.

useServersideApplicationFilters boolean

Whether $filter statements should be used for the $count / $inlinecount requests and for the data request if the operation mode is OperationMode.Auto. Use this feature only if your back end supports pre-filtering the tree and is capable of responding with a complete tree hierarchy, including all inner nodes. To construct the hierarchy on the client, it is mandatory that all filter matches include their complete parent chain up to the root level. If OperationMode.Client is used, the complete collection without filters is requested; filters are applied on the client side.

treeState any

A tree state handle can be given to the ODataTreeBinding when two conditions are met:

The feature is only available when using the ODataTreeBindingAdapter, which is automatically applied when using the sap.ui.table.TreeTable. The tree state handle will contain all necessary information to expand the tree to the given state.

This feature is not supported if OperationMode.Server or OperationMode.Auto is used. See also sap.ui.model.odata.ODataTreeBindingAdapter#getCurrentTreeState

countMode sap.ui.model.odata.CountMode

Defines the count mode of this binding; if not specified, the default count mode of the binding's model is applied. The resulting count mode must not be sap.ui.model.odata.CountMode.None.

usePreliminaryContext boolean

Whether a preliminary context is used; defaults to the value of the parameter preliminaryContext given on construction of the binding's model, see sap.ui.model.odata.v2.ODataModel

batchGroupId string

Deprecated, use groupId instead. Sets the batch group id to be used for requests originating from this binding

navigation object

A map describing the navigation properties between entity sets, which is used for constructing and paging the tree. Keys in this object are entity names, whereas the values name the navigation properties.

Deprecated: since 1.44 The use of navigation properties to build up the hierarchy structure is deprecated. It is recommended to use the hierarchy annotations mentioned above instead.

vSorters sap.ui.model.Sorter sap.ui.model.Sorter[]

The dynamic sorters to be used initially

callFunction

Triggers a request for the given function import.

If the return type of the function import is either an entity type or a collection of an entity type, then this OData model's cache is updated with the values of the returned entities. Otherwise they are ignored, and the response can be processed in the success callback.

Param Type DefaultValue Description
sFunctionName string

The name of the function import starting with a slash, for example /Activate.

mParameters object

The parameter map containing any of the following properties:

adjustDeepPath function

Defines a callback function to adjust the deep path for the resulting entity of the function import call; since 1.82. The deep path of an entity is the resolved path relative to the parent contexts of the binding in the UI hierarchy. For example, for a ToBusinessPartner relative context binding with a /SalesOrder('42') parent context, the resulting deep path for the BusinessPartner is /SalesOrder('42')/ToBusinessPartner. This deep path is used to properly assign messages and show them correctly on the UI.

The callback function returns a string with the deep path for the entity returned by the function import and gets the parameter map mParameters containing the following properties:

  • {string} mParameters.deepPath: The deep path of the resulting entity, as far as the framework is able to determine from the metadata and the OData response
  • {object} mParameters.response: A copy of the OData response object

changeSetId string

ID of the ChangeSet that this request belongs to

error function

A callback function which is called when the request failed. The handler can have the parameter: oError which contains additional error information.

eTag string

If the function import changes an entity, the ETag for this entity can be passed with this parameter

expand string

A comma-separated list of navigation properties to be expanded for the entity returned by the function import; since 1.83.0.
The navigation properties are requested with an additional GET request in the same $batch request as the POST request for the function import. The given mParameters.headers are not considered in the GET request.
Note: The following prerequisites must be fulfilled:

  • batch mode must be enabled; see constructor parameter useBatch,
  • the HTTP method used for the function import is "POST",
  • the function import returns a single entity,
  • the back-end service must support the "Content-ID" header,
  • the back end must allow GET requests relative to this content ID outside the changeset within the $batch request.
The success and error callback functions are called only once, even if there are two requests in the $batch related to a single call of #callFunction.
  • If both requests succeed, the success callback is called with the merged data of the POST and the GET request and with the response of the POST request.
  • If the POST request fails, the GET request also fails. In that case the error callback is called with the error response of the POST request.
  • If the POST request succeeds but the GET request for the navigation properties fails, the success callback is called with the data and the response of the POST request. The response object of the success callback call and the response parameter of the corresponding requestFailed and requestCompleted events have an additional property expandAfterFunctionCallFailed set to true.

groupId string

ID of a request group; requests belonging to the same group are bundled in one batch request

headers Object<string,string>

A map of headers for this request

method string 'GET'

The HTTP method used for the function import call as specified in the metadata definition of the function import

refreshAfterChange boolean

Defines whether to update all bindings after submitting this change operation; since 1.46. See #setRefreshAfterChange. If given, this overrules the model-wide refreshAfterChange flag for this operation only.

success function

A callback function which is called when the data has been successfully retrieved; the handler can have the following parameters: oData and response.

urlParameters Object<string,string>

Maps the function import parameter name as specified in the function import's metadata to its value; the value is formatted based on the parameter's type as specified in the metadata

batchGroupId string

Deprecated - use groupId instead

canonicalRequestsEnabled

Whether the canonical requests calculation is switched on, see the canonicalRequests parameter of the model constructor.

create

Trigger a POST request to the OData service that was specified in the model constructor.

Please note that deep creates are not supported and may not work.

Param Type DefaultValue Description
sPath string

A string containing the path to the collection where an entry should be created. The path is concatenated to the service URL which was specified in the model constructor.

oData object

Data of the entry that should be created.

mParameters object

Optional parameter map containing any of the following properties:

context object

If specified , sPath has to be relative to the path given with the context.

success function

A callback function which is called when the data has been successfully retrieved. The handler can have the following parameters: oData and response. The oData parameter contains the data of the newly created entry if it is provided by the backend. The response parameter contains information about the response of the request.

error function

A callback function which is called when the request failed. The handler can have the parameter oError which contains additional error information.

urlParameters Object<string,string>

A map containing the parameters that will be passed as query strings

headers Object<string,string>

A map of headers for this request

batchGroupId string

Deprecated - use groupId instead

groupId string

ID of a request group; requests belonging to the same group will be bundled in one batch request

changeSetId string

ID of the ChangeSet that this request should belong to

refreshAfterChange boolean

Since 1.46; defines whether to update all bindings after submitting this change operation. See #setRefreshAfterChange If given, this overrules the model-wide refreshAfterChange flag for this operation only.

createBindingContext

Creates a binding context for the given path.

If the data of the context is not yet available, it can not be created, but first the entity needs to be fetched from the server asynchronously. In case no callback function is provided, the request will not be triggered.

If a callback function is given, the created binding context for a fetched entity is passed as argument to the given callback function.

References:

Param Type DefaultValue Description
sPath string

Binding path

oContext object

Binding context

mParameters object

Map which contains additional parameters for the binding

expand string

Value for the OData $expand query parameter which should be included in the request

select string

Value for the OData $select query parameter which should be included in the request

preliminaryContext boolean

Whether a preliminary context will be created. When set to true, the model can bundle the OData calls for dependent bindings into fewer $batch requests. For more information, see Optimizing Dependent Bindings

custom Object<string,string>

Optional map of custom query parameters, names of custom parameters must not start with $.

fnCallBack function

The function to be called when the context has been created. The parameter of the callback function is the newly created binding context, an instance of sap.ui.model.odata.v2.Context.

bReload boolean

Whether to reload data

createEntry

Creates a new entry object which is described by the metadata of the entity type of the specified sPath Name. A context object is returned which can be used to bind against the newly created object.

For each created entry a request is created and stored in a request queue. The request queue can be submitted by calling #submitChanges. As long as the context is transient (see sap.ui.model.odata.v2.Context#isTransient), sap.ui.model.odata.v2.ODataModel#resetChanges with the bDeleteCreatedEntities parameter set to true can be used to delete the created entity again.

If the creation of the entity on the server failed, it is repeated automatically.

The optional parameter mParameters.properties can be used as follows:

If properties is not specified, all properties in the entity type will be included in the created entry.

If there are no values specified, the properties will have undefined values.

The properties can be modified via property bindings relative to the returned context instance.

The parameter expand is supported since 1.78.0. If this parameter is set, the given navigation properties are expanded automatically with the same $batch request in which the POST request for the creation is contained. Ensure that the batch mode is used and the back-end service supports GET requests relative to a content ID outside the changeset. The success and error callback functions are called only once, even if there are two requests in the $batch related to a single call of #createEntry:

The following outcomes are possible:

Note: If a server requires a property in the request, you must supply this property in the initial data, for example if the server requires a unit for an amount. This also applies if this property has a default value.

Note: A deep create (including data defined by navigation properties) is not supported. The dependent entity has to be created using a second list binding, after this entity has been saved successfully in the back-end system.

Param Type DefaultValue Description
sPath string

The path to the EntitySet

mParameters object

A map of the following parameters:

batchGroupId string

Deprecated - use groupId instead

changeSetId string

The ID of the ChangeSet that this request should belong to

context sap.ui.model.Context

The binding context

created function

The callback function that is called after the metadata of the service is loaded and the sap.ui.model.odata.v2.Context instance for the newly created entry is available; The sap.ui.model.odata.v2.Context instance for the newly created entry is passed as the first and only parameter.

error function

The error callback function

expand string

A comma-separated list of navigation properties to be expanded for the newly created entity; since 1.78.0.
The navigation properties are requested with an additional GET request in the same $batch request as the POST request for the entity creation; the given mParameters.headers are not considered in the GET request.
Note: The following prerequisites must be fulfilled:

  • batch mode must be enabled; see constructor parameter useBatch,
  • the back-end service must support the "Content-ID" header,
  • the back end must allow GET requests relative to this content ID outside the changeset within the $batch request.

groupId string

The ID of a request group; requests belonging to the same group will be bundled in one batch request

headers Object<string,string>

A map of headers

properties array object

An array that specifies a set of properties or the entry

refreshAfterChange boolean

Whether to update all bindings after submitting this change operation, see #setRefreshAfterChange; if given, this overrules the model-wide refreshAfterChange flag for this operation only; since 1.46

success function

The success callback function

urlParameters Object<string,string>

A map of URL parameters

createKey

Creates the key from the given collection name and property map.

Please make sure that the metadata document is loaded before using this function.

Param Type DefaultValue Description
sCollection string

Name of the collection

oKeyProperties object

Object containing at least all the key properties of the entity type

deleteCreatedEntry

Deletes a created entry from the request queue and from the model.

Note: Controls are not updated. Use #resetChanges instead to update also the controls, for example:
oModel.resetChanges([oContext.getPath()], undefined, true);

Since since 1.95.0; use {@link #resetChanges} instead
Param Type DefaultValue Description
oContext sap.ui.model.Context

The context object pointing to the created entry

destroy

References:

detachAnnotationsFailed

Detaches event handler fnFunction from the annotationsFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachAnnotationsLoaded

Detaches event handler fnFunction from the annotationsLoaded event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachBatchRequestCompleted

Detaches event handler fnFunction from the batchRequestCompleted event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachBatchRequestFailed

Detaches event handler fnFunction from the batchRequestFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachBatchRequestSent

Detaches event handler fnFunction from the batchRequestSent event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachMetadataFailed

Detaches event handler fnFunction from the metadataFailed event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachMetadataLoaded

Detaches event handler fnFunction from the metadataLoaded event of this sap.ui.model.odata.v2.ODataModel.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

enableCanonicalRequests

Enable/Disable canonical requests calculation. When enabled, a given resource path will be shortened as much as possible.

Param Type DefaultValue Description
bCanonicalRequests boolean

Enable/disable canonical request calculation

sap.ui.model.odata.v2.ODataModel.extend

Creates a new subclass of class sap.ui.model.odata.v2.ODataModel 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.Model.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

fireAnnotationsFailed

Fires event annotationsFailed to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

message string

A text that describes the failure

statusCode string

HTTP status code returned by the request (if available)

statusText string

The status as a text, details not specified, intended only for diagnosis output

responseText string

Response that has been received for the request, as a text string

fireAnnotationsLoaded

Fires event annotationsLoaded to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

annotations sap.ui.model.odata.v2.ODataAnnotations

The annotations object

fireBatchRequestCompleted

Fires event batchRequestCompleted to attached listeners.

Param Type DefaultValue Description
oParameters object

parameters to add to the fired event

ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

success boolean

Request was successful or not

async boolean

If the request is synchronous or asynchronous (if available)

requests array

Array of embedded requests ($batch) - empty array for non batch requests. Each request object within the array contains the following properties: url, method, headers, response object

response object

The response object - empty object if no response: The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

fireBatchRequestFailed

Fires event batchRequestFailed to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

ID string

The request ID

url string

The URL which is sent to the backend

method string

The HTTP method

headers Object<string,string>

The request headers

async boolean

If the request is synchronous or asynchronous (if available)

success boolean

Request was successful or not

response object

The response object - empty object if no response The response object contains the following properties: message, success, headers, statusCode, statusText, responseText

requests array

Array of embedded requests ($batch) Each request object within the array contains the following properties: URL, method, headers, response object

fireBatchRequestSent

Fires event batchRequestSent to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

url string

The URL which is sent to the backend.

type string

The type of the request (if available)

async boolean

If the request is synchronous or asynchronous (if available)

requests array

Array of embedded requests ($batch) Each request object within the array contains the following properties: url, method, headers

fireMetadataFailed

Fires event metadataFailed to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

message string

A text that describes the failure.

statusCode string

HTTP status code returned by the request (if available)

statusText string

The status as a text, details not specified, intended only for diagnosis output

responseText string

Response that has been received for the request ,as a text string

fireMetadataLoaded

Fires event metadataLoaded to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

metadata sap.ui.model.odata.ODataMetadata

the metadata object.

forceEntityUpdate

Force the update on the server of an entity by setting its ETag to '*'.

ETag handling must be active so the force update will work.

Param Type DefaultValue Description
sKey string

The key to an Entity e.g.: Customer(4711)

getChangeBatchGroups

Returns the definition of batch groups per entity type for two-way binding changes.

Since 1.36 use {@link #getChangeGroups} instead

getChangeGroups

Returns the definition of groups per entity type for two-way binding changes

getData

Return requested data as object if the data has already been loaded and stored in the model.

Since 1.24 please use {@link #getProperty} instead
Param Type DefaultValue Description
sPath string

A string containing the path to the data object that should be returned.

oContext object

The optional context which is used with the sPath to retrieve the requested data.

bIncludeExpandEntries boolean

This parameter should be set when a URI or custom parameter with a $expand system query option was used to retrieve associated entries embedded. If set to true then the getProperty function returns a desired property value or entry and includes the associated expand entries (if any). If set to false the associated/expanded entry properties are removed and not included in the desired entry as properties at all. This is useful for performing updates on the base entry only. Note: A copy, not a reference of the entry will be returned.

getDefaultCountMode

Returns the default count mode for retrieving the count of collections

getDeferredBatchGroups

Returns the array of batch group IDs that are set as deferred

Since 1.32 use {@link #getDeferredGroups} instead

getDeferredGroups

Returns the array of group IDs that are set as deferred.

getETag

Returns the ETag for a given binding path/context or data object.

Param Type DefaultValue Description
sPath string

The binding path

oContext sap.ui.model.Context

The binding context

oEntity object

The entity data

getHeaders

Returns all headers and custom headers which are stored in this OData model.

getKey

Returns the key part for the given the canonical entry URI, model context or data object or undefined when the vValue can't be interpreted.

Param Type DefaultValue Description
vValue string object sap.ui.model.Context

The canonical entry URI, the context or entry object

getMessageScope

Returns this model's message scope.

References:

sap.ui.model.odata.v2.ODataModel.getMetadata

Returns a metadata object for class sap.ui.model.odata.v2.ODataModel.

getMetaModel

Returns an instance of an OData meta model which offers a unified access to both OData V2 metadata and V4 annotations. It uses the existing sap.ui.model.odata.ODataMetadata as a foundation and merges V4 annotations from the existing sap.ui.model.odata.v2.ODataAnnotations directly into the corresponding model element.

BEWARE: Access to this OData meta model will fail before the promise returned by loaded has been resolved!

getObject

Returns a JSON object that is a copy of the entity data referenced by the given sPath and oContext. It does not load any data and may not return all requested data if it is not available.

With the mParameters.select parameter it is possible to specify comma-separated property or navigation property names which should be included in the result object. This works like the OData $select URL parameter. With the mParameters.expand parameter it is possible to specify comma-separated navigation property names which should be included inline in the result object. This works like the OData $expand parameter.

Note: mParameters.expand can only be used if the corresponding navigation properties have been read via sap.ui.model.odata.v2.ODataModel#read using the OData $expand URL parameter. If a navigation property has not been read via the OData $expand URL parameter, it is left out in the result. Keep in mind that navigation properties referencing a collection are usually not loaded via the OData $expand URL parameter but directly via its navigation property.

Note: If mParameters.select is not specified, the returned object may contain model-internal attributes. This may lead to problems when submitting this data to the service for an update or create operation. To get a copy of the entity without internal attributes, use {select: "*"} instead.

Note: If mParameters.select is given and not all selected properties are available, this method returns undefined instead of incomplete data.

Note: If mParameters.select is not given, all properties and navigation properties available on the client are returned.

Example:
With mParameters given as {select: "Products/ProductName, Products", expand:"Products"} no properties of the entity itself are returned, but only the ProductName property of the Products navigation property. If Products/ProductName has not been loaded before, undefined is returned.

Param Type DefaultValue Description
sPath string

The path referencing the object

oContext sap.ui.model.Context

The optional context which is used with the sPath to reference the object.

mParameters object

Map of parameters

select string

Comma-separated list of properties or paths to properties to select

expand string

Comma-separated list of navigation properties or paths to navigation properties to expand

getOriginalProperty

Returns the original value for the property with the given path and context. The original value is the value that was last responded by the server.

Param Type DefaultValue Description
sPath string

The path/name of the property

oContext object

The context if available to access the property value

getPendingChanges

Returns the changed properties of all changed entities in a map which are still pending. The key is the string name of the entity and the value is an object which contains the changed properties.

In contrast to the two related functions #hasPendingChanges and #resetChanges, only client data changes are supported.

getPersistTechnicalMessages

Gets the flag whether technical messages should always be treated as persistent.

getProperty

Returns the value for the property with the given sPath.

If the path points to a navigation property which has been loaded via $expand then the bIncludeExpandEntries parameter determines if the navigation property should be included in the returned value or not. Please note that this currently works for 1..1 navigation properties only.

Param Type DefaultValue Description
sPath string

Path/name of the property

oContext object

Context if available to access the property value

bIncludeExpandEntries boolean false

@deprecated Please use #getObject function with select/expand parameters instead. This parameter should be set when a URI or custom parameter with a $expand system query option was used to retrieve associated entries embedded/inline. If true then the getProperty function returns a desired property value/entry and includes the associated expand entries (if any). Note: A copy and not a reference of the entry will be returned.

getRefreshAfterChange

getSecurityToken

Returns the current security token.

If the token has not been requested from the server it will be requested first (synchronously).

getServiceAnnotations

Return the annotation object. Please note that the metadata is loaded asynchronously and this function might return undefined because the metadata has not been loaded yet. In this case attach to the annotationsLoaded event to get notified when the annotations are available and then call this function.

getServiceMetadata

Return the parsed XML metadata as a Javascript object.

Please note that the metadata is loaded asynchronously and this function might return undefined because the metadata has not been loaded yet. In this case attach to the metadataLoaded event to get notified when the metadata is available and then call this function.

hasPendingChanges

Checks if there exist pending changes in the model.

By default, only client data changes triggered through: #createEntry #setProperty are taken into account.

If bAll is set to true, also deferred requests triggered through: #create #update #remove are taken into account.

Param Type DefaultValue Description
bAll boolean false

If set to true, deferred requests are also taken into account.

hasPendingRequests

Checks if there are pending requests, either ongoing or sequential.

invalidate

Invalidate the model data.

Mark all entries in the model cache as invalid. Next time a context or list is bound (binding), the respective entries will be detected as invalid and will be refreshed from the server.

To refresh all model data use sap.ui.model.odata.v2.ODataModel#refresh

Param Type DefaultValue Description
fnCheckEntry function

A function which can be used to restrict invalidation to specific entries, gets the entity key and object as parameters and should return true for entities to invalidate.

invalidateEntityType

Invalidate all entries of the given entity type in the model data.

Mark entries of the provided entity type in the model cache as invalid. Next time a context binding or list binding is done, the entry will be detected as invalid and will be refreshed from the server.

Param Type DefaultValue Description
sEntityType string

The qualified name of the entity type. A qualified name consists of two parts separated by a dot. The first part is the namespace of the schema in which the entity type is defined, such as "NorthwindModel". The second part is the entity type name such as "Customer". This results in a qualified name such as "NorthwindModel.Customer". The qualified name can be found in the data sent from the server in JSON format under __metadata.type or in XML format in the term attribute of the entity's category tag.

invalidateEntry

Invalidate a single entry in the model data.

Mark the selected entry in the model cache as invalid. Next time a context binding or list binding is done, the entry will be detected as invalid and will be refreshed from the server.

Param Type DefaultValue Description
vEntry string sap.ui.model.Context

the reference to the entry, either by key, absolute path or context object

isMetadataLoadingFailed

Checks whether metadata loading has failed in the past.

messageScopeSupported

Checks whether the service has set the OData V2 annotation "message-scope-supported" on the EntityContainer with the value true. This is a a precondition for the setting of sap.ui.model.odata.MessageScope.BusinessObject via #setMessageScope.

References:

metadataLoaded

Returns a promise for the loaded state of the metadata.

The metadata needs to be loaded prior to performing OData calls. Chaining to the returned promise ensures that all required parameters have been loaded, e.g. the security token, see #getSecurityToken.

The returned promise depends on the optional parameter bRejectOnFailure.

bRejectOnFailure=false: The promise won't get rejected in case the metadata or annotation loading failed but is only resolved if

  1. the metadata are loaded successfully,
  2. the annotations are processed, provided the model parameter loadAnnotationsJoined has been set.
Use this promise for delaying OData calls until all required information is available, i.e. this promise is resolved.

bRejectOnFailure=true: Since 1.79, the parameter bRejectOnFailure allows to request a promise that is rejected when one of the following fails:

The promise is fulfilled upon successful loading of both. This promise can be used to start processing OData calls when it is fulfilled and to display an error message when it is rejected. See also the example below.

If the method refreshMetadata is called after the returned promise is already resolved or rejected, you should use the promise returned by refreshMetadata to get information about the refreshed state.

Param Type DefaultValue Description
bRejectOnFailure boolean false

Determines since 1.79 whether the returned promise is rejected when the initial loading of the metadata fails. In case the model parameter loadAnnotationsJoined is set, the returned promise fails also if loading the annotations fails.

read

Trigger a GET request to the OData service that was specified in the model constructor.

The data will be stored in the model. The requested data is returned with the response.

Param Type DefaultValue Description
sPath string

An absolute path or a path relative to the context given in mParameters.context; if the path contains a query string, the query string is ignored, use mParameters.urlParameters instead

mParameters object

Optional parameter map containing any of the following properties:

context object

If specified, sPath has to be relative to the path given with the context.

urlParameters Object<string,string>

A map containing the parameters that will be passed as query strings

filters sap.ui.model.Filter[]

An array of filters to be included in the request URL

sorters sap.ui.model.Sorter[]

An array of sorters to be included in the request URL

success function

A callback function which is called when the data has been successfully retrieved. The handler can have the following parameters: oData and response. The oData parameter contains the data of the retrieved data. The response parameter contains further information about the response of the request.

error function

A callback function which is called when the request failed. The handler can have the parameter: oError which contains additional error information.

batchGroupId string

Deprecated - use groupId instead

groupId string

ID of a request group; requests belonging to the same group will be bundled in one batch request

updateAggregatedMessages boolean

Whether messages for child entities belonging to the same business object as the requested or changed resources are updated. It is considered only if sap.ui.model.odata.MessageScope.BusinessObject is set using #setMessageScope and if the OData service supports message scope.

refresh

Refresh the model.

This will reload all data stored in the model. This will check all bindings for updated data and update the controls if data has been changed.

Note: In contrast to an individual Binding refresh, the model refresh ignores Binding-specific parameters/queries.

Param Type DefaultValue Description
bForceUpdate boolean false

Force update of controls

bRemoveData boolean false

If set to true then the model data will be removed/cleared. Please note that the data might not be there when calling e.g. getProperty too early before the refresh call returned.

sGroupId string

ID of a request group; requests belonging to the same group will be bundled in one batch request

refreshMetadata

Refreshes the metadata for this model, for example when the request for metadata has failed.

Note: Do not use refreshMetadata if the metadata is outdated or should be updated. This will lead to inconsistent data in the application.

Returns a new promise which can be resolved or rejected depending on the metadata loading state.

refreshSecurityToken

Refresh XSRF token by performing a GET request against the service root URL.

Param Type DefaultValue Description
fnSuccess function

Callback function which is called when the data has been successfully retrieved.

fnError function

Callback function which is called when the request failed. The handler can have the parameter: oError which contains additional error information.

bAsync boolean false

Whether the request should be sent asynchronously

remove

Trigger a DELETE request to the OData service that was specified in the model constructor.

Param Type DefaultValue Description
sPath string

A string containing the path to the data that should be removed. The path is concatenated to the service URL which was specified in the model constructor.

mParameters object

Optional, can contain the following attributes:

context object

If specified, sPath has to be relative to the path given with the context.

success function

A callback function which is called when the data has been successfully retrieved. The handler can have the following parameters: oData and response.

error function

A callback function which is called when the request failed. The handler can have the parameter: oError which contains additional error information.

eTag string

If specified, the If-Match header will be set to this ETag.

urlParameters Object<string,string>

A map containing the parameters that will be passed as query strings

headers Object<string,string>

A map of headers for this request

batchGroupId string

Deprecated - use groupId instead

groupId string

ID of a request group; requests belonging to the same group will be bundled in one batch request

changeSetId string

ID of the ChangeSet that this request should belong to

refreshAfterChange boolean

Since 1.46; defines whether to update all bindings after submitting this change operation, see #setRefreshAfterChange. If given, this overrules the model-wide refreshAfterChange flag for this operation only.

resetChanges

Resets pending changes and aborts corresponding requests.

By default, only changes triggered through #createEntry or #setProperty are taken into account. If bAll is set, also deferred requests triggered through #create, #update or #remove are taken into account.

If bDeleteCreatedEntities is set, the entity is completely removed, provided it has been created

Param Type DefaultValue Description
aPath array

Paths to be be reset; if no array is passed, all changes are reset

bAll boolean false

Whether also deferred requests are taken into account

bDeleteCreatedEntities boolean false

Whether to delete the entities created via #createEntry or #callFunction; since 1.95.0

securityTokenAvailable

Returns a promise, which will resolve with the security token as soon as it is available.

setChangeBatchGroups

Definition of batch groups per entity type for two-way binding changes.

Since 1.32 Use {@link #setChangeGroups} instead
Param Type DefaultValue Description
mGroups Object<string,sap.ui.model.odata.v2.ODataModel.ChangeGroupDefinition>

A map containing the definition of batch groups for two-way binding changes. The map has the following format:

{
  "EntityTypeName": {
    batchGroupId: "ID",
    [changeSetId: "ID",]
    [single: true/false,]
  }
}
  • batchGroupId: Defines the batch group for changes of the defined EntityTypeName
  • changeSetId: ID of a ChangeSet which bundles the changes for the entity type.
  • single: Defines if every change will get an own change set (defaults to true)

setChangeGroups

Definition of groups per entity type for two-way binding changes.

Param Type DefaultValue Description
mGroups Object<string,sap.ui.model.odata.v2.ODataModel.ChangeGroupDefinition>

A map containing the definition of batch groups for two-way binding changes, keyed by entity names. The map has the following format:

{
  "EntityTypeName": {
    groupId: "ID",
    [changeSetId: "ID",]
    [single: true/false,]
  }
}
  • groupId: Defines the group for changes of the defined EntityTypeName
  • changeSetId: ID of a ChangeSet which bundles the changes for the entity type.
  • single: Defines if every change will get an own change set (defaults to true)

setDefaultCountMode

Sets the default mode how to retrieve the item count for a collection in this model.

The count can be determined in the following ways

See sap.ui.model.odata.CountMode for all enumeration values and more details.

Note that a call to this method does not modify the count mode for existing list bindings, only bindings that are created afterwards will use the new mode when no mode is defined at their creation.

If no default count mode is set for an ODataModel (v2), the mode Request will be used.

Param Type DefaultValue Description
sCountMode sap.ui.model.odata.CountMode

The new default count mode for this model

setDeferredBatchGroups

Setting batch groups as deferred.

Requests that belong to a deferred batch group have to be sent by explicitly calling #submitChanges.

Since 1.32 use {@link #setDeferredGroups} instead
Param Type DefaultValue Description
aGroupIds array

Array of batch group IDs that should be set as deferred

setDeferredGroups

Setting request groups as deferred.

Requests that belong to a deferred group will be sent by explicitly calling #submitChanges.

Param Type DefaultValue Description
aGroupIds array

Array of group IDs that should be set as deferred

setHeaders

Set custom headers which are provided in a key/value map.

These headers are used for requests against the OData backend. Private headers which are set in the ODataModel cannot be modified. These private headers are: accept, accept-language, x-csrf-token, MaxDataServiceVersion, DataServiceVersion.

To remove these custom headers simply set the mHeaders parameter to null. Please also note that when calling this method again, all previous custom headers are removed unless they are specified again in the mHeaders parameter.

Param Type DefaultValue Description
mHeaders object

The header name/value map.

setMessageScope

Sets this model's message scope.

References:

Param Type DefaultValue Description
sMessageScope sap.ui.model.odata.MessageScope

The message scope

setPersistTechnicalMessages

Sets the flag whether technical messages should always be treated as persistent. Works only with sap.ui.model.odata.ODataMessageParser.

Param Type DefaultValue Description
bPersistTechnicalMessages boolean

Whether technical messages should always be treated as persistent

setProperty

Sets a new value for the given property sPath in the model.

If the changeBatchGroup for the changed entity type is set to deferred, changes could be submitted with #submitChanges. Otherwise the change will be submitted directly.

Param Type DefaultValue Description
sPath string

Path of the property to set

oValue any

Value to set the property to

oContext sap.ui.model.Context

The context which will be used to set the property

bAsyncUpdate boolean

Whether to update other bindings dependent on this property asynchronously

setRefreshAfterChange

Defines whether all bindings are updated after a change operation.

This flag can be overruled on request level by providing the refreshAfterChange parameter to the corresponding function (for example #update).

Param Type DefaultValue Description
bRefreshAfterChange boolean

Whether to automatically refresh after changes

setTokenHandlingEnabled

Enable/Disable security token handling.

Param Type DefaultValue Description
bTokenHandling boolean true

Whether to use token handling or not

setUseBatch

Enable or disable batch mode for future requests.

Param Type DefaultValue Description
bUseBatch boolean false

Whether the requests should be encapsulated in a batch request

submitChanges

Submits the collected changes which were collected by the #setProperty method and other deferred requests.

The update method is defined by the global defaultUpdateMethod parameter which is sap.ui.model.odata.UpdateMethod.Merge by default. In case of a sap.ui.model.odata.UpdateMethod.Merge request only the changed properties will be updated. If a URI with a $expand query option was used then the expand entries will be removed from the collected changes. Changes to this entries should be done on the entry itself. So no deep updates are supported.

Important: The success/error handler will only be called if batch support is enabled. If multiple batch groups are submitted the handlers will be called for every batch group. If there are no changes/requests or all contained requests are aborted before a batch request returns, the success handler will be called with an empty response object. If the abort method on the return object is called, all contained batch requests will be aborted and the error handler will be called for each of them.

Param Type DefaultValue Description
mParameters object

A map which contains the following parameter properties:

batchGroupId string

Deprecated - use groupId instead

groupId string

Defines the group that should be submitted. If not specified, all deferred groups will be submitted. Requests belonging to the same group will be bundled in one batch request.

success function

A callback function which is called when the data has been successfully updated. The handler can have the following parameters: oData. oData contains the parsed response data as a Javascript object. The batch response is in the __batchResponses property which may contain further __changeResponses in an array depending on the amount of changes and change sets of the actual batch request which was sent to the backend. The changeResponses contain the actual response of that change set in the response property. For each change set there is also a __changeResponse property.

error function

A callback function which is called when the request failed. The handler can have the parameter: oError which contains additional error information

update

Trigger a PUT/MERGE request to the OData service that was specified in the model constructor.

The update method used is defined by the global defaultUpdateMethod parameter which is sap.ui.model.odata.UpdateMethod.Merge by default. Please note that deep updates are not supported and may not work. These should be done separately and directly on the corresponding entry.

Param Type DefaultValue Description
sPath string

A string containing the path to the data that should be updated. The path is concatenated to the sServiceUrl which was specified in the model constructor.

oData object

Data of the entry that should be updated.

mParameters object

Optional, can contain the following attributes:

context object

If specified the sPath has to be is relative to the path given with the context.

success function

A callback function which is called when the data has been successfully updated.

error function

A callback function which is called when the request failed. The handler can have the parameter oError which contains additional error information.

eTag string

If specified, the If-Match header will be set to this ETag. Caution: This feature in not officially supported as using asynchronous requests can lead to data inconsistencies. If you decide to use this feature nevertheless, you have to make sure that the request is completed before the data is processed any further.

urlParameters Object<string,string>

A map containing the parameters that will be passed as query strings

headers Object<string,string>

A map of headers for this request

batchGroupId string

Deprecated - use groupId instead

groupId string

ID of a request group; requests belonging to the same group will be bundled in one batch request

changeSetId string

ID of the ChangeSet that this request should belong to

refreshAfterChange boolean

Since 1.46; defines whether to update all bindings after submitting this change operation. See #setRefreshAfterChange If given, this overrules the model-wide refreshAfterChange flag for this operation only.

updateBindings

Update all bindings.

Param Type DefaultValue Description
bForceUpdate boolean false

If set to false, an update will only be done when the value of a binding changed.