When optimistic concurrency control is enabled for a RAP business object, the OData client reads the current ETag value with every read request and sends this value back with every modifying operation.

 

On each ETag relevant operation, the value the client sends with the request is compared to the current value of the ETag field on the database. If these values match, the change request is accepted and the data can be modified. At this point, the business object logic changes the value of the ETag field.

 

In the example in the figure, ETag Check in UPDATE Operation, both OData Clients read the data with value 'X' in the ETag field. When Client 1 sends an update request with ETag value 'X', this request is accepted because ETag field value 'X' matches the value on the database. During the update of the data, the ETag field value is changed, to 'Y' in our example.

 

The ETag mechanism ensures that the client only changes data with exactly the version the client wants to change. In particular, it is ensured that data an OData client tries to change has not been changed by another client between data retrieval and sending the change request. On modifying the entity instance, the ETag value must also be updated to log the change of the instance and to define a new version for the entity instance.

 

In the example the update request of Client 2 is rejected because it is sent with ETag field value 'X'. By comparing this value to the current value on the database, the business object logic sees that a concurrent modify access took place and that Client 2 is operating on an outdated version of the data.

 

ETag Definition and Implementation

Activation of ETag Handling in RAP

 

In RAP Business Objects, ETag handling is activated by adding keywords etag master or etag dependent to the behavior definition of the related entity. Root entities are often ETag masters that log the changes of every business object entity that is part of the BO. The keyword master is followed by the name of a field that is part of the business object entity. You must make sure that the value of this field is changed during every modify operation on this entity.

 

To expose the ETag for a service specification in the projection layer, the ETag has to be used in the projection behavior definition for each entity with the syntax use etag. The ETag type (master or dependent) is derived from the underlying behavior definition and cannot be changed in the projection behavior definition. Once the ETag is exposed to the service, OData clients will include the Tag value in any relevant request.

 

Recommended ETag Field in Managed Scenario

 

An ETag check is only possible, if the ETag field is updated with a new value whenever the data set of the entity instance is changed or created. That means, for every modify operation, except for the delete operation, the ETag value must be uniquely updated.

 

The managed scenario updates administrative fields automatically if they are annotated with the respective annotations:

• @Semantics.user.createdBy: true
• @Semantics.systemDateTime.createdAt: true
• @Semantics.user.lastChangedBy: true
• @Semantics.systemDateTimeChangedAt: true

 

If the element that is annotated with @Semantics.systemDateTime.LastChangedAt: true is used as an ETag field, it is updated automatically by the framework and receives a unique value on each update. In this case, you do not have to implement ETag field updates.

 

If you choose an element as ETag field that is not automatically updated, you have to make sure that the ETag value is updated on every modify operation via determinations.