Changes to fflib_SObjectDomain -- separation of Domain concern from Trigger concern - request for review by community

[daveespo]

TL;DR - fflib_SObjectDomain is both a Trigger Handler and a Domain. The blurring of these two concerns into one class creates a challenge when training new engineers to the Apex Enterprise Patterns (AEP). We propose to separate the Domain from the Trigger Handling features of fflib_SObjectDomain

Through the hard work and advocacy of William Velzeboer @wimvelzeboer , we are planning to make a structural change to the longstanding SObjectDomain class in fflib-apex-common. William’s pull request separates the Domain out of SObjectDomain and into its own class and interface -- free from any trigger handling concerns.

All of the maintainers of the AEP repositories have tested this PR against our own internal production/proprietary projects and found no functional regressions. We are now giving notice that we will merge this change on April 1, 2021 unless reasonable objections to the approach or substantive functional-regression issues are raised.

To repeat: Existing code that extends fflib_SObjectDomain should continue to function, unmodified, even after merging in the new version of the AEPs.

In summary:

fflib_IDomain - a new interface that represents a collection of Object instances

fflib_IObjects - an interface extending fflib_IDomain for collection manipulation of the Domain

fflib_ISObjects - an interface extending fflib_IObjects that provides access to the SObject instances

fflib_Objects - a concrete implementation of fflib_IDomain that solely deals with Objects (not SObjects) and provides expected methods for manipulating collections of objects.

fflib_SObjects - an extension of fflib_Objects that adds additional methods for manipulating SObject collections -- such as filtering to return a subset of records, retrieving all the values of a field or updating a field in bulk.

fflib_SObjectDomain - has been modified to remove the state management for the Domain and delegate it to a fflib_SObjects instance

The pull request is here:

#300

William has also provided a working example in the sample code repo for review:

apex-enterprise-patterns/fflib-apex-common-samplecode#27

Please provide feedback either on the PR itself or, if it's a more general concern, on this discussion thread. The deadline for feedback is March 31, 2021

[girishla]

Do I understand it correct that with the proposed changes we now have to extend the fflib_SObjectDomain class twice on 2 different concrete classes - first calling it Domain and second calling it Triggerhandler ?
whilst I can see the reasons (backward compatibility etc) I think it will still be confusing for newcomers albeit in a new way.
Is the idea perhaps that this is step 1 in the move and we eventually come up with a separate/cleaner TriggerHandler interface ?

[cropredyHelix]

woo-boy - thanks for engaging the community here. I see that a 4th edition of Andy Fawcett's book will need to accompany this PR as that book is by far (IMO) the best way to learn fflib. Plus Trailhead modules will need updating.

I agree that introducing fflib domain to people steeped in trigger handlers was a burden; especially if they had not read Fawcett's book.

Of course, the temptation for "classically-trained apex devs" will be to put their business logic in the triggerhandler class and skip using the domain class altogether. I see heated arguments during the PR step in the dev cycle.

Some questions:

a) The inner class TriggerEvent in fflib_SObjectDomain - I presume stays put and is used as is?
b) What happens to logic we put into an intermediary class between our existing domain classes and fflib_SObjectDomain? See, for example pg 210 in 3rd edition of Fawcett's book - "Overriding default behavior" ?
c) fflib_Objects and fflib_SObjects are tantalizing; one pattern I use often is to pivot a list of sobjects around a field. For example,

Map<String,Contact[]> contactsByEmail = Pivot.byString(Contact.Email,ContactsSelector.newInstance.selectByXXX(...));

Is this the sort of functionality envisioned for fflib_SObjects ?

d) My existing domain classes tend to have either static constants or accessors for frequently referenced values across testmethods and logic; e.g. public static final String STAGE_QUALIFIED = 'Qualified'; This makes good sense to move out of trigger handler class to domain class.
e) The triggerhandler class function is to orchestrate methods in the domain class or possibly other service classes. Have I got that right?
f) Aidan Harding has a lot of cool stuff in his Lazy iterators repo -- are there similar items in fflib_SObjects? I have also used the Bluewolf Selector repo for filtering sobject collections. It would be nice to have all this functionality under the fflib umbrella.

[wimvelzeboer]

Hi @cropredyHelix,
Indeed we will have to work on updating existing examples here and there.
The nice thing about this change is that it is fully backwards compatible, so the old Devs can still keep going their way. But I can imagine that they do want to adopt this new structure as it will make their classes more nice and clean.

To answer your questions:
a.) Yes, the TriggerEvent will stay in fflib_SObjectDomain as that is part of the trigger handler functionality.
b.) Those overrides should still work, as fflib_SObjectDomain is extended from fflib_SObjects.
c.) Yes! The intention is to add more methods to the fflib_SObjects domain class to manipulate or extract data. I already have methods similar to the pivot one you're referring, but have not added them yet to the PR to not overcomplicate things. Lots of fun stuff similar to the Lazy iterators and the Selector repo can then be embedded in the core functionality of this rep.
e.) Yes! The trigger handler should be orchestrating at a high level what needs to be happening on TriggerOperation events. It should use Domains to create subsets of records or extract data it needs, and call Services to perform the actual logic.

[PeterLin888]

Thank you so much for your hard work here, @wimvelzeboer !
It is really helpful.
Could you please take a look at apex-enterprise-patterns/fflib-apex-common-samplecode#27? There are 3 conflicting files.
Thank you for your excellent work again!

[matthewpomar-at-reddit]

Thanks for the summary of changes. I'm new to the library and it appears current books/documentation/videos have not caught up with this change. Since the last comment on this thread was more than 1 year ago, does anyone know of any blog posts, documentation, or videos that discusses how best to use these new objects? I realize the sample application has been updated, but it would be nice to see some more examples/patterns on how to properly apply these objects in real world scenarios, including how to mock these in tests.

Thank you.

[cropredyHelix]

I think, but @wimvelzeboer would know best, but the example sample application is the best I've seen.

The books used subclasses of fflib_SObjectDomain to be both the triggerhandler and the domain. E.g. Opportunities.cls had the trigger handlers as well as any custom domain methods one chose to add.

The new structure breaks out the triggerhandler methods into a class named XXXTriggerHandler (and you'll need to reference that class type in the trigger itself - example - and is not supposed to do anything other than "handle" the onBeforeXX, onApplyDefaults, , ... entry points.

Domains are supposed to be named objectNameAsPlural - e.g. Opportunities,and do everything known in the books as domain classes except "handle" the onBeforeXX, .. etc events. Domains are created by the Application class factories, just as they always were.

One thing the change did is no longer restrict domains to SObjects; they can be any business "domain" you want as they operate on a list of Objects whereas before, domains operated on a list of SObjects.

Domains can continue to be mocked with ApexMocks (via the setMock() method).