bc-code-intelligence-mcp 1.3.4 → 1.3.6

package/embedded-knowledge/domains/jordan-bridge/samples/etag-implementation.md

@@ -0,0 +1,508 @@
+# ETag Implementation for Optimistic Concurrency - AL Code Sample
+
+## Basic ETag Implementation
+
+```al
+page 50300 "Customer ETag API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'customers';
+    APIVersion = 'v1.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                field(displayName; Rec.Name)
+                {
+                    Caption = 'Display Name';
+                }
+                field(lastModifiedDateTime; Rec.SystemModifiedAt)
+                {
+                    Caption = 'Last Modified Date Time';
+                    Editable = false;
+                    // Used for ETag generation
+                }
+                // ETag field for optimistic concurrency control
+                field(etag; ETagValue)
+                {
+                    Caption = 'ETag';
+                    Editable = false;
+                }
+            }
+        }
+    }
+    
+    var
+        ETagValue: Text;
+        OriginalETagValue: Text;
+    
+    trigger OnAfterGetRecord()
+    begin
+        // Generate ETag based on SystemModifiedAt
+        ETagValue := GenerateETag(Rec.SystemModifiedAt, Rec.SystemId);
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    var
+        CurrentRecord: Record Customer;
+        CurrentETag: Text;
+    begin
+        // Validate ETag for optimistic concurrency
+        if CurrentRecord.GetBySystemId(Rec.SystemId) then begin
+            CurrentETag := GenerateETag(CurrentRecord.SystemModifiedAt, CurrentRecord.SystemId);
+            
+            // Check if record was modified by another user
+            if CurrentETag <> OriginalETagValue then
+                Error('The record has been modified by another user. Please refresh and try again.');
+        end;
+        
+        exit(true);
+    end;
+    
+    local procedure GenerateETag(ModifiedDateTime: DateTime; RecordSystemId: Guid): Text
+    var
+        TypeHelper: Codeunit "Type Helper";
+        ETagSource: Text;
+    begin
+        // Combine timestamp and SystemId for unique ETag
+        ETagSource := Format(ModifiedDateTime, 0, 9) + Format(RecordSystemId);
+        exit(TypeHelper.GetMD5Hash(ETagSource));
+    end;
+}
+```
+
+## Advanced ETag with Custom Versioning
+
+```al
+// Custom versioning table for ETag management
+table 50300 "Record Version Control"
+{
+    Caption = 'Record Version Control';
+    DataClassification = SystemMetadata;
+    
+    fields
+    {
+        field(1; "Table ID"; Integer)
+        {
+            Caption = 'Table ID';
+        }
+        field(2; "Record SystemId"; Guid)
+        {
+            Caption = 'Record SystemId';
+        }
+        field(3; "Version Number"; Integer)
+        {
+            Caption = 'Version Number';
+            InitValue = 1;
+        }
+        field(4; "Last Modified DateTime"; DateTime)
+        {
+            Caption = 'Last Modified DateTime';
+        }
+        field(5; "Modified By User"; Text[100])
+        {
+            Caption = 'Modified By User';
+        }
+        field(6; "ETag Value"; Text[100])
+        {
+            Caption = 'ETag Value';
+        }
+    }
+    
+    keys
+    {
+        key(PK; "Table ID", "Record SystemId")
+        {
+            Clustered = true;
+        }
+        key(ETag; "ETag Value")
+        {
+            // Index for fast ETag lookups
+        }
+    }
+}
+
+// ETag management codeunit
+codeunit 50300 "ETag Manager"
+{
+    // Generate and store ETag for record
+    procedure GenerateETag(TableID: Integer; RecordSystemId: Guid): Text
+    var
+        VersionControl: Record "Record Version Control";
+        ETagValue: Text;
+        VersionNumber: Integer;
+    begin
+        // Get or create version record
+        if VersionControl.Get(TableID, RecordSystemId) then begin
+            VersionNumber := VersionControl."Version Number" + 1;
+        end else begin
+            VersionControl.Init();
+            VersionControl."Table ID" := TableID;
+            VersionControl."Record SystemId" := RecordSystemId;
+            VersionNumber := 1;
+        end;
+        
+        // Generate ETag from version and timestamp
+        ETagValue := StrSubstNo('%1-%2-%3', 
+                                TableID, 
+                                VersionNumber, 
+                                Format(CurrentDateTime, 0, 9));
+        
+        // Update version control record
+        VersionControl."Version Number" := VersionNumber;
+        VersionControl."Last Modified DateTime" := CurrentDateTime;
+        VersionControl."Modified By User" := UserId;
+        VersionControl."ETag Value" := ETagValue;
+        
+        if VersionControl."Version Number" = 1 then
+            VersionControl.Insert()
+        else
+            VersionControl.Modify();
+            
+        exit(ETagValue);
+    end;
+    
+    // Validate ETag for concurrency control
+    procedure ValidateETag(TableID: Integer; RecordSystemId: Guid; ProvidedETag: Text): Boolean
+    var
+        VersionControl: Record "Record Version Control";
+    begin
+        if not VersionControl.Get(TableID, RecordSystemId) then
+            exit(false);  // No version record exists
+            
+        exit(VersionControl."ETag Value" = ProvidedETag);
+    end;
+    
+    // Get current ETag for record
+    procedure GetCurrentETag(TableID: Integer; RecordSystemId: Guid): Text
+    var
+        VersionControl: Record "Record Version Control";
+    begin
+        if VersionControl.Get(TableID, RecordSystemId) then
+            exit(VersionControl."ETag Value");
+        exit('');
+    end;
+}
+
+// API page with advanced ETag implementation
+page 50301 "Item Advanced ETag API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'inventory';
+    APIVersion = 'v1.0';
+    EntityName = 'item';
+    EntitySetName = 'items';
+    SourceTable = Item;
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                field(displayName; Rec.Description)
+                {
+                    Caption = 'Display Name';
+                }
+                field(unitPrice; Rec."Unit Price")
+                {
+                    Caption = 'Unit Price';
+                }
+                field(inventory; Rec.Inventory)
+                {
+                    Caption = 'Inventory';
+                    Editable = false;
+                }
+                field(etag; ETagValue)
+                {
+                    Caption = 'ETag';
+                    Editable = false;
+                }
+                field(version; VersionNumber)
+                {
+                    Caption = 'Version';
+                    Editable = false;
+                }
+            }
+        }
+    }
+    
+    var
+        ETagValue: Text;
+        VersionNumber: Integer;
+        ETagManager: Codeunit "ETag Manager";
+        ProvidedETag: Text;
+    
+    trigger OnAfterGetRecord()
+    var
+        VersionControl: Record "Record Version Control";
+    begin
+        // Get current ETag and version
+        ETagValue := ETagManager.GetCurrentETag(Database::Item, Rec.SystemId);
+        
+        if VersionControl.Get(Database::Item, Rec.SystemId) then
+            VersionNumber := VersionControl."Version Number"
+        else
+            VersionNumber := 0;
+            
+        // Generate ETag if not exists
+        if ETagValue = '' then
+            ETagValue := ETagManager.GenerateETag(Database::Item, Rec.SystemId);
+    end;
+    
+    trigger OnInsertRecord(BelowxRec: Boolean): Boolean
+    begin
+        // Generate initial ETag for new record
+        ETagValue := ETagManager.GenerateETag(Database::Item, Rec.SystemId);
+        exit(true);
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    begin
+        // Validate provided ETag before modification
+        if ProvidedETag <> '' then begin
+            if not ETagManager.ValidateETag(Database::Item, Rec.SystemId, ProvidedETag) then
+                Error('Concurrency conflict detected. The record has been modified by another user. ETag: %1', ProvidedETag);
+        end;
+        
+        // Generate new ETag after successful modification
+        ETagValue := ETagManager.GenerateETag(Database::Item, Rec.SystemId);
+        exit(true);
+    end;
+    
+    trigger OnDeleteRecord(): Boolean
+    var
+        VersionControl: Record "Record Version Control";
+    begin
+        // Validate ETag before deletion
+        if ProvidedETag <> '' then begin
+            if not ETagManager.ValidateETag(Database::Item, Rec.SystemId, ProvidedETag) then
+                Error('Concurrency conflict detected. Cannot delete record that has been modified.');
+        end;
+        
+        // Clean up version control record
+        if VersionControl.Get(Database::Item, Rec.SystemId) then
+            VersionControl.Delete();
+            
+        exit(true);
+    end;
+}
+```
+
+## HTTP Header ETag Processing
+
+```al
+// Codeunit for processing ETag HTTP headers
+codeunit 50301 "HTTP ETag Processor"
+{
+    // Extract ETag from If-Match header
+    procedure ExtractETagFromHeader(HttpHeaders: Dictionary of [Text, Text]): Text
+    var
+        ETagHeader: Text;
+        ETagValue: Text;
+    begin
+        // Check If-Match header for ETag value
+        if HttpHeaders.Get('If-Match', ETagHeader) then begin
+            // Remove quotes from ETag value
+            ETagValue := ETagHeader.Replace('"', '');
+            exit(ETagValue);
+        end;
+        
+        // Check If-None-Match header
+        if HttpHeaders.Get('If-None-Match', ETagHeader) then begin
+            ETagValue := ETagHeader.Replace('"', '');
+            exit(ETagValue);
+        end;
+        
+        exit('');
+    end;
+    
+    // Set ETag in response headers
+    procedure SetETagResponseHeader(var HttpHeaders: Dictionary of [Text, Text]; ETagValue: Text)
+    begin
+        if ETagValue <> '' then
+            HttpHeaders.Set('ETag', '"' + ETagValue + '"');
+    end;
+    
+    // Process conditional request based on ETag
+    procedure ProcessConditionalRequest(ProvidedETag: Text; CurrentETag: Text; RequestMethod: Text): Boolean
+    begin
+        case RequestMethod of
+            'GET':
+                // If-None-Match: return 304 if ETags match
+                exit(ProvidedETag <> CurrentETag);
+            'PUT', 'PATCH', 'DELETE':
+                // If-Match: proceed only if ETags match
+                exit(ProvidedETag = CurrentETag);
+            else
+                exit(true);
+        end;
+    end;
+}
+
+// API page with HTTP ETag header processing
+page 50302 "Sales Order ETag API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'sales';
+    APIVersion = 'v1.0';
+    EntityName = 'salesOrder';
+    EntitySetName = 'salesOrders';
+    SourceTable = "Sales Header";
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    SourceTableView = WHERE("Document Type" = CONST(Order));
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                field(customerNumber; Rec."Sell-to Customer No.")
+                {
+                    Caption = 'Customer Number';
+                }
+                field(orderDate; Rec."Order Date")
+                {
+                    Caption = 'Order Date';
+                }
+                field(totalAmount; TotalAmount)
+                {
+                    Caption = 'Total Amount';
+                    Editable = false;
+                }
+                field(etag; ETagValue)
+                {
+                    Caption = 'ETag';
+                    Editable = false;
+                }
+            }
+        }
+    }
+    
+    var
+        ETagValue: Text;
+        TotalAmount: Decimal;
+        ETagManager: Codeunit "ETag Manager";
+        HttpETagProcessor: Codeunit "HTTP ETag Processor";
+        RequestETag: Text;
+    
+    trigger OnAfterGetRecord()
+    begin
+        // Calculate totals
+        Rec.CalcFields("Amount Including VAT");
+        TotalAmount := Rec."Amount Including VAT";
+        
+        // Generate ETag based on header and line modifications
+        ETagValue := GenerateOrderETag();
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    var
+        CurrentETag: Text;
+    begin
+        // Get current ETag for comparison
+        CurrentETag := GenerateOrderETag();
+        
+        // Validate provided ETag matches current state
+        if (RequestETag <> '') and (RequestETag <> CurrentETag) then
+            Error('Concurrency conflict: Order has been modified by another user. Current ETag: %1, Provided ETag: %2', CurrentETag, RequestETag);
+            
+        exit(true);
+    end;
+    
+    local procedure GenerateOrderETag(): Text
+    var
+        SalesLine: Record "Sales Line";
+        ETagSource: Text;
+        TypeHelper: Codeunit "Type Helper";
+        LineModificationTime: DateTime;
+    begin
+        // Build ETag from header and all related lines
+        ETagSource := Format(Rec.SystemModifiedAt, 0, 9);
+        
+        // Include line modifications in ETag
+        SalesLine.SetRange("Document Type", Rec."Document Type");
+        SalesLine.SetRange("Document No.", Rec."No.");
+        if SalesLine.FindLast() then
+            LineModificationTime := SalesLine.SystemModifiedAt
+        else
+            LineModificationTime := Rec.SystemModifiedAt;
+            
+        ETagSource += Format(LineModificationTime, 0, 9);
+        ETagSource += Format(Rec.SystemId);
+        
+        // Generate hash-based ETag
+        exit(TypeHelper.GetMD5Hash(ETagSource));
+    end;
+}
+```
+
+## Implementation Notes
+
+**ETag Implementation Best Practices:**
+
+1. **ETag Generation Strategies:**
+   - Use SystemModifiedAt for simple timestamp-based ETags
+   - Combine multiple factors (timestamp + SystemId + version) for robust ETags
+   - Include related record modifications for composite entities
+   - Use consistent hashing algorithms (MD5, SHA-256) for ETag values
+
+2. **Concurrency Control:**
+   - Validate ETags on all modification operations (PUT, PATCH, DELETE)
+   - Return appropriate HTTP status codes (409 Conflict, 412 Precondition Failed)
+   - Implement version tracking for detailed conflict resolution
+   - Provide clear error messages for concurrency conflicts
+
+3. **Performance Optimization:**
+   - Index ETag fields for fast lookups
+   - Cache ETag values to avoid recalculation
+   - Use efficient ETag generation algorithms
+   - Minimize database queries during ETag validation
+
+4. **HTTP Integration:**
+   - Process If-Match and If-None-Match headers correctly
+   - Set ETag response headers for all API responses
+   - Support conditional requests (304 Not Modified responses)
+   - Handle weak vs strong ETag semantics appropriately