class sap.ui.model.odata.ODataModel

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

Model implementation for OData format


Constructor

Constructor for a new ODataModel.

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

base uri of the service to request data from; additional URL parameters appended here will be appended to every request can be passed with the mParameters object as well: [mParameters.serviceUrl] A serviceURl is required!

mParameters? object

(optional) a map which contains the following parameter properties:

json? boolean

if set true request payloads will be JSON, XML for false (default = false),

user? string

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

password? string

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

headers? Object<string,string>

a map of custom headers like {"myHeader":"myHeaderValue",...},

tokenHandling? boolean

enable/disable XCSRF-Token handling (default = true),

withCredentials? boolean

experimental - true when user credentials are to be included in a cross-origin request. Please note that this works only if all requests are asynchronous.

loadMetadataAsync? object

(optional) determined if the service metadata request is sent synchronous or asynchronous. Default is false.

maxDataServiceVersion? undefined

(default = '2.0') please use the following string format e.g. '2.0' or '3.0'. OData version supported by the ODataModel: '2.0',

useBatch? boolean

when true all requests will be sent in batch requests (default = false),

refreshAfterChange? boolean

enable/disable automatic refresh after change operations: default = true,

annotationURI? string string[]

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

loadAnnotationsJoined? boolean

Whether or not to fire the metadataLoaded-event only after annotations have been loaded as well,

serviceUrlParams? Object<string,string>

map of URL parameters - these parameters will be attached to all requests,

metadataUrlParams? Object<string,string>

map of URL parameters for metadata requests - only attached to $metadata request.

defaultCountMode? string

sets the default count mode for the model. If not set, sap.ui.model.odata.CountMode.Both is used.

metadataNamespaces? Object<string,string>

a map of namespaces (name => URI) used for parsing the service metadata.

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


Events Overview

Event Description
annotationsFailed

The annotationsFailed event is fired when loading the annotations document failed.

annotationsLoaded

The annotationsLoaded event is fired after the annotations document was successfully loaded.

metadataFailed

The metadataFailed event is fired when loading the metadata document failed.

metadataLoaded

The metadataLoaded event is fired after the metadata document was successfully loaded.

annotationsFailed

The annotationsFailed event is fired when loading the annotations document failed.

Param Type Description
oEvent sap.ui.base.Event

annotationsLoaded

The annotationsLoaded event is fired after the annotations document was successfully loaded.

Param Type Description
oEvent sap.ui.base.Event

metadataFailed

The metadataFailed event is fired when loading the metadata document failed.

Param Type Description
oEvent sap.ui.base.Event

metadataLoaded

The metadataLoaded event is fired after the metadata document was successfully loaded.

Param Type Description
oEvent sap.ui.base.Event

Methods Overview

Method Description
addAnnotationUrl

Adds (a) new URL(s) to the be parsed for 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.

addBatchChangeOperations

Appends the change batch operations to the end of the batch stack. Only PUT, POST or DELETE batch operations should be included in the specified array. The operations in the array will be included in a single changeset. To embed change operations in different change sets call this method with the corresponding change operations again. If an illegal batch operation is added to the change set nothing will be performed and false will be returned.

addBatchReadOperations

Appends the read batch operations to the end of the batch stack. Only GET batch operations should be included in the specified array. If an illegal batch operation is added to the batch nothing will be performed and false will be returned.

attachAnnotationsFailed

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

attachAnnotationsLoaded

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

attachMetadataFailed

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

attachMetadataLoaded

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

bindList

Creates a new list binding for this model.

References:

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

callFunction

Trigger a request to the function import odata service that was specified in the model constructor.

clearBatch

Removes all operations in the current batch.

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.

createBatchOperation

Creates a single batch operation (read or change operation) which can be used in a batch request.

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. To delete a created entry from the request queue call deleteCreateEntry.

The optional vProperties parameter can be used as follows:

- vProperties could be an array containing the property names which should be included in the new entry. Other properties defined in the entity type are not included. - vProperties could be an object which includes the desired properties and the values which should be used for the created entry.

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

Please note that deep creates (including data defined by navigationproperties) are not supported

createKey

Creates the key from the given collection name and property map

deleteCreatedEntry

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

destroy

References:

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

detachAnnotationsFailed

Detaches event handler fnFunction from the annotationsFailed event of this sap.ui.model.odata.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.ODataModel.

detachMetadataFailed

Detaches event handler fnFunction from the metadataFailed event of this sap.ui.model.odata.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.ODataModel.

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

