OData V2 Model

One OData model instance can only cover one OData service. For accessing multiple services, you have to create multiple OData model instances. The only mandatory parameter when creating an ODataModel instance is the service URL. It can be passed as first parameter or within the mParameters map to the constructor.

var oModel = new sap.ui.model.odata.v2.ODataModel("http://services.odata.org/Northwind/Northwind.svc/");
var oModel = new sap.ui.model.odata.v2.ODataModel({serviceUrl: "http://services.odata.org/Northwind/Northwind.svc"});

When creating an ODataModel instance, a request is sent to retrieve the service metadata:

http://services.odata.org/Northwind/Northwind.svc/$metadata

The service metadata is cached per service URL. Multiple OData models that are using the same service can share this metadata. Only the first model instance triggers a $metadata request. A JSON representation of the service metadata can be accessed by calling the getServiceMetadata() method on an Odata model instance.

var oMetadata = oModel.getServiceMetadata();

For OData services, you can use URL parameters for configuration. SAPUI5 sets most URL parameters automatically, according to the respective binding.

For authentication tokens or general configuration options, for example, you can add additional arguments to the request URL. Some of the parameters must not be included in every request, but should only be added to specific aggregation or element bindings, such as $expand or $select. For this, the binding methods provide the option to pass a map of parameters, which are then included in all requests for this specific binding. The OData model currently only supports $expand and $select.

There are different ways to add URL parameters to the requests:

• Appending parameters to the service URL:

  var oModel = new sap.ui.model.odata.v2.ODataModel("http://myserver/MyService.svc/?myParam=value&myParam2=value");

  These parameters will be included in every request sent to the OData server.

• Passing URL parameters with the mparameters map

  You can pass URL parameters that are used for $metadata requests only (metadataUrlParams) as well as URL parameters that are included only in data requests (serviceUrlParams). The parameters are passed as maps:

  var oModel = new sap.ui.model.odata.v2.ODataModel({ 
      serviceUrl: "http://services.odata.org/Northwind/Northwind.svc",    
      serviceUrlParams: {
          myParam: "value1",
          myParam2: "value2"
      },
      metadataUrlParams: {
          myParam: "value1",
          myParam2: "value2"
      }
  });

You can add custom headers which are sent with each request. To do this, provide a map of headers to the OData model constructor or use the setHeaders() function:

• Passing custom headers with the mparameters map

  var oModel = new sap.ui.model.odata.v2.ODataModel({
      headers: {
          "myHeader1" : "value1",
          "myHeader2" : "value2"
      }
  });

• Setting custom headers globally on a model instance

  oModel.setHeaders({"myHeader1" : "value1", "myHeader2" : "value2"});

  Note

  When you add custom headers, all previous custom headers are removed if not specified again in the headers map. Some headers are private, that is, they are set by the OData model internally and cannot be set:

  "accept"
  "accept-language"
  "maxdataserviceversion"
  "dataserviceversion"
  "x-csrf-token"

  For additional methods and parameters, see the API Reference for sap.ui.model.odata.v2.ODataModel in the Demo Kit.

The binding path syntax for OData models matches the URL path relative to the service URL used in OData to access specific entities or entity sets.

You access the data provided by the OData model according to the structure of the OData service as defined in the metadata of a service. URL parameters, such as filters, cannot be added to a binding path. A binding path can be absolute or relative. Absolute binding paths are resolved immediately. A relative path can only be resolved if it can be automatically converted into an absolute binding path. If, for example, a property is bound to a relative path and the parent control is then bound to an absolute path, the relative property path can e resolved to an absolute path.

The following binding samples within the ODataModel are taken from the Northwind demo service.

Absolute binding path (starting with a slash ('/')):

"/Customers"
"/Customers('ALFKI')/Address"

Relative binding paths that can be resolved with a context (for example "/Customer('ALFKI')"):

"CompanyName"
"Address"
"Orders"

Resolved to:

"/Customer('ALFKI')/CompanyName"
"/Customer('ALFKI')/Address"
"/Customer('ALFKI')/Orders"

Navigation properties, used to identify a single entity or a collection of entities:

"/Customers('ALFKI')/Orders"
"/Products(1)/Supplier"

For more information on addressing OData entries, see the URI conventions documentation on http://www.odata.org.

The data requested from an OData service is cached in the OData model. It can be accessed by the getData() and the getProperty() method, which returns the entity object or value. These methods do not request data from the backend, so you can only access already requested and cached entities:

oModel.getData("/Customer('ALFKI')");
oModel.getProperty("/Customer('ALFKI')/Address");

You can only access single entities and properties with these methods. To access entity sets, you can get the binding contexts of all read entities via a list binding. The values returned by these methods are copies of the data in the model, not references as in the JSONModel.

To create entities for a specified entity set, call the createEntry() method. The method returns a context object that points to the newly created entity. The application can bind against these objects and change the data by means of two-way binding. To store the entities in the OData backend, the application calls submitChanges(). To reset the changes, the application can call the deleteCreatedEntry() method.

The application can choose the properties that shall be included in the created object and can pass its own default values for these properties. Per default, all property values are be empty, that is, undefined.

// create an entry of the Products collection with the specified properties and values
var oContext = oModel.createEntry("/Products", { properties: { ID:99, Name:"Product", Description:"new Product", ReleaseDate:new Date(), Price:"10.1", Rating:1} });
// binding against this entity
oForm.setBindingContext(oContext);
// submit the changes (creates entity at the backend)
oModel.submitChanges({success: mySuccessHandler, error: myErrorHandler});
// delete the created entity
oModel.deleteCreatedEntry(oContext);

The OData model allows manual CRUD (create, read, update, delete) operations on the OData service. If a manual operation returns data, the data is imported into the data cache of the OData model. All operations require a mandatory sPath parameter as well as an optional mParameters map. The create and update methods also require a mandatory oData parameter for passing the created or changed data object. Each operation returns an object containing a function abort, which can be used to abort the request. If the request is aborted, the error handler is called. This ensures that the success or the error handler is executed for every request. It is also possible to pass additional header data, URL parameters, or an eTag.

• Creating entities

  The create function triggers a POST request to an OData service which was specified at creation of the OData model. The application has to specify the entity set, in which the new entity and the entity data is to be created.

  var oData = {
      ProductId: 999,
      ProductName: "myProduct"
  }
  oModel.create("/Products", oData, {success: mySuccessHandler, error: myErrorHandler});

• Reading entities

  The read function triggeres a GET request to a specified path. The path is retrieved from the OData service which was specified at creation of the OData model. The retrieved data is returned in the success callback handler function.

  oModel.read("/Products(999)", {success: mySuccessHandler, error: myErrorHandler});

• Updating entities

  The update function triggers a PUT/MERGE request to an OData service which was specified at creation of the OData model. After a successful request to update the bindings in the model, the refresh is triggered automatically.

  var oData = {
      ProductId: 999,
      ProductName: "myProductUpdated"
  }
  oModel.update("/Products(999)", oData, {success: mySuccessHandler, error: myErrorHandler});

• Deleting entities

  The remove function triggers a DELETE request to an OData service which was specified at creation of the OData model. The application has to specify the path to the entry which should be deleted.

  oModel.remove("/Products(999)", {success: mySuccessHandler, error: myErrorHandler});

• Refresh after change

  The model provides a mechanism to automatically refresh bindings that depend on changed entities. If you carry out a create, update or remove function, the model identifies the bindings and triggers a refresh for these bindings. If the model runs in batch mode, the refresh requests are bundled together with the changes in the same batch request. You can disable the auto refresh by calling setRefreshAfterChange(false). If the auto refresh is disabled, the application has to take care of refreshing the respective bindings.

  oModel.setRefreshAfterChange(false);

OData uses HTTP ETags for optimistic concurrency control. The service must be configured to provide them. The ETag can be passed within the parameters map for every CRUD request. If no ETag is passed, the ETag of the cached entity is used, if it is loaded already.

To address cross-site request forgery, an OData service may require XSRF tokens for change requests by the client application. In this case, the client has to fetch a token from the server and send it with each change request to the server. The OData model fetches the XSRF token when reading the metadata and then automatically sends it with each write request header. If the token is no longer valid, a new token can be fetched by calling the refreshSecurityToken function on the OData model. The token is fetched with a request to the service document. To ensure getting a valid token, make sure that the service document is not cached.

The refresh function refreshes all data within an OData model. Each binding reloads its data from the server. For list or element bindings, a new request to the back end is triggered. If the XSRF token is no longer valid, it has to be fetched again with a read request to the service document. Data that has been imported via manual CRUD requests is not reloaded automatically.

The v2.ODataModel supports batch processing ($batch) in two different ways:

• Default: All requests in a thread are collected and bundled in batch requests, meaning that request is sent in a timeout immediately after the current call stack is finished. This includes all manual CRUD requests as well as requests triggered by a binding.

