slashdev 1.1.0 → 1.2.0

package/claude-skills/salesforce-development/references/apex-patterns.md

@@ -0,0 +1,388 @@
+# Apex Patterns — Reference
+
+Load this file when implementing triggers, async Apex, integrations, or custom exceptions.
+
+---
+
+## TriggerHandler Base Class
+
+A virtual base class that routes trigger context to named methods. Provides bypass control
+(disable a handler during data migrations), recursion guards, and a clean extension point.
+
+```apex
+public virtual class TriggerHandler {
+
+    // Bypass management
+    private static Set<String> bypassedHandlers = new Set<String>();
+
+    // Recursion control
+    private static Map<String, Integer> loopCountMap = new Map<String, Integer>();
+    private static Map<String, Integer> maxLoopMap = new Map<String, Integer>();
+
+    @TestVisible
+    private TriggerOperation context;
+    @TestVisible
+    private Boolean isTriggerExecuting;
+
+    public TriggerHandler() {
+        this.setTriggerContext();
+    }
+
+    // --- Public API ---
+
+    public void run() {
+        if (!validateRun()) return;
+        addToLoopCount();
+
+        switch on this.context {
+            when BEFORE_INSERT  { this.beforeInsert(); }
+            when BEFORE_UPDATE  { this.beforeUpdate(); }
+            when BEFORE_DELETE  { this.beforeDelete(); }
+            when AFTER_INSERT   { this.afterInsert(); }
+            when AFTER_UPDATE   { this.afterUpdate(); }
+            when AFTER_DELETE   { this.afterDelete(); }
+            when AFTER_UNDELETE { this.afterUndelete(); }
+        }
+    }
+
+    // --- Bypass control ---
+
+    public static void bypass(String handlerName) {
+        bypassedHandlers.add(handlerName);
+    }
+
+    public static void clearBypass(String handlerName) {
+        bypassedHandlers.remove(handlerName);
+    }
+
+    public static Boolean isBypassed(String handlerName) {
+        return bypassedHandlers.contains(handlerName);
+    }
+
+    public static void clearAllBypasses() {
+        bypassedHandlers.clear();
+    }
+
+    // --- Recursion control ---
+
+    public void setMaxLoopCount(Integer max) {
+        String handlerName = getHandlerName();
+        maxLoopMap.put(handlerName, max);
+    }
+
+    public void clearMaxLoopCount() {
+        maxLoopMap.remove(getHandlerName());
+    }
+
+    // --- Virtual methods — override in subclasses ---
+
+    protected virtual void beforeInsert() {}
+    protected virtual void beforeUpdate() {}
+    protected virtual void beforeDelete() {}
+    protected virtual void afterInsert() {}
+    protected virtual void afterUpdate() {}
+    protected virtual void afterDelete() {}
+    protected virtual void afterUndelete() {}
+
+    // --- Private helpers ---
+
+    private void setTriggerContext() {
+        this.isTriggerExecuting = Trigger.isExecuting;
+        this.context = Trigger.operationType;
+    }
+
+    private Boolean validateRun() {
+        if (!this.isTriggerExecuting) {
+            throw new TriggerHandlerException('TriggerHandler called outside of trigger context');
+        }
+        return !bypassedHandlers.contains(getHandlerName());
+    }
+
+    private void addToLoopCount() {
+        String handlerName = getHandlerName();
+        if (!loopCountMap.containsKey(handlerName)) {
+            loopCountMap.put(handlerName, 0);
+        }
+        Integer count = loopCountMap.get(handlerName) + 1;
+        loopCountMap.put(handlerName, count);
+
+        if (maxLoopMap.containsKey(handlerName) && count > maxLoopMap.get(handlerName)) {
+            throw new TriggerHandlerException(
+                'Max loop count of ' + maxLoopMap.get(handlerName) +
+                ' reached for ' + handlerName
+            );
+        }
+    }
+
+    private String getHandlerName() {
+        return String.valueOf(this).split(':')[0];
+    }
+
+    public class TriggerHandlerException extends Exception {}
+}
+```
+
+### Example Subclass — Detecting Field Changes
+
+```apex
+public class OpportunityTriggerHandler extends TriggerHandler {
+
+    public OpportunityTriggerHandler() {
+        super();
+        this.setMaxLoopCount(2);  // Guard against recursion from cross-object updates
+    }
+
+    protected override void afterUpdate() {
+        List<Opportunity> stageChanged = new List<Opportunity>();
+        Map<Id, Opportunity> oldMap = (Map<Id, Opportunity>) Trigger.oldMap;
+
+        for (Opportunity opp : (List<Opportunity>) Trigger.new) {
+            if (opp.StageName != oldMap.get(opp.Id).StageName
+                && opp.StageName == 'Closed Won') {
+                stageChanged.add(opp);
+            }
+        }
+
+        if (!stageChanged.isEmpty()) {
+            OpportunityService.handleClosedWon(stageChanged);
+        }
+    }
+}
+```
+
+### Bypassing Handlers in Data Migrations
+
+```apex
+// In a Batch Apex execute() or anonymous script:
+TriggerHandler.bypass('OpportunityTriggerHandler');
+update records;
+TriggerHandler.clearBypass('OpportunityTriggerHandler');
+```
+
+---
+
+## Queueable with Callouts and Chaining
+
+`Queueable` is the default async pattern. It supports complex types, callouts (with the
+`Database.AllowsCallouts` interface), and job chaining.
+
+```apex
+public class SyncAccountToERP implements Queueable, Database.AllowsCallouts {
+
+    private List<Id> accountIds;
+
+    public SyncAccountToERP(List<Id> accountIds) {
+        this.accountIds = accountIds;
+    }
+
+    public void execute(QueueableContext ctx) {
+        List<Account> accounts = [
+            SELECT Id, Name, BillingStreet, BillingCity, BillingState
+            FROM Account
+            WHERE Id IN :this.accountIds
+        ];
+
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:ERP_API/accounts/sync');
+        req.setMethod('POST');
+        req.setHeader('Content-Type', 'application/json');
+        req.setBody(JSON.serialize(accounts));
+
+        HttpResponse res = new Http().send(req);
+
+        if (res.getStatusCode() != 200) {
+            // Log failure — don't silently swallow
+            ErrorLogger.log('SyncAccountToERP', 'HTTP ' + res.getStatusCode(), res.getBody());
+        }
+
+        // Chain next job if there are more records to process
+        // Guard with !Test.isRunningTest() because chaining in tests causes
+        // "Maximum stack depth reached" errors
+        if (!this.accountIds.isEmpty() && !Test.isRunningTest()) {
+            System.enqueueJob(new SyncAccountFollowUp(this.accountIds));
+        }
+    }
+}
+```
+
+### Enqueuing from a trigger
+
+```apex
+// In a trigger handler's afterInsert():
+if (!System.isBatch() && !System.isFuture()) {
+    System.enqueueJob(new SyncAccountToERP(accountIds));
+}
+```
+
+---
+
+## Batch Apex
+
+Use Batch Apex when processing more than 50K records. Implements `Database.Batchable<SObject>`
+and optionally `Database.Stateful` to maintain state across `execute()` calls.
+
+```apex
+public class DeactivateStaleLeadsBatch implements Database.Batchable<SObject>, Database.Stateful {
+
+    private Integer totalProcessed = 0;  // Stateful — survives between execute() calls
+    private Integer totalErrors = 0;
+
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Status
+            FROM Lead
+            WHERE LastActivityDate < LAST_N_DAYS:90
+              AND IsConverted = false
+              AND Status != 'Closed - Not Converted'
+        ]);
+    }
+
+    public void execute(Database.BatchableContext bc, List<Lead> scope) {
+        for (Lead l : scope) {
+            l.Status = 'Closed - Not Converted';
+        }
+
+        List<Database.SaveResult> results = Database.update(scope, false);  // partial success
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                totalProcessed++;
+            } else {
+                totalErrors++;
+            }
+        }
+    }
+
+    public void finish(Database.BatchableContext bc) {
+        // Post-processing: send summary email, enqueue follow-up, log results
+        System.debug('DeactivateStaleLeads — processed: ' + totalProcessed + ', errors: ' + totalErrors);
+    }
+}
+```
+
+### Launching a Batch
+
+```apex
+// Default scope size is 200 — reduce for callout-heavy batches
+Database.executeBatch(new DeactivateStaleLeadsBatch(), 200);
+```
+
+---
+
+## Scheduled Job
+
+Schedulable classes run on a cron schedule. Keep the `execute()` body minimal — enqueue a
+Queueable or kick off a Batch.
+
+```apex
+public class NightlyLeadCleanupSchedule implements Schedulable {
+
+    public void execute(SchedulableContext ctx) {
+        Database.executeBatch(new DeactivateStaleLeadsBatch(), 200);
+    }
+}
+```
+
+### Scheduling via Anonymous Apex
+
+```apex
+// Run nightly at 2 AM
+String cronExpr = '0 0 2 * * ?';
+System.schedule('Nightly Lead Cleanup', cronExpr, new NightlyLeadCleanupSchedule());
+```
+
+---
+
+## Integration Callout Pattern
+
+Standard pattern for HTTP callouts via Named Credentials with proper error handling.
+
+```apex
+public with sharing class ExternalAccountService {
+
+    public static ExternalAccount getAccount(String externalId) {
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:ExternalSystem/api/v2/accounts/' + EncodingUtil.urlEncode(externalId, 'UTF-8'));
+        req.setMethod('GET');
+        req.setTimeout(30000);  // 30 second timeout
+
+        HttpResponse res = new Http().send(req);
+
+        if (res.getStatusCode() == 200) {
+            return (ExternalAccount) JSON.deserialize(res.getBody(), ExternalAccount.class);
+        } else if (res.getStatusCode() == 404) {
+            return null;
+        } else {
+            throw new CalloutException(
+                'External API error: HTTP ' + res.getStatusCode() + ' — ' + res.getBody()
+            );
+        }
+    }
+
+    // DTO for deserialization
+    public class ExternalAccount {
+        public String id;
+        public String name;
+        public String status;
+    }
+}
+```
+
+### Calling from a trigger (async required)
+
+```apex
+// WRONG — triggers cannot make sync callouts
+// HttpResponse res = new Http().send(req);  // throws CalloutException
+
+// RIGHT — enqueue a Queueable
+System.enqueueJob(new SyncAccountToERP(accountIds));
+```
+
+### @future vs Queueable from trigger context
+
+- `@future(callout=true)` — simpler, but only accepts primitive parameters
+  (`Id`, `String`, `List<Id>`). No chaining, no complex objects.
+- `Queueable` with `Database.AllowsCallouts` — accepts complex types, supports chaining,
+  allows state tracking. **Prefer this.**
+
+---
+
+## Custom Exception Patterns
+
+Create domain-specific exceptions to distinguish business logic failures from platform errors.
+
+```apex
+public class AccountServiceException extends Exception {}
+public class IntegrationException extends Exception {}
+public class ValidationException extends Exception {
+    public List<String> fieldErrors { get; private set; }
+
+    public ValidationException(List<String> fieldErrors) {
+        this('Validation failed: ' + String.join(fieldErrors, '; '));
+        this.fieldErrors = fieldErrors;
+    }
+}
+```
+
+### When to throw vs return
+
+- **Throw** when the caller cannot reasonably continue — missing required data, integration
+  failure, security violation.
+- **Return a result object** when partial success is expected — batch processing, multi-record
+  validation where you want to collect all errors before reporting.
+
+```apex
+public class OperationResult {
+    public Boolean isSuccess;
+    public List<String> errors = new List<String>();
+    public List<SObject> successRecords = new List<SObject>();
+
+    public OperationResult() {
+        this.isSuccess = true;
+    }
+
+    public void addError(String message) {
+        this.isSuccess = false;
+        this.errors.add(message);
+    }
+}
+```