sap.ui.model.odata.ODataModel.extend

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

fireMetadataFailed

Fires event metadataFailed to attached listeners.

fireMetadataLoaded

Fires event metadataLoaded to attached listeners.

forceNoCache

Force no caching

Since 1.13 the caching should be controlled by the backend by setting the correct cache control header
getData

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

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

Returns the default count mode for retrieving the count of collections

getHeaders

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

getKey

Returns the key part from the entry URI or the given context or object

sap.ui.model.odata.ODataModel.getMetadata

Returns a metadata object for class sap.ui.model.odata.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.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!

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.

getSecurityToken

Returns the current security token. If the token has not been requested from the server it will be requested first.

getServiceAnnotations

Return the annotation object. Please note that when using the model with bLoadMetadataAsync = true then 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 metadata object. Please note that when using the model with bLoadMetadataAsync = true then 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 created by the setProperty method.

isCountSupported

Returns whether this model supports the $count on its collections

Since 1.20 please use {@link #getDefaultCountMode} instead.
read

Trigger a GET request to the odata service that was specified in the model constructor. The data will not be stored in the model. The requested data is returned with the response.

refresh

Refresh the model.

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

refreshMetadata

Refreshes the metadata for model, e.g. in case the first request for metadata has failed.

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 the collected changes by the setProperty method and reloads the data from the server.

setCountSupported

Sets whether this OData service supports $count on its collections.

Since 1.20 please use {@link #setDefaultCountMode} instead.
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 (v1), the mode Both will be used for compatibility reasons.

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 headers simply set the mCustomHeaders 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 mCustomHeaders parameter.

setProperty

Sets a new value for the given property sPropertyName in the model without triggering a server request. This can be done by the submitChanges method.

Note: Only one entry of one collection can be updated at once. Otherwise a fireRejectChange event is fired.

Before updating a different entry the existing changes of the current entry have to be submitted or resetted by the corresponding methods: submitChanges, resetChanges.

IMPORTANT: All pending changes are resetted in the model if the application triggeres any kind of refresh on that entry. Make sure to submit the pending changes first. To determine if there are any pending changes call the hasPendingChanges method.

setRefreshAfterChange

Enable/Disable automatic updates of all Bindings after change operations

setTokenHandlingEnabled

Enable/Disable XCSRF-Token handling

setUseBatch

Enable/Disable batch for all requests

submitBatch

Submits the collected changes in the batch which were collected via addBatchReadOperations or addBatchChangeOperations. The batch will be cleared afterwards. If the batch is empty, no request will be sent and false will be returned.

Note: No data will be stored in the model as long as bImportData is not set.

submitChanges

Submits the collected changes which were collected by the setProperty method. A MERGE request will be triggered to only update the changed properties. If a URI with a $expand System 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.

update

Trigger a PUT/MERGE request to the odata service that was specified in the model constructor. Please note that deep updates are not supported and may not work. These should be done seperate on the entry directly.

updateBindings

update all bindings

addAnnotationUrl

Adds (a) new URL(s) to the be parsed for 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 or 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

addBatchChangeOperations

Appends the change batch operations to the end of the batch stack. Only PUT, POST or DELETE batch operations should be included in the specified array. The operations in the array will be included in a single changeset. To embed change operations in different change sets call this method with the corresponding change operations again. If an illegal batch operation is added to the change set nothing will be performed and false will be returned.

Param Type DefaultValue Description
aChangeOperations any[]

an array of change batch operations created via createBatchOperation and sMethod = POST, PUT, MERGE or DELETE

addBatchReadOperations

Appends the read batch operations to the end of the batch stack. Only GET batch operations should be included in the specified array. If an illegal batch operation is added to the batch nothing will be performed and false will be returned.

Param Type DefaultValue Description
aReadOperations any[]

an array of read batch operations created via createBatchOperation and sMethod = GET

attachAnnotationsFailed

Attaches event handler fnFunction to the annotationsFailed event of this sap.ui.model.odata.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.ODataModel itself

attachAnnotationsLoaded

Attaches event handler fnFunction to the annotationsLoaded event of this sap.ui.model.odata.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.ODataModel itself

attachMetadataFailed

Attaches event handler fnFunction to the metadataFailed event of this sap.ui.model.odata.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.ODataModel itself

attachMetadataLoaded

Attaches event handler fnFunction to the metadataLoaded event of this sap.ui.model.odata.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.ODataModel itself

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 filter/s, 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

Defines the count mode of the new binding; if not specified, the default count mode of this model will be applied

callFunction

Trigger a request to the function import odata service that was specified in the model constructor.

Param Type DefaultValue Description
sFunctionName string

A string containing the name of the function to call. The name is concatenated to the sServiceUrl which was specified in the model constructor.

mParameters object

Optional parameter map containing any of the following properties:

method string

A string containing the type of method to call this function with

urlParameters Object<string,string>

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

context object

If specified the 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.

async boolean false

Whether or not to send the request asynchronously. Default: false In case sMethod is "GET", the request is always asynchronous. Please be advised that this feature is officially unsupported as using asynchronous requests can lead to data inconsistencies if the application does not make sure that the request was completed before continuing to work with the data.

clearBatch

Removes all operations in the current batch.

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

async boolean false

Whether the request should be done asynchronously. Default: false Please be advised that this feature is officially unsupported as using asynchronous requests can lead to data inconsistencies if the application does not make sure that the request was completed before continuing to work with the data.

urlParameters Object<string,string>

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

createBatchOperation

Creates a single batch operation (read or change operation) which can be used in a batch request.

Param Type DefaultValue Description
sPath string

A string containing the path to the collection or entry where the batch operation should be performed. The path is concatenated to the sServiceUrl which was specified in the model constructor.

sMethod string

for the batch operation. Possible values are GET, PUT, MERGE, POST, DELETE

oData object

optional data payload which should be created, updated, deleted in a change batch operation.

oParameters object

optional parameter for additional information introduced in SAPUI5 1.9.1,

sETag string

an ETag which can be used for concurrency control. If it is specified, it will be used in an If-Match-Header in the request to the server for this entry.

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. To delete a created entry from the request queue call deleteCreateEntry.

The optional vProperties parameter can be used as follows:

- vProperties could be an array containing the property names which should be included in the new entry. Other properties defined in the entity type are not included. - vProperties could be an object which includes the desired properties and the values which should be used for the created entry.

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

Please note that deep creates (including data defined by navigationproperties) are not supported

Param Type DefaultValue Description
sPath string

Name of the path to the collection

vProperties array object

An array that specifies a set of properties or the entry

createKey

Creates the key from the given collection name and property map

Param Type DefaultValue Description
sCollection string

The name of the collection

oKeyParameters object

The object containing at least all the key properties of the entity type

bDecode boolean

Whether the URI decoding should be applied on the key

deleteCreatedEntry

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

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

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

sap.ui.model.odata.ODataModel.extend

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

the annotations object.

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.

forceNoCache

Force no caching

Since 1.13 the caching should be controlled by the backend by setting the correct cache control header
Param Type DefaultValue Description
bForceNoCache boolean false

whether to force no caching

getData

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

Since 1.6.0 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/inline. If true then the getProperty function returns a desired property value/entry and includes the associated expand entries (if any). If 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 and not a reference of the entry will be returned.

getDefaultCountMode

Returns the default count mode for retrieving the count of collections

getHeaders

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

getKey

Returns the key part from the entry URI or the given context or object

Param Type DefaultValue Description
oObject object sap.ui.model.Context

The context or object

bDecode boolean

Whether the URI decoding should be applied on the key

sap.ui.model.odata.ODataModel.getMetadata

Returns a metadata object for class sap.ui.model.odata.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.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!

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

the path/name of the property

oContext object

the context if available to access the property value

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/inline. If true then the getProperty function returns a desired property value/entry and includes the associated expand entries (if any). If 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 and not a reference of the entry will be returned.

getSecurityToken

Returns the current security token. If the token has not been requested from the server it will be requested first.

getServiceAnnotations

Return the annotation object. Please note that when using the model with bLoadMetadataAsync = true then 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 metadata object. Please note that when using the model with bLoadMetadataAsync = true then 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 created by the setProperty method.

isCountSupported

Returns whether this model supports the $count on its collections

Since 1.20 please use {@link #getDefaultCountMode} instead.

read

Trigger a GET request to the odata service that was specified in the model constructor. The data will not be stored in the model. The requested data is returned with the response.

Param Type DefaultValue Description
sPath string

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

mParameters object

Optional parameter map containing any of the following properties:

context object

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

urlParameters Object<string,string>

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

async boolean true

true for asynchronous requests.

filters array

an array of sap.ui.model.Filter to be included in the request URL

sorters array

an array of sap.ui.model.Sorter 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.

error function

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

refresh

Refresh the model.

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

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.

refreshMetadata

Refreshes the metadata for model, e.g. in case the first request for metadata has failed.

refreshSecurityToken

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

Param Type DefaultValue Description
fnSuccess function

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

fnError function

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

bAsync boolean false

true for asynchronous requests.

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 sServiceUrl which was specified in the model constructor.

mParameters object

Optional, can contain the following attributes: oContext, fnSuccess, fnError, sETag:

context object

If specified the 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.

payload object

if specified, this optional variable can be used to pass a payload into the delete function, e.g. if the entry which should be deleted has not been bound to any control, but has been retrieved via read, only.

async boolean false

Whether the request should be done asynchronously. Please be advised that this feature is officially unsupported as using asynchronous requests can lead to data inconsistencies if the application does not make sure that the request was completed before continuing to work with the data.

urlParameters Object<string,string>

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

resetChanges

Resets the collected changes by the setProperty method and reloads the data from the server.

Param Type DefaultValue Description
fnSuccess function

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

fnError function

a callback function which is called when the request failed

setCountSupported

Sets whether this OData service supports $count on its collections.

Since 1.20 please use {@link #setDefaultCountMode} instead.
Param Type DefaultValue Description
bCountSupported boolean

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 (v1), the mode Both will be used for compatibility reasons.

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

The new default count mode for this model

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 headers simply set the mCustomHeaders 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 mCustomHeaders parameter.

Param Type DefaultValue Description
mHeaders object

the header name/value map.

setProperty

Sets a new value for the given property sPropertyName in the model without triggering a server request. This can be done by the submitChanges method.

Note: Only one entry of one collection can be updated at once. Otherwise a fireRejectChange event is fired.

Before updating a different entry the existing changes of the current entry have to be submitted or resetted by the corresponding methods: submitChanges, resetChanges.

IMPORTANT: All pending changes are resetted in the model if the application triggeres any kind of refresh on that entry. Make sure to submit the pending changes first. To determine if there are any pending changes call the hasPendingChanges method.

Param Type DefaultValue Description
sPath string

path of the property to set

oValue any

value to set the property to

oContext object

the context which will be used to set the property

bAsyncUpdate boolean

whether to update other bindings dependent on this property asynchronously

setRefreshAfterChange

Enable/Disable automatic updates of all Bindings after change operations

Param Type DefaultValue Description
bRefreshAfterChange boolean

setTokenHandlingEnabled

Enable/Disable XCSRF-Token handling

Param Type DefaultValue Description
bTokenHandling boolean true

whether to use token handling or not

setUseBatch

Enable/Disable batch for all requests

Param Type DefaultValue Description
bUseBatch boolean false

whether the requests should be encapsulated in a batch request

submitBatch

Submits the collected changes in the batch which were collected via addBatchReadOperations or addBatchChangeOperations. The batch will be cleared afterwards. If the batch is empty, no request will be sent and false will be returned.

Note: No data will be stored in the model as long as bImportData is not set.

Param Type DefaultValue Description
fnSuccess function

A callback function which is called when the batch request has been successfully sent. Note: Errors that may have come up in the single batch operations can be accessed in the aErrorResponses parameter in the callback handler. The handler can have the following parameters: oData, oResponse and aErrorResponses.

fnError function

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

bAsync boolean true

true for asynchronous request

bImportData boolean false

Whether response data should be imported into the model

submitChanges

Submits the collected changes which were collected by the setProperty method. A MERGE request will be triggered to only update the changed properties. If a URI with a $expand System 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.

Param Type DefaultValue Description
fnSuccess function

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

fnError function

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

oParameters object

optional parameter for additional information introduced in SAPUI5 1.9.1

sETag string

an ETag which can be used for concurrency control. If it is specified, it will be used in an If-Match-Header in the request to the server for this entry.

update

Trigger a PUT/MERGE request to the odata service that was specified in the model constructor. Please note that deep updates are not supported and may not work. These should be done seperate on the entry directly.

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.

merge boolean false

trigger a MERGE request instead of a PUT request to perform a differential update

eTag string

If specified, the If-Match-Header will be set to this Etag.

async boolean false

Whether the request should be done asynchronously. Please be advised that this feature is officially unsupported as using asynchronous requests can lead to data inconsistencies if the application does not make sure that the request was completed before continuing to work with the data.

urlParameters Object<string,string>

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

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.