ABAP - Keyword Documentation → ABAP RAP Business Objects → RAP - Behavior Definitions → RAP - BDL for Behavior Definitions → RAP - Managed and Unmanaged Behavior Definitions → RAP - EntityBehaviorDefinition → RAP - EntityBehaviorCharacteristics → 

    RAP - etag

    Syntax Forms

    ETag for Active Data
            etag master MasterField 
    | etag dependent by _Assoc     
    ETag for Draft Data
           total etag TotalEtagField

    Variant

    1. ... etag master MasterField 

    2. ... etag dependent by _Assoc 

    3. ... total etag TotalEtagField

    Description

    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.

    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 this particular ETag field must be guaranteed.

    In an unmanaged RAP BO, the handling of the ETag fields must be implemented in the ABAP behavior pool.

    Availability

    • Managed RAP BO
    • Unmanaged RAP BO
    • total ETag is available in draft-enabled RAP BOs only and for these, it is mandatory.
    • In a projection or interface BDEF, the optimistic concurrency control functionality can be reused with the keyword use etag. For details, see topic RAP - use, Projection and Interface BDEF.

    Hints

    • In draft-enabled RAP BOs, total ETag and ETag master/dependent complement each other and it is recommended that both are used together. Depending on the use case, separate fields or identical fields can be used as total ETag field and ETag master field.
    • 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.
    • In scenarios where the managed RAP BO provider handles the ETag fields, it is recommended that you specify the respective fields as read-only using the field characteristic readonly.
    • In an unmanaged RAP business object, it is recommended that the ETag fields are handled during the RAP save sequence.

    Further Information

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

    Variant 1

    ... etag master MasterField

    Description

    Defines an entity as RAP ETag master entity and assigns a field MasterField for change logging. The following rules apply:

    • An ETag master field is optional.
    • One or more RAP BO entities can be defined as ETag master entities and have an ETag master field assigned. RAP BO entities on each level of the CDS composition tree can be ETag master entities.
    • MasterField can have any data type that can be converted into the data type string (see the topic Assignment and Conversion Rules for details).
    • In a managed RAP BO, a value for the total ETag field can be provided automatically if the following conditions are met:
    • In unmanaged RAP BOs, the application developer must ensure that a value is provided for the ETag master field.

    Hints

    Variant 2

    ... etag dependent by _Assoc

    Description

    Defines an entity as RAP ETag dependent entity. This means that this entity does not have its own ETag field and uses the ETag field of the ETag master entity. The following rules apply to ETag dependent entities:

    • The association _Assoc to the ETag master entity must be explicitly read-enabled in the entity behavior body using the syntax:
    • The ETag master entity must be higher in the CDS composition tree than its dependent entities.

    Hint

    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 the topic RAP - SyntaxShortForm.

    Variant 3

    ... total etag TotalEtagField

    Description

    Defines a field TotalEtagField 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 following rules apply:

    • A total ETag field is mandatory for draft-enabled RAP BOs.
    • The total ETag field must be defined directly after the lock master entity lock master.
    • The total ETag field is defined in the entity behavior characteristics of the lock master entity and it controls all RAP BO entities of the current RAP BO.
    • TotalEtagField can have any data type that can be converted into the data type string (see the topic Assignment and Conversion Rules for details). Additionally, it can have a length of maximally 40 characters.
    • In a managed RAP BO, a value for the total ETag field can be provided automatically if the following conditions are met:
    • In unmanaged RAP BOs, the application developer must ensure that a value is provided for the total ETag field TotalEtagField.

    Hints

    Further Information

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