Skip to content

Client-only Entities Overview

The client-only entities feature is an extension to Offline OData that enables the client application to load client-only metadata and perform OData CRUD operations on entity sets that do not exist in the OData back-end server. The term "client only" or "client-only" means that the entities exist in the client store only, and will never be uploaded to the back-end store.

Annotation Terms For Client-only Entities

The OData protocol allows models and instance elements to be decorated with Annotations. Models annotated with the term com.sap.vocabularies.Offline.v1.ClientOnly exist only on client devices. Typically, for each entity type there is one corresponding entity set that uses the entity type. However, OData permits having multiple entity sets sharing the same entity type. This provides the capability to define a local draft entity set for a back-end entity type. An entity set annotated with the term com.sap.vocabularies.Offline.v1.LocalDraft is a draft set that uses the same entity type as its active entity set defined in the back-end metadata.

Benefit Of Client-only Entities

The back end usually has a predefined set of models that cannot be changed occasionally. The client application may need to verify new features in OData to periodically persist data to the local database. Allowing a client application to use locally-defined metadata can support the acceleration of application prototyping and development in the following ways:

  • Preserve data in the local device

    The client-only entities will stay on the client device forever and will never be uploaded to the server. Users can use Offline OData to store "temporary data" utilizing the same technique as for server data.

  • Create and access local database tables using the OData API

    Traditionally, to access a local database, users would need to create and manage the database tables, writing SQL queries or using ORM to manipulate the data. The client-only feature leverages the capability to create tables in the local database and perform the CRUD operation using the unified OData API. Each client-only entity type is backed by a local database table. Each property in the client-only entity type has a column in the local database table. The OData CRUD operation actually operates on the back-end database tables.

  • Application prototyping

    Using client-only models, an application developer is free to try any kind of OData application prototyping without the need to have everything ready in the back end.

  • Try out new features locally without changing the back end.

    For example, the back end may not have the latest features defined in OData 4.0. A client application can define those types introduced since OData 4.0 in the client-only metadata and try using them without changing the back end.

  • Make a draft copy of an entity value.

    Using client-only entities, it is possible to make a draft copy of some entity value and save it into the draft set for later use.

Comparing With Partial Upload

UploadCategory provides the capability to selectively upload a subset of local changes to OData back end. The uploading of a subset of local changes is called partial upload. With partial upload, some categories of locally-modified data can also be kept on the local device without having to upload that category to the server. However, application developers need to maintain the upload categories very carefully for every modification request, and conflicts may occur if the entity is updated in the back end. The client-only entities are guaranteed to stay on the local device without requiring any extra effort.

Enable Client-only Entity

From a developer's perspective, developing a client application that supports client-only entities is nearly the same as developing a typical Offline OData application, with the following additional requirements. You will need to:

  • Edit the metadata fetched from the back end to add client-only models into the metadata.

  • Generate proxy classes with the updated metadata that contains client-only entities definitions.

  • Enable client-only metadata in OfflineODataParameters.

After completing these steps, everything is ready, and accessing the client-only entity sets defined in the metadata will be exactly the same as accessing entity sets defined in the back-end metadata.

OData Version And Client-only Entities

The Offline OData client database is initially populated with the back-end metadata, and the supported OData version is the OData service version of the back-end metadata. Due to this limitation, the client-only models have to comply with the OData version of the back end. Thus, if the back end has OData 4.0, the client-only metadata has to be OData 4.0. If the back end is OData 2.0. then the client-only metadata has to be OData 2.0. Mixed usage of OData 2.0 and OData 4.0 in the same database is not supported. The only exception is for the terms defined in the Offline Vocabulary. The ClientOnly annotation is used to annotate client-only models for both OData 2.0 and OData 4.0, even though the annotation is introduced in OData 4.0.

Last update: June 15, 2023