• The requests are stored and can be submitted with a manual submitChanges() call by the application. This also includes all manual CRUD requests as well as requests triggered by a binding.

The model cannot decide how to bundle the requests. For this, SAPUI5 provides the groupId. For each binding and each manual request, a groupId can be specified. All requests belonging to the same group are bundled into one batch request. Request without a groupId are bundled in the default batch group. You can use a changeSetId for changes. The same principle applies: Each change belonging to the same changeSetId is bundled into one changeSet in the batch request. Per default, all changes have their own changeSet. For more information, see the API reference.

You can use the setDeferredGroups() method to set each group to deferred: All requests belonging to the group are then stored in a request queue. The deferred batch group must then be submitted manually by means of the submitChanges() method. If you do not specify a batch group ID when calling submitChanges, all deferred batch groups are submitted.

Example:

var oModel = new sap.ui.model.odata.v2.ODataModel(myServiceUrl);

Pass the groupId to a binding:

{path:"/myEntities", parameters: {groupId: "myId"}}

Set the groupId to deferred:

oModel.setDeferredGroups(["myGroupId", "myGroupId2"]);

Submit a deferred group:

oModel.submitChanges({groupId: "myGroupId", success: mySuccessHandler, error: myErrorHandler});

The v2.ODataModel enables two-way binding. Per default, all changes are collected in a batch group called "changes" which is set to deferred. To submit the changes, use submitChanges(). The data changes are made on a data copy. This enables you to reset the changes without sending a new request to the backend to fetch the old data again. With resetChanges() you can reset all changes. You can also reset only specific entities by calling resetChanges with an array of entity paths.

You can collect the changes for different entities or types in different batch groups. To configure this, use the setChangeGroups() method of the model:

var oModel = new sap.ui.model.odata.v2.ODataModel(myServiceUrl);
oModel.setDeferredGroups(["myGroupId", "myGroupId2"]);
oModel.setChangeGroups({
    "EntityTypeName": {
        groupId: "myGroupId",  
        [changeSetId: "ID",]
        [single: true/false,]
    }
);
oModel.submitChanges({groupId: "myGroupId", success: mySuccessHandler, error: myErrorHandler});

To collect the changes for all entity types in the same batch group, use '*’ as EntityType. If the change is not set to deferred, the changes are sent to the backend immediately. By setting the single parameter for changeSet to true or false, you define if a change is assigned its own change set (true) or if all changes are collected in one change set (false). The model only takes care of the changeSetId if single is set to false.

Example

Reset changes:

var oModel = new sap.ui.model.odata.v2.ODataModel(myServiceUrl);
//do a change
oModel.setProperty("/myEntity(0)", oValue);

//reset the change
oModel.resetChanges(["/myEntity(0)"]);

The OData protocol specifies different URL parameters. You can use these parameters in bindings in addition to the parameters described above:

• Expand parameter

  The expand parameter allows the application to read associated entities with their navigation properties:

  oControl.bindElement("/Category(1)", {expand: "Products"}); 
  
  oTable.bindRows({
      path: "/Products",
      parameters: {expand: "Category"}
  });

  In this example, all products of "Category(1)" are embedded inline in the server response and loaded in one request. The category for all "Products" is embedded inline in the response for each product.

• Select parameter

  The select parameter allows the application to define a subset of properties that is read when requesting an entity.

  oControl.bindElement("/Category(1)", {expand: "Products", select: "Name,ID,Products"}); 
  
  oTable.bindRows({
      path: "/Products",
      parameters: {select: "Name,Category"}
  });

  In this example, the properties Name, ID and ofCategory(1) as well as all properties of the embedded products are returned. The properties Name and Category are included for each product. The Category property contains a link to the related category entry.

• Custom query options

  You can use custom query options as input parameters for service operations. When creating the aggregation binding, specify these custom parameter as follows:

  oTable.bindRows({
          path: "/Products", 
          parameters: {
          custom: {
              param1: "value1",
              param2: "value2"
          }
      },
      template: rowTemplate
  });

  If you use bindElement, you can specify custom parameters as follows:

  oTextField.bindElement("/GetProducts", {
      custom: {
          "price" : "500"
      }
  });

SAPUI5 uses the concept of a "current language" (see Identifying the Language Code / Locale). This language is automatically propagated to the OData service by the OData V2 model. For this reason, applications must not hard code the language themselves, e.g. they must not specify the "sap-language" URL parameter as a custom query option.