Skip to content

upgrading-your-odata-model-cda632b.md

Latest commit

 

History

History
466 lines (298 loc) · 15.6 KB

upgrading-your-odata-model-cda632b.md

File metadata and controls

466 lines (298 loc) · 15.6 KB

Upgrading Your OData Model

On this page:

Transition to OData V4.01

OData Version 4.01 comes with many new features; for details, see What's New in OData Version 4.01. Once 4.01 will be supported by SAPUI5's v4.ODataModel, you'll need to consider various aspects. You can already start preparing your application for this transition.

While 2.7 Improved: Case-Insensitive System Query Options without $ prefix may offer convenience for handwritten requests, it's a challenge for v4.ODataModel's handling of system query options. Features like auto-$expand/$select need to take an application's $expand and $select parameters into account. Paging takes care of $top and $skip while data aggregation computes its own $apply. Thus the only supported syntax for system query options will continue to be lowercase with a leading dollar sign.

Starting with SAPUI5 1.141.0, an option that is considered an OData V4 custom query option today and might be treated as a system query option with 4.01 in the future thus causes a "[FUTURE FATAL]" warning, which will become an error when your application runs with a 4.01 service. This affects the following names: apply, compute, count, expand, filter, format, id, index, levels, orderby, schemaversion, search, select, skip, top

In general, there is a number of new features which are passed through by v4.ODataModel, but some may be incompatible for or unsupported by other parts of a client-side stack including application code. Keep in mind that switching to 4.01 requires extensive testing of your application! The following is a list of changes to pay attention to, but this is in no way meant to be complete:

Transition from OData V2 to OData V4

This section outlines the main differences between the OData V2 and OData V4 models. While some of them are due to features that have not yet been implemented, many differences are due to the following issues:

  • Protocol incompatibility between OData V4 and OData V2

  • API cleanup and simplification

  • Adherence to OData V4 standards regarding the names and terms used in APIs

These differences will therefore remain even after all features have been implemented. The table below gives you an overview of these changes, as well as the reason behind them and (if applicable) how the OData V2 model mechanism is supported in the OData V4 model.

Change

Reason

Binding parameter names: The binding parameter name for an OData system query option is identical to the system query option name: $expand, $select, ... (V2 uses expand, select).

Simplification: The OData V4 model simplifies the binding parameter structure to just one map where all entries in the map are OData query options, with the exception of entries that have a key starting with "$$" (binding-specific parameters). In all cases, the names of the binding parameters are exactly the same as in the OData URL sent to the server.

The model does not support the methods getData, getObject, getOriginalProperty, getProperty. For data access, use the context API instead of methods on the model.

OData requires asynchronous data retrieval: Synchronous data access requires that data has already been loaded from the server. This means there is no way of knowing whether this already happened, meaning the result of a synchronous access method is quite often unpredictable.

The OData V4 context API offers ansynchronous and synchronous access to the data of a specific context. It is no longer necessary to construct a path for data access as needed by the methods on the model. For more information, see the section Context API in Bindings.

Minimize APIs required for batch control: Model does not support the methods getChangeBatchGroups, getChangeGroups, getDeferredGroups, setChangeBatchGroups, setChangeGroups, setDeferredBatchGroups, setDeferredGroups, setUseBatch (and corresponding model construction parameters).

Simplification: Batch groups are solely defined via binding parameters with the corresponding parameters on the model as default. Application groups are by default deferred; there is no need to set or get deferred groups. You just need the submitBatch method on the model to control invocation of the batch. You can use the predefined batch group "$direct" to switch off batch either for the complete model or for a specific binding (only possible for the complete model in V2). For more information, see Batch Control.

OData operations invoked via binding: Model does not support the method callFunction.

Simplification: Use an operation binding instead; it is now much easier to bind operation invocation results to controls.

No CRUD methods on model: Model does not support the methods create, read, remove, update.

Simplification: read, update, create and remove operations are available implicitly via the bindings. Bindings can also be used without controls. It is not possible to initiate requests for specific OData URLs. For more information, see Accessing Data in Controller Code.

No metadata access via model: Model does not support methods getServiceAnnotations, getServiceMetadata, refreshMetadata as well as methods corresponding to the events metadataFailed, metadataLoaded.

Simplification: Metadata is only accessed via ODataMetaModel. Metadata is only loaded when needed (e.g. for type detection or to compute URLs for write requests); the corresponding methods on the v4.ODataMetaModel use promises instead of events.

sap.ui.model.odata.AnnotationHelper is not supported for OData V4.

