Get Example source ABAP code based on a different SAP table
• ETAG MASTER ABAP_BDL_PROP • ETAG DEPENDENT BY ABAP_BDL_PROP • TOTAL ETAG ABAP_BDL_PROP
ABAP_RAP - etag
ABAP_SYNTAX_FORMS
ETag for Active Version etag master MasterField $| etag dependent by _Assoc
ETag for Draft Version total etag TotalEtagField
ABAP_VARIANTS: 1 ... etag master MasterField 2 ... etag dependent by _Assoc 3 ... total etag TotalEtagField
What does it do? 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 ETag field must be updated reliably with every change on the RAP BO entity instance.
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 TITLE .
Latest 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. NON_V5_HINTS ABAP_HINT_END
ABAP_FURTHER_INFO Development guide for the ABAP RESTful Application Programming Model, section about Optimistic Concurrency Control.
ABAP_EXAMPLE_VX5 - 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. ABAP_NOTE This example does not fully meet the requirements of the RAP BO contract. It is intentionally kept short and simple and serves demonstration purposes only. See more information on the RAP BO contract in the Development guide for the ABAP RESTful Application Programming Model. BDEF DEMO_RAP_MANAGED_DRAFT_1 The class CL_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 ABAP_EXAMPLE_END
ABAP_EXAMPLE_VX5 - 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. BDEF DEMO_RAP_UNMANAGED_DRAFT_ROOT 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: METH bp_demo_rap_unmanaged_draft_ro(CCIMP)=>create The class CL_DEMO_RAP_UNMNGD_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 ABAP_EXAMPLE_END
ABAP_VARIANT_1 ... etag master MasterField
What does it do?
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.
ABAP_VARIANT_2 ... etag dependent by _Assoc
What does it do?
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 TITLE .
ABAP_VARIANT_3 ... total etag TotalEtagField
What does it do? 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 RAP BO 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.
Latest notes: If BDEF strict mode is enabled, draft-enabled scenarios require a total etag field. Otherwise, a syntax error occurs. NON_V5_HINTS ABAP_HINT_END
ABAP_FURTHER_INFO For further details, see topic Total ETag in the development guide for the ABAP RESTful Application Programming Model.
