diff --git a/.gitignore b/.gitignore index bd20187..790a84f 100644 --- a/.gitignore +++ b/.gitignore @@ -37,9 +37,18 @@ $RECYCLE.BIN/ # Local environment variables .env +# Ignore VSCode config files +.vscode/ + # Ignore Intellij config files .idea/ *.iml *.iws IlluminatedCloud/ -.project.license \ No newline at end of file +.project.license +temp/ + +# Ignore other fflib packages +sfdx-source/apex-mocks +sfdx-source/apex-common +sfdx-source/apex-extensions-examples diff --git a/README.md b/README.md index de0f03e..94f83b0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,14 @@ # fflib-apex-extensions -Extension for the fflib-apex-common Library. Introducing many advanced features on top of the Apex Enterprise Patterns +Extensions for the fflib-apex-common Library. Introducing many advanced features on top of the Apex Enterprise Patterns + +**Dependencies:**
+This extension package is dependent on the following packages: +- [fflib-apex-mocks](https://github.com/apex-enterprise-patterns/fflib-apex-mocks) +- [fflib-apex-common](https://github.com/apex-enterprise-patterns/fflib-apex-common) + +## Contents +This extension pack includes the following features + +- [Primitive domains](./docs/primitive-domains.md) +- [A common criteria based filter](./docs/criteria-based-filter.md) for Domains and Selector + diff --git a/docs/criteria-based-filter.md b/docs/criteria-based-filter.md new file mode 100644 index 0000000..cad7adf --- /dev/null +++ b/docs/criteria-based-filter.md @@ -0,0 +1,107 @@ +# fflib-apex-extensions + +## Criteria based filter for Domains and Selectors + +A common criteria based filter for domains and SOQL condition generator for Selectors. + + +It is very often that we have the same filters in domain and elector classes. The Criteria feature provides a solution that extracts the filter conditions into a single reusable criteria class. These filter conditions are dynamic and can be evaluated in run-time, or be converted to a SOQL statement condition. +``` + + - - - - - - - - + + + - - - | Filter Criteria | - - - + + | + - - - - - - - - + | + | | + | | ++ - - - - - - - + + - - - - - - - + +| Domain | | Selector | ++ - - - - - - - + + - - - - - - - + +``` +Here is an example on how its used: + +The criteria class is the place where all the filter conditions are stored for a single SObjectType. + +```apex +public with sharing class AccountCriteria extends fflib_Criteria +{ + public AccountCriteria ShippingCountryEquals(String countryName) + { + equalTo(Schema.Account.ShippingCountry, countryName); + return this; + } + + public AccountCriteria NumberOfEmployeesGreaterThan(Integer numberOfEmployees) + { + greaterThan(Schema.Account.NumberOfEmployees, numberOfEmployees); + return this; + } +} +``` + +How it can be applied in a Domain class: + +```apex +public with sharing class Accounts + extends SObjects + implements IAccounts +{ + private static final Integer LARGE_ACCOUNT_EMPLOYEE_NUMBERS = 500; + + public Accounts getByCountry(String countryName) + { + return new Accounts( + getRecords( + new AccountCriteria().ShippingCountryEquals(countryName) + ) + ); + } + + public Accounts getByNumberOfEmployeesGreaterThan(Integer numberOfEmployees) + { + return new Accounts( + getRecords( + new AccountCriteria().NumberOfEmployeesGreaterThan(numberOfEmployees) + ) + ); + } + + public Accounts getByLargeAccountsInCountry(String countryName) + { + return new Accounts( + getRecords( + new AccountCriteria() + .ShippingCountryEquals(countryName) + .NumberOfEmployeesGreaterThan(numberOfEmployees) + ) + ); + } +} +``` +In this example we see three filters; one for country, another for checking minimal number of employees and a third that combines the first two. +It is important not to have a filter with too many conditions. +One filter criteria condition per method is ideal to have maximum flexibility and a high chance on code-reuse. + + +How the same filters can be used in the Selector class: + +```apex +public with sharing class AccountsSelector + extends fflib_SObjectSelector + implements IAccountsSelector +{ + ... + public List selectByCountryWithMinimalNumberOfEmployees(String country, Integer minimalNumberOfEmployees) + { + return (List) Database.query( + newQueryFactory() + .setCondition( + new AccountCriteria() + .ShippingCountryEquals(country) + .NumberOfEmployeesGreaterThan(minimalNumberOfEmployees) + ); + } + ... +} +``` + +With this feature developers can avoid a lot of code duplications. +Hope you like it! diff --git a/docs/primitive-domains.md b/docs/primitive-domains.md new file mode 100644 index 0000000..55a2321 --- /dev/null +++ b/docs/primitive-domains.md @@ -0,0 +1,22 @@ +# fflib-apex-extensions + +## Primitive Domains + +A huge benefit of using primitive domains, is that you write less code. +Instead of: +```apex +List myStrings = getSomeStrings(); +``` +You can write: +```apex +Strings myStrings = getSomeString(); +``` + +It is a small thing, but it makes things looks much nicer. + + +One other benefit is that you can encapsulate more logic as Lists. You can see these lists as a Domain. +Take a look at the SObjects primitive domain, it is the new source for extending domain classes. + + + diff --git a/sfdx-project.json b/sfdx-project.json index f635075..b2b5c6f 100644 --- a/sfdx-project.json +++ b/sfdx-project.json @@ -1,7 +1,7 @@ { "packageDirectories": [ { - "path": "sfdx-source/force-app", + "path": "sfdx-source/apex-extensions", "default": true } ], diff --git a/sfdx-source/apex-extensions/main/default/classes/criteria/fflib_Comparator.cls b/sfdx-source/apex-extensions/main/default/classes/criteria/fflib_Comparator.cls new file mode 100644 index 0000000..0f0979a --- /dev/null +++ b/sfdx-source/apex-extensions/main/default/classes/criteria/fflib_Comparator.cls @@ -0,0 +1,178 @@ +/** + * File Name: fflib_Comparator + * Description: Comparator for primitive values + * + * @author : architect ir. Wilhelmus G.J. Velzeboer + * + * Copyright (c), W.G.J. Velzeboer, + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above author notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither the name of the author nor the names of its contributors + * may be used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +public with sharing class fflib_Comparator +{ + + public static Boolean compareTo(Object object1, fflib_Operator operator, Object object2) + { + Integer result = compare(object1, object2); + + if (operator == fflib_Operator.EQUALS && result == 0) + return true; + else if (operator == fflib_Operator.NOT_EQUALS && result != 0) + return true; + else if (operator == fflib_Operator.LESS_THAN && result == -1) + return true; + else if (operator == fflib_Operator.LESS_THAN_OR_EQUAL_TO && result != 1) + return true; + else if (operator == fflib_Operator.GREATER_THAN && result == 1) + return true; + else if (operator == fflib_Operator.GREATER_THAN_OR_EQUAL_TO && result != -1) + return true; + else + return false; + } + + public static Integer compare(Object object1, Object object2) + { + if (object1 == null && object2 == null) + return 0; + else if (object1 == null) + return -1; + else if (object2 == null) + return 1; + else if (object1 instanceof Boolean && object2 instanceof Boolean) + return compare((Boolean) object1, (Boolean) object2); + else if (object1 instanceof Date && object2 instanceof Date) + return compare((Date) object1, (Date) object2); + else if (object1 instanceof Datetime && object2 instanceof Datetime) + return compare((Datetime) object1, (Datetime) object2); + else if (object1 instanceof Integer && object2 instanceof Integer) + return compare((Integer) object1, (Integer) object2); + else if (object1 instanceof Long && object2 instanceof Long) + return compare((Long) object1, (Long) object2); + else if (object1 instanceof Double && object2 instanceof Double) + return compare((Double) object1, (Double) object2); + else if (object1 instanceof Time && object2 instanceof Time) + return compare((Time) object1, (Time) object2); + else if (object1 instanceof String && object2 instanceof String) + return compare((String) object1, (String) object2); + else + throw new IllegalArgumentException( + 'Both arguments must be type Boolean, Date, Datetime, Decimal, Double, ID, Integer, Long, Time, or String'); + } + + public static Integer compare(Boolean b1, Boolean b2) + { + if (!b1 && b2) return -1; + else if (b1 == b2) return 0; + else return 1; + } + + public static Integer compare(Date d1, Date d2) + { + if (d1 < d2) return -1; + else if (d1 == d2) return 0; + else return 1; + } + + public static Integer compare(Datetime d1, Datetime d2) + { + if (d1 < d2) return -1; + else if (d1 == d2) return 0; + else return 1; + } + + public static Integer compare(Double d1, Double d2) + { + if (d1 < d2) return -1; + else if (d1 == d2) return 0; + else return 1; + } + + public static Integer compare(Integer i1, Integer i2) + { + if (i1 < i2) return -1; + else if (i1 == i2) return 0; + else return 1; + } + + public static Integer compare(Long l1, Long l2) + { + if (l1 < l2) return -1; + else if (l1 == l2) return 0; + else return 1; + } + + public static Integer compare(String s1, String s2) + { + if (s1 < s2) return -1; + else if (s1 == s2) return 0; + else return 1; + } + + public static Integer compare(Time t1, Time t2) + { + return compare('' + t1, '' + t2); + } + + + /** + * @description check if a Set contains a value + * @author architect ir. Wim G.J. Velzeboer + * @param object1 - Object - a Set of objects + * @param object2 - Object - the object to check if its a member of the Set + * @return Boolean - TRUE if the object is a member of the Set + */ + public static Boolean contains(Object object1, Object object2) + { + if (object1 == null && object2 == null) + return true; + else if (object1 == null) + return false; + else if (object2 == null) + return false; + else if (object1 instanceof set && object2 instanceof Date) + return ((set) object1).contains((date) object2); + else if (object1 instanceof set && object2 instanceof Datetime) + return ((set) object1).contains((Datetime) object2); + else if (object1 instanceof set && object2 instanceof Double) + return ((set) object1).contains((Double) object2); + else if (object1 instanceof set && object2 instanceof Id) + return ((set) object1).contains((Id) object2); + else if (object1 instanceof set && object2 instanceof Integer) + return ((set) object1).contains((Integer) object2); + else if (object1 instanceof set && object2 instanceof Long) + return ((set) object1).contains((Long) object2); + else if (object1 instanceof set) + return ((set) object1).contains((Object) object2); + else if (object1 instanceof set