Kontakt

Ansicht
Dokumentation

ABENBDL_ETAG - BDL ETAG

ABENBDL_ETAG - BDL ETAG

rdisp/max_wprun_time - Maximum work process run time   ABAP Short Reference  
This documentation is copyright by SAP AG.
SAP E-Book

- etag

ETag for active version

  etag master MasterField
$| etag dependent by _Assoc

ETag for draft version
  total etag TotalEtagField

Variants:

1. ... etag master MasterField

2. ... etag dependent by _Assoc

3. ... total etag TotalEtagField

Effect

Defines a field as entity tag (ETag) field for optimistic concurrency control. A field flagged as ETag field is used to describe, uniquely, the state of a requested resource (for example a specific entity instance). Any changes made to the requested resource update the ETag field. On each change request, the value of the ETag field is compared to the value the RAP BO consumer sends with the request and only if these values match is the change request accepted. This way, inconsistencies and unintentional changes of data are prevented when multiple users work on the same data. Often fields containing time stamps, hash values, or any other versioning that precisely identifies the version of the data set are used.

etag master and etag dependent can optionally be used for the persistent data of a business object. They are defined at entity-level in the entity behavior characteristics for each RAP BO entity separately. If an entity is an ETag master entity, it has its own ETag field. An ETag dependent entity uses the ETag field of another entity for optimistic concurrency control.

total etag is available only for draft-enabled business objects and for these, it is recommended. It manages the transitions from active data to draft data and vice versa.

In a managed RAP BO, optimistic concurrency control with ETag fields can be handled by the managed RAP BO provider, so that no implementation in the ABAP behavior pool is required. This is only possible if the following prerequisites are met:

  • The read access to the ETag master field from every entity that uses an ETag must be guaranteed.

In a projection or interface behavior definition, the optimistic concurrency control functionality can be reused with the keyword use etag. For details, see topic CDS BDL - use.

Notes

  • In draft-enabled RAP BOs, total ETag and ETag master/dependent complement each other and it is recommended that both are used together. Since both serve different purposes, separate fields must be used to enable both functionalities.
  • The RAP framework offers reuse data elements that can be used as ETag and total ETag fields. For more information, see RAP Reuse Data Elements.

Development guide for the ABAP RESTful Application Programming Model, section about Optimistic Concurrency Control.

Example - Managed

The following example shows a managed BDEF based on the CDS root view entity DEMO_RAP_MANAGED_DRAFT_1. The BDEF is draft-enabled and it defines a total etag field as well as an etag master field.

The program DEMO_RAP_MANAGED_TOTAL_ETAG accesses the business object using EML and executes the following actions:

  • First, it creates a new draft instance.
  • Then, it creates a new active instance.
  • Finally, it activates the new draft instance.

The entries of the database tables after each of these actions are shown. Both the ETag field and the total ETag field of the persistent database table are automatically filled with a time stamp period.

Result: the ETag field LCHG_DATE_TIME and the total ETag field CREA_DATE_TIME are automatically filled with a time stamp value.

IMAGE @@ABDOC_ETag.png@@635@@359@@

Example - Unmanaged

The following example shows an unmanaged BDEF based on the CDS root view entity DEMO_RAP_UNMANAGED_DRAFT_ROOT. The BDEF is draft-enabled and it defines a total etag field as well as an etag master field.

In the ABAP behavior pool, the create method provides values for the etag master and for the total etag fields using the function GET TIME STAMP.

Code snippet:

The program DEMO_RAP_UNMANAGED_TOTAL_ETAG accesses the business object using EML and executes the following actions:

  • First, it creates a new draft instance.
  • Then, it creates a new active instance.
  • Finally, it activates the new draft instance.

Result: the ETag field LCHG_DATE_TIME and the total ETag field CREA_DATE_TIME are automatically filled with a time stamp value

IMAGE @@ABDOC_ETag.png@@635@@359@@

Variant 1

... etag master MasterField


Effect

  • Defines an entity as ETag master and assigns a field MasterField for change logging. Root entities are often ETag masters that log the changes of every business object entity that is part of the BO.
  • In a managed RAP BO, a value for the total ETag field can be provided automatically if the following conditions are met:
  • The ETag field MasterField must be annotated in CDS with the annotation @Semantics.systemDateTime.localInstanceLastChangedAt: true

  • The data type must be date compatible.

  • In unmanaged RAP BO, the application developer must ensure that a value is provided for the total ETag field by filling the respective field in the implementation of all MODIFY ENTITY operations.
  • 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 ENTITY operation via determinations.
  • In a managed RAP BO, the RAP read operation is always implicitly available and therefore, this prerequisite is always fulfilled.

Variant 2

... etag dependent by _Assoc


  • Defines an entity as ETag dependent. This means that this entity does not have its own ETag field and uses the ETag field of the ETag master entity. The association to the ETag master entity must be explicitly read-enabled in the entity behavior body using the syntax:
association _AssocToETagMaster { }
This association must also be defined in the underlying CDS data model.
  • An ETag master entity must always be higher in the BO composition structure than its dependent entities.
  • The following syntax short form is available to summarize lock dependent, ETag dependent, and authorization dependent:
($[lock$]$[, authorization$]$[, etag$]) dependent by _assoc
For details, see topic syntax_short_form.

Variant 3

... total etag TotalEtagField


Defines a field as total ETag field for draft-enabled scenarios to enable optimistic concurrency checks during the transition from draft to persistent data. If a user edits data in draft mode and returns after the exclusive lock of their editing session has expired, the total etag checks whether the persistent data has been changed during the period of absence. Each time the persistent state is changed, the total etag field is updated. To resume a draft version, the infrastructure first compares the total etag of the persistent and the draft version and only if both values are identical the draft can be resumed.

The total ETag field is defined in the entity behavior characteristics of the lock master entity (currently identical to the root entity) and it controls the whole business object. A total ETag field is recommended for draft-enabled BOs. Its position is important: it must be defined directly after the lock master definition in the behavior definition.

A value for the total ETag field can be provided automatically in the managed RAP BO if the following conditions are met:

  • The field that is specified as TotalEtagField must be annotated in CDS with the annotation @Semantics.systemDateTime.lastChangedAt: true and the data type must be date compatible.
  • The total ETag field must be included in the type mapping in the entity behavior definition body, if its name in the database table and in the CDS view model differs.

In unmanaged RAP BOs, the application developer must ensure that a value is provided for the total ETag field by filling the respective field in the implementation of all MODIFY ENTITY operations.

Note

If BDEF strict mode is enabled, draft-enabled scenarios require a total etag field. Otherwise, a syntax error occurs.

For further details, see topic Total ETag in the development guide for the ABAP RESTful Application Programming Model.






ABAP Short Reference   ABAP Short Reference  
This documentation is copyright by SAP AG.

Length: 15721 Date: 20240418 Time: 072512     sap01-206 ( 224 ms )