BeforeUpdate.RecursionGuard
Cap how many times a Populator acts on the same record in one transaction.
Signature
apex
public interface RecursionGuard {
Integer maxRunsPerRecordOnBeforeUpdate();
}maxRunsPerRecordOnBeforeUpdate(): called once per chunk, when the handler list is built. Returns how many times one record may qualify for this handler in the transaction.
Only a Populator uses it; a Validator ignores it.
Example
apex
public with sharing class ContactPopulator implements BeforeUpdate.Populator, BeforeUpdate.RecursionGuard {
public Integer maxRunsPerRecordOnBeforeUpdate() {
return 1;
}
public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
return record.isChanged(Contact.Email);
}
public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
record.put(Contact.HasOptedOutOfEmail, false);
}
}cls
public with sharing class OpportunityClosingPopulator implements BeforeUpdate.Populator, BeforeUpdate.RecursionGuard {
public Integer maxRunsPerRecordOnBeforeUpdate() {
return 1;
}
public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
Opportunity newOpportunity = (Opportunity) record.getNewSObject();
return record.isChanged(Opportunity.StageName) && new Set<String>{ 'Closed Won', 'Closed Lost' }.contains(newOpportunity.StageName);
}
public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
Opportunity newOpportunity = (Opportunity) record.getNewSObject();
Opportunity oldOpportunity = (Opportunity) record.getOldSObject();
record.put(Opportunity.NextStep, null);
String closingNote = newOpportunity.StageName + ' by ' + UserInfo.getName() + ' on ' + Date.today().format() + ' (previous stage: ' + oldOpportunity.StageName + ')';
record.put(Opportunity.Description, record.isBlank(Opportunity.Description) ? closingNote : newOpportunity.Description + '\n' + closingNote);
}
}cls
public with sharing class AccountTypeAuditPopulator implements BeforeUpdate.Populator, BeforeUpdate.RecursionGuard {
public Integer maxRunsPerRecordOnBeforeUpdate() {
return 1;
}
public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
return record.isChanged(Account.Type);
}
public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
Account newAccount = (Account) record.getNewSObject();
Account oldAccount = (Account) record.getOldSObject();
String auditLine =
Datetime.now().format('yyyy-MM-dd HH:mm') +
' - Type ' +
(oldAccount.Type ?? 'none') +
' -> ' +
(newAccount.Type ?? 'none') +
' by ' +
UserInfo.getName();
record.put(Account.Description, this.stampedDescription(auditLine, newAccount.Description));
}
private String stampedDescription(String auditLine, String description) {
String stamped = String.isBlank(description) ? auditLine : auditLine + '\n' + description;
return stamped.length() > 32000 ? stamped.left(32000) : stamped;
}
}Rules
- Without it, the depth is 3 and nothing is skipped. When a record comes back after 3 passes, each run logs an error and the Populator keeps acting.
- It counts qualifying passes. The count goes up by 1 each time the predicate returns true for a record Id. It is not the nesting level. RecursionGuard exists only in BeforeUpdate and AfterUpdate, and each keeps its own count.
- A limit of 1 blocks a second edit. When one transaction updates a record twice, both updates qualify, and the second one is skipped and logged.
- Skipped records are logged. Each run that skips a record logs an error. The Finalizer does not get the record.
TIP
A change gate often does the job. On a nested update, isChanged compares with the values the previous update saved, so it is false unless the field changed again.