Simplification: Much of the functionality in sap.ui.model.odata.AnnotationHelper is provided by sap.ui.model.odata.v4.ODataMetaModeland sap.ui.model.odata.v4.ODataModel. You can find the remaining functionality in the OData V4 specific sap.ui.model.odata.v4.AnnotationHelper.

Example:

The path syntax supported by the v4.ODataMetaModel, see sap.ui.model.odata.v4.ODataMetaModel, method requestObject allows for navigation in the model's metadata; there is no need to use AnnotationHelper methods for this.

The property binding automatically determines the appropriate type depending on the property's metadata, unless a type is specified explicitly.

For more information, see Type Determination.

Note:

By default, a property binding delivers a value formatted according to the target type of the control property it applies to, for exampleboolean in case of <Icon src="sap-icon://message-warning" visible="{path: 'DeliveryDate', formatter: '.isOverdue'}">. This leads to errors, because type determination adds the correct type for the DeliveryDate property, which is DateTimeOffset, and cannot format its value as boolean. In such cases, use targetType: 'any' as follows:

<Icon 
	src="sap-icon://message-warning" 
	visible="{
		path: 'DeliveryDate', 
		targetType: 'any', 
		formatter: '.isOverdue'
	}"/>

The above also applies to Expression Bindings. In this case, there is a convenience notation %{binding}, which is a shortcut for ${path: 'binding', targetType: 'any'}.

Note:

A property binding can have an object value. For more information, see Property Binding With an Object Value:

<SimpleForm binding="{/BusinessPartnerList('42')}">
	<Label text="Phone number list"/>
	<Text
		text="{
			path: 'BP_2_CONTACT', 
			mode: 'OneTime', 
			targetType: 'any', 
			formatter: '.formatPhoneNumbersAsCSV'
		}"/>
</SimpleForm>

There is no AnalyticalBinding and no ODataTreeBinding available. Data aggregation and recursive hierarchy support are available with the sap.ui.model.odata.v4.ODataListBinding using the $$aggregate binding parameter and the related sap.ui.model.odata.v4.ODataListBinding#setAggregation method.

Aggregated data as well as hierarchical data is displayed in a table or list. As a result, the interface of the table or list control and the list binding is reused and enhanced without providing new binding classes. This allows to reuse functionality of the sap.ui.model.odata.v4.ODataListBinding.

There is no global cache of entities. Instead, data is kept with respect to bindings and different data for the same entity may be displayed. As a consequence, it is important to use relative bindings as described in Data Reuse if the same data should be displayed.

It is now possible to show different states of the same entity, e.g. to allow comparison between the data states before and after a change.

A selection is managed by the ODataModel and not by the table.

The ODataModel is responsible for fetching data for the client and caching data on the client. It is important for the model to know which records are selected, so that the respective sap.ui.model.odata.v4.Context instances remain available. Also, possible future improvements require the handling of record selection in the ODataModel.

Data of selected contexts may not be available synchronously.

In applications, a user may continue editing after selecting a record. This might cause side effects; see sap.ui.model.odata.v4.Context#requestSideEffects. The user may also refresh, change, sort, or filter. In all these cases, the expectation is that the client shows up-to-date data. For selected contexts, this means that, instead of keeping their data up to date all the time, their data needs to be accessed asynchronously when needed.

Related Information:

Migration of Deprecated OData Model

Note:

The sap.ui.model.odata.ODataModel is deprecated and may be removed in a future major SAPUI5 version. As alternatives, we provide the sap.ui.model.odata.v2.ODataModel (OData V2 model) and the sap.ui.model.odata.v4.ODataModel (OData V4 model). If you're using the sap.ui.model.odata.ODataModel, migrate your OData model to either OData Version 2.0 or OData Version 4.0.

The following table shows the supported features for the sap.ui.model.odata.v2.ODataModel and sap.ui.model.odata.ODataModel:

Feature

sap.ui.model.odata.v2.ODataModel

sap.ui.model.odata.ODataModel

OData version support

2.0

2.0

JSON format

Yes (default)

Yes

XML format

Yes

Yes (default)

Support of two-way binding mode

Yes; for property changes only, not yet implemented for aggregations

Experimental; only properties of one entity can be changed at the same time

Default binding mode

One-way binding

One-way binding

Client-side sorting and filtering

Yes

For more information, see API Reference: sap.ui.model.odata.OperationMode.

No

$batch

Yes; all requests can be batched

Only manual batch requests are possible

Data cache in model

All data is cached in the model

Manually requested data is not cached

Automatic refresh

Yes (default)

Yes

Message handling

Yes, see Error, Warning, and Info Messages

No