diff --git a/docs/README.asciidoc b/docs/README.asciidoc index adce1ae..6791439 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -11,7 +11,7 @@ === Application * *Interfaces* - - fflib_IDomainFactory + - link:fflib_IDomainFactory.asciidoc[fflib_IDomainFactory] - fflib_ISelectorFactory - fflib_IServiceFactory - fflib_IUnitOfWorkFactory diff --git a/docs/fflib_IDomainFactory.asciidoc b/docs/fflib_IDomainFactory.asciidoc new file mode 100644 index 0000000..3a989f1 --- /dev/null +++ b/docs/fflib_IDomainFactory.asciidoc @@ -0,0 +1,256 @@ += fflib_IDomainFactory Class +:Author: Wilhelmus G.J. Velzeboer +:Email: wim@velzeboer.nl +:Date: 2021 +:Revision: version 1 + +Interface for creating instances of Domain classes + +== Methods + +- < recordIds)>> + +Dynamically constructs an instance of a Domain class for the given record Ids +- < recordIds, Schema.SObjectType sObjectType)>> + +Dynamically constructs an instance of a Domain class for the given record Ids +- < records)>> + +Dynamically constructs an instance of the Domain class for the given records +- < objects, Object objectType)>> + +Dynamically constructs an instance of the Domain class for the given Objects +- < records, Schema.SObjectType sObjectType)>> + +Dynamically constructs an instance of the Domain class for the given records +- <> + +- <> + +Registers a mock implementation in the Factory for the provided sObjectType +- <> + +Registers a mock in the Factory by providing a mock instance of a domain +- <> + +Registers a mock implementation in the Factory for the provided sObjectType + + +[[newInstance1]] +=== newInstance(Set recordIds) +Dynamically constructs an instance of a Domain class for the given record Ids +Internally uses the Selector Factory to query the records before passing to a +dynamically constructed instance of the application Apex Domain class + +==== _Signature_ +```java +fflib_IDomain newInstance(Set recordIds); +``` + +==== _Parameters_ + +_**recordIds**_ + +A list of Id's of the same type + +==== _Returns_ +Instance of the Domain with the records + + +___ + +[[newInstance2]] +=== newInstance(Set recordIds, Schema.SObjectType sObjectType) +Dynamically constructs an instance of a Domain class for the given record Ids +Internally uses the Selector Factory to query the records before passing to a +dynamically constructed instance of the application Apex Domain class. + +Will return a Mock implementation if one has been provided via setMock + +==== _Signature_ +```java +fflib_IDomain newInstance(Set recordIds, Schema.SObjectType sObjectType); +``` + +==== _Parameters_ + +_**recordIds**_ + +A list of Id's of the same type + +_**sObjectType**_ + +The Schema.SObjectType of the record Ids, +Providing this parameter will omit the framework from checking if the Id's are all the same +and of which SObjectType they are. + +==== _Returns_ +Instance of the Domain with the records + +___ + +[[newInstance3]] +=== newInstance(List records) +Dynamically constructs an instance of the Domain class for the given records. + +Will return a Mock implementation if one has been provided via setMock + +==== _Signature_ +```java +fflib_IDomain newInstance(List records); +``` + +==== _Parameters_ + +_**records**_ + +A concrete list of records, e.g.; `List` or `List`) + +==== _Returns_ +Instance of the Domain containing the given records + +___ +[[newInstance4]] +=== newInstance(List objects, Object objectType) +Dynamically constructs an instance of the Domain class for the given records. + +Will return a Mock implementation if one has been provided via setMock + +==== _Signature_ +```java +fflib_IDomain newInstance(List objects, Object objectType); +``` + +==== _Parameters_ + +_**objects**_ + +A concrete list of Objects, e.g.; `List` or `List`) + +_**objectType**_ + +The type of objects which are provided + +==== _Returns_ +Instance of the Domain containing the given Objects + +___ + +[[newInstance5]] +=== newInstance(List records, SObjectType domainSObjectType) +Dynamically constructs an instance of the Domain class for the given records and SObjectType. +All records in the provided list will be assumed to be of the specified sObjectType + +Will return a Mock implementation if one has been provided via setMock. + + + +==== _Signature_ +```java +fflib_IDomain newInstance(List records, Schema.SObjectType sObjectType); +``` + +==== _Parameters_ + +_**records**_ + +A list records + +_**sObjectType**_ + +SObjectType for list of records + +==== _Returns_ +Instance of the Domain containing the given records + +___ +[[setMock1]] +=== setMock(fflib_ISObjectDomain mockDomain) +Registers a mock in the Factory by providing a mock instance of a domain + +NOTE: This method is only available for backward compatibility for +domains which are implementations of fflib_ISObjectDomain + +==== _Signature_ +```java +void setMock(fflib_ISObjectDomain mockDomain); +``` + +==== _Parameters_ + +_**mockDomain**_ + +The instance of the Domain mock + +==== _Example_ +```java +fflib_ApexMocks mocks = new fflib_ApexMocks(); +IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); +mocks.startStubbing(); +mocks.when(domainMock.getType()).thenReturn(Schema.Account.SObjectType); +... +mocks.stopStubbing(); + +Application.Domain.setMock((fflib_ISObjectDomain) domainMock); +``` + +___ + +[[setMock2]] +=== setMock(Schema.SObjectType sObjectType, fflib_ISObjectDomain mockDomain) +Registers a mock implementation in the Factory for the provided sObjectType + +NOTE: This method is only available for backward compatibility for +domains which are implementations of fflib_ISObjectDomain + +==== _Signature_ +```java +void setMock(Schema.SObjectType sObjectType, fflib_ISObjectDomain mockDomain); +``` + +==== _Parameters_ + +_**sObjectType**_ + +The SObjectType of the Domain mock, avoids the need to stub the mock to return its SObjectType + +_**mockDomain**_ + +The instance of the Domain mock + +==== _Example_ +```java +fflib_ApexMocks mocks = new fflib_ApexMocks(); +IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + +Application.Domain.setMock(Schema.Account.SObjectType, domainMock); +``` + +___ +[[setMock3]] +=== setMock(fflib_IDomain mockDomain) +Registers a mock in the Factory by providing a mock instance of a domain + +==== _Signature_ +```java +void setMock(fflib_IDomain mockDomain); +``` + +==== _Parameters_ + +_**mockDomain**_ + +The instance of the Domain mock + +==== _Example_ +```java +IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); +mocks.startStubbing(); +mocks.when(domainMock.getType()).thenReturn(Schema.Account.SObjectType); +... +mocks.stopStubbing(); + +Application.Domain.setMock(domainMock); +``` + +___ +[[setMock4]] +=== setMock(Object domainType, fflib_IDomain mockDomain) +Registers a mock implementation in the Factory for the provided sObjectType + +==== _Signature_ +```java +void setMock(Object domainType, fflib_IDomain mockDomain); +``` + +==== _Parameters_ + +_**domainType**_ + +The ObjectType of the Domain mock, avoids the need to stub the mock to return its ObjectType + +_**mockDomain**_ + +The instance of the Domain mock + +==== _Example_ +```java +fflib_ApexMocks mocks = new fflib_ApexMocks(); +IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + +Application.Domain.setMock(domainMock); +``` + +___ \ No newline at end of file diff --git a/sfdx-source/apex-extensions/main/application/main/classes/interfaces/fflib_IDomainFactory.cls b/sfdx-source/apex-extensions/main/application/main/classes/interfaces/fflib_IDomainFactory.cls index 65033f0..187b19c 100644 --- a/sfdx-source/apex-extensions/main/application/main/classes/interfaces/fflib_IDomainFactory.cls +++ b/sfdx-source/apex-extensions/main/application/main/classes/interfaces/fflib_IDomainFactory.cls @@ -1,6 +1,6 @@ /** * File Name: fflib_IDomainFactory - * @description Interface for creating instances of Service classes + * @description Interface for creating instances of Domain classes * * @author architect ir. Wilhelmus G.J. Velzeboer * @@ -42,20 +42,47 @@ public interface fflib_IDomainFactory **/ fflib_IDomain newInstance(Set recordIds); + /** + * Dynamically constructs an instance of a Domain class for the given record Ids + * Internally uses the Selector Factory to query the records before passing to a + * dynamically constructed instance of the application Apex Domain class + * + * @param recordIds A list of Id's of the same type + * @param sObjectType The Schema.SObjectType of the record Ids, + * Providing this parameter will omit the framework from checking if the Id's are all the same + * and of which SObjectType they are. + * + * @exception Throws an exception via the Selector Factory if the Ids are not all of the same SObjectType + * + * @return Instance of the Domain + **/ fflib_IDomain newInstance(Set recordIds, Schema.SObjectType sObjectType); /** * Dynamically constructs an instance of the Domain class for the given records * Will return a Mock implementation if one has been provided via setMock * - * @param records A concrete list (e.g. List vs List) of records + * @param records A concrete list of records, e.g.; `List` or `List`) + * * @exception Throws an exception if the SObjectType cannot be determined from the list * or the constructor for Domain class was not registered for the SObjectType * - * @return Instance of the Domain + * @return Instance of the Domain containing the given records **/ fflib_IDomain newInstance(List records); + /** + * Dynamically constructs an instance of the Domain class for the given records + * Will return a Mock implementation if one has been provided via setMock + * + * @param objects A concrete list of Objects, e.g.; `List` or `List`) + * @param objectType + * + * @exception Throws an exception if the SObjectType cannot be determined from the list + * or the constructor for Domain class was not registered for the SObjectType + * + * @return Instance of the Domain containing the given Objects + **/ fflib_IDomain newInstance(List objects, Object objectType); /** @@ -63,37 +90,86 @@ public interface fflib_IDomainFactory * Will return a Mock implementation if one has been provided via setMock * * @param records A list records - * @param domainSObjectType SObjectType for list of records + * @param sObjectType SObjectType for list of records + * * @exception Throws an exception if the SObjectType is not specified or if constructor for Domain class was not registered for the SObjectType * * @remark Will support List but all records in the list will be assumed to be of * the type specified in sObjectType * - * @return Instance of the Domain + * @return Instance of the Domain containing the given records **/ - fflib_IDomain newInstance(List records, SObjectType domainSObjectType); + fflib_IDomain newInstance(List records, Schema.SObjectType sObjectType); /** + * Registers a mock in the Factory by providing a mock instance of a domain + * This method is only available for backward compatibility for + * domains which are implementations of fflib_ISObjectDomain + * * @param mockDomain The instance of the Domain mock + * + * @example + * + * fflib_ApexMocks mocks = new fflib_ApexMocks(); + * IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + * mocks.startStubbing(); + * mocks.when(domainMock.getType()).thenReturn(Schema.Account.SObjectType); + * ... + * mocks.stopStubbing(); + * + * Application.Domain.setMock((fflib_ISObjectDomain) domainMock); */ void setMock(fflib_ISObjectDomain mockDomain); /** + * Registers a mock implementation in the Factory for the provided sObjectType + * This method is only available for backward compatibility for + * domains which are implementations of fflib_ISObjectDomain + * * @param sObjectType The SObjectType of the Domain mock, * avoids the need to stub the mock to return its SObjectType * @param mockDomain The instance of the Domain mock + * + * @example + * + * fflib_ApexMocks mocks = new fflib_ApexMocks(); + * IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + * + * Application.Domain.setMock(Schema.Account.SObjectType, domainMock); */ void setMock(Schema.SObjectType sObjectType, fflib_ISObjectDomain mockDomain); /** + * Registers a mock in the Factory by providing a mock instance of a domain + * * @param mockDomain The instance of the Domain mock + * + * @example + * + * fflib_ApexMocks mocks = new fflib_ApexMocks(); + * IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + * mocks.startStubbing(); + * mocks.when(domainMock.getType()).thenReturn(Schema.Account.SObjectType); + * ... + * mocks.stopStubbing(); + * + * Application.Domain.setMock(domainMock); */ void setMock(fflib_IDomain mockDomain); /** + * Registers a mock implementation in the Factory for the provided sObjectType + * * @param domainType The ObjectType of the Domain mock, * avoids the need to stub the mock to return its ObjectType * @param mockDomain The instance of the Domain mock + * + * @example + * + * fflib_ApexMocks mocks = new fflib_ApexMocks(); + * IAccounts domainMock = (IAccounts) mocks.mock(IAccounts.class); + * + * Application.Domain.setMock(domainMock); */ void setMock(Object domainType, fflib_IDomain mockDomain); } \ No newline at end of file