Add documentation for new domain structure (#348)

Some issues were raised around the change to the new domain structure. This PR adds a Update message and a support page that lists the most important items, known issues and how to resolve them.

Co-authored-by: Wim Velzeboer <[email protected]>
Co-authored-by: John M. Daniel <[email protected]>

Author: 3 people

README.md

@@ -15,6 +15,7 @@ Updates
 =======
 
 - **December 2022**, **IMPORTANT CHANGE** - Support for native Apex User Mode was added to the library (see [discussion](https://github.com/apex-enterprise-patterns/fflib-apex-common/discussions/419)). For new projects, the old `enforceCRUD` and `enforceFLS` flags on `fflib_SObjectSelector` should be considered deprecated and the constructors that take `dataAccess` arguments should be used instead. Additionally, the introduction of `fflib_SObjectUnitOfWork.UserModeDML` provides an `IDML` implementation that supports `USER_MODE` or `SYSTEM_MODE`. `fflib_SObjectUnitOfWork.SimpleDML` (the default `IDML` implementation) should be considered deprecated. There are measurable performance benefits to using `SYSTEM_MODE` and `USER_MODE` (Apex CPU usage reduction). Additionally, the use of explicit `USER_MODE` and `SYSTEM_MODE` overrides the `with sharing` and `without sharing` class declaration and makes the expected behavior of DML and SOQL easier to understand.
+- **April 2021**, **IMPORTANT CHANGE**, the fflib_SObjectDomain has been split into a domain (fflib_IDomain) and triggerhandler (fflib_ISObjectDomain). This change can impact existing projects, please review [this page](docs/202105-new-domain-structure.md) for more details.
 - **April 2020**, **IMPORTANT CHANGE**, the directory format of this project repo was converted to [Salesforce DX Source Format](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm).  While the GIT commit history was maintained, it is not visible on GitHub.  If you need to see the history, either clone the repo and execute `git log --follow` from the command line or refer to this [tag](https://github.com/apex-enterprise-patterns/fflib-apex-common/tree/metadata-format-prior-to-dx-source-format-conversion) of the codebase prior to conversion.
 - **September 2014**, **IMPORTANT CHANGE**, changes applied to support Dreamforce 2014 advanced presentation, library now provides Application factories for major layers and support for ApexMocks. More details to follow! As a result [ApexMocks](https://github.com/apex-enterprise-patterns/fflib-apex-mocks) must be deployed to the org before deploying this library. The sample application [here](https://github.com/apex-enterprise-patterns/fflib-apex-common-samplecode) has also been updated to demonstrate the new features!
 - **July 2014**, **IMPORTANT CHANGE**, prior **23rd July 2014**, both the ``fflib_SObjectDomain.onValidate()`` and ``fflib_SObjectDomain.onValidate(Map<Id, SObject> existingRecords)`` methods where called during an on **after update** trigger event. From this point on the ``onValidate()`` method will only be called during on **after insert**. If you still require the orignal behaviour add the line ``Configuration.enableOldOnUpdateValidateBehaviour();`` into your constructor.

docs/202105-new-domain-structure.md

@@ -0,0 +1,57 @@
+# New domain structure
+The new domain structure allows more flexibility of the object type a domain can contain. 
+This allows for the creation of compound-domains and domains of data-classes. 
+
+It also splits the functionality into a Domain Model [as described by Martin Fowler](https://www.martinfowler.com/eaaCatalog/domainModel.html) and a separate trigger handler. 
+This helps to structure the code better and makes it more clear which Apex code should be in the domain and which in the trigger handler.
+
+
+
+## Previous interface and implementation structure
+| Interfaces | Implementation | Description |
+|:---|:---|:---|
+| fflib_ISObjectDomain | fflib_SObjectDomain | Used as Domain and trigger handler 
+
+
+## New interface and implementation structure
+| Interfaces | Implementation | Description |
+|:---|:---|:---|
+| fflib_IDomain | | Generic identifier for domains
+| fflib_IObjects | fflib_Objects | Domains constructed with Objects, e.g. data-classes 
+| fflib_ISObjects | fflib_SObjects | Domain containing SObjectTypes, e.g. Accounts, Contacts
+| fflib_ISObjectDomain | fflib_SObjectDomain | Used for trigger handlers and for legacy domains
+
+See [this PR](https://github.com/apex-enterprise-patterns/fflib-apex-common/pull/300) for a detailed overview 
+of all the code changes which were part of this change.
+
+The [fflib-apex-common-samplecode](https://github.com/apex-enterprise-patterns/fflib-apex-common-samplecode)
+also includes examples on how to structure the change into the 
+[new domain](https://github.com/apex-enterprise-patterns/fflib-apex-common-samplecode/blob/master/sfdx-source/apex-common-samplecode/main/classes/domains/Accounts.cls)
+and [trigger handler](https://github.com/apex-enterprise-patterns/fflib-apex-common-samplecode/blob/master/sfdx-source/apex-common-samplecode/main/classes/triggerHandlers/OpportunitiesTriggerHandler.cls)
+
+## Known issues and how to resolve them
+
+
+### _Issue:_ Ambiguous method signature: void setMock(MyDomainClass)
+This happens when you try to mock an old domain class which is extended from fflib_SObjectDomain. 
+```apex
+Application.Domain.setMock(mockAssetsDomain);   // <<== generates Ambiguous method signature: void setMock
+```
+The issue can be resolved by casting the mock implementation to fflib_ISObjectDomain:
+> Application.Domain.setMock( **(fflib_ISObjectDomain)** mockAssetsDomain);  
+
+[See this issue report for more information](https://github.com/apex-enterprise-patterns/fflib-apex-common/issues/347)
+
+
+### _Issue:_ Illegal assignment from fflib_Domain to fflib_ISObjectDomain
+The `newInstance` method signature of the Application Domain Factory (fflib_Application.DomainFactory) has changed into:
+>public **fflib_IDomain** newInstance(***);
+
+If you have:
+```apex
+fflib_ISObjectDomain domain =  Application.Domain.newInstance(sObjIds);	
+```
+You need to change that into:
+> fflib_ISObjectDomain domain = **(fflib_ISObjectDomain)** Application.Domain.newInstance(sObjIds);	
+
+[See this issue report for more information](https://github.com/apex-enterprise-patterns/fflib-apex-common/issues/346)