Salesforce Apex Master Class (Ep. 3) – What is the Apex Programming Langage?

The Salesforce Definition of What the Apex Language is

Let’s go over what Apex actually is, and when you, as a developer or administrator, should use it when creating custom functionality in your Salesforce orgs.

Apex is a proprietary development language created specifically for Salesforce’s own platform. Apex looks and feels similar to Java (not Javascript) or C#. The Apex language allows you to build custom functionality that Salesforce’s point-and-click tools can’t support or do on their own. This means that with Apex, you can expand Salesforce’s functionality and build absolutely anything that you or your users can dream up for your Salesforce instance. The sky is the limit with the power of Apex! Go ahead and give it a try, and see what you can do with it.

A Simpler Explanation of What the Apex Language Is

Apex is a strongly typed object-oriented programming language, but what does that really mean? Let’s look at an example.

public class OpportunityCalculator {
    
    Integer numberValue = 1;
    String oppName = 'Cool Opp';
    
    
    public Integer addOpportunityValues(Integer oppValueOne, Integer oppValueTwo){
        Integer oppValuesCombined = oppValueOne + oppValueTwo;
        return oppValuesCombined;
    }
    
    public Integer substractOpportunityValues(Integer oppValueOne, Integer oppValueTwo){
        Integer oppValuesCombined = oppValueOne - oppValueTwo;
        return oppValuesCombined;
    }

This example is a representation of a calculator for opportunities in our org. Like a real, physical calculator, this code calculator could potentially have the ability to add, subtract, multiply, and divide value. My opportunity calculator class above uses methods to add and subtract values, all while creating a representation of an object and the many ways in which that object can interface with its users (such as pressing a calculator’s buttons to do some math). There’s much more I could say about object-oriented programming, but that can should probably wait for a future blog post. It’s too much to unpack here, but eventually, we’ll check it out together!

There are four key things you need to know about object-oriented programming: encapsulation, abstraction, inheritance, and polymorphism. If you’d like to know more about those four in greater detail, check out my video over OOP in Apex here!


What is a Strongly Typed OOP Language?

public class OpportunityCalculator {

Integer numberValue = 1;
String oppName = 'Cool Opp';


public Integer addOpportunityValues(Integer oppValueOne, Integer oppValueTwo){
Integer oppValuesCombined = oppValueOne + oppValueTwo;
return oppValuesCombined;
}

public Integer substractOpportunityValues(Integer oppValueOne, Integer oppValueTwo){
Integer oppValuesCombined = oppValueOne - oppValueTwo;
return oppValuesCombined;
}



At a very high-level, object-oriented programming (OOP) is the representation of an object and its functionality in code. Now, what is a strongly typed language? First, consider variables, or a way to represent a value. When I create a variable called numberValue and I set it equal to 1, I’m declaring that variable as an integer, or a way to declare a number in Apex (among many other development languages). I’m declaring it as type Integer, but note that if I just declared that 1 as a number value without “Integer,” Apex wouldn’t accept it, nor would Apex allow me to save it like that. In short, Apex needs me to specify the type of value I’m trying to store: Integer. I must also specify what kind of value I want to return from those methods if I want to return something.

So, when I declare my method, I’m saying that when my method is done executing, it will return an integer. In programming languages that aren’t strongly typed, you don’t have to declare variables as a specific type (like Integer). Javascript is an example, where you can simply say that the variable you’re declaring equals 1 or Cool or whatever you can think up, and you don’t define a type for those variable.

In short, strongly typed OOP language means you’ve got to tell the code what it’s supposed to return and what your variable types are.


When Should You Actually Choose to Use Apex?

When exactly should you use the Apex development language? It’s a bit subjective, but also not. Often, you’ll find that out-of-the-box, point-and-click Salesforce stuff doesn’t work well with what your users actually need so they can do their job, and that’s when you use Apex. As a Salesforce user or admin, you must know all the administrative capabilities and know how to create new objects with their own fields, among other things. This is so you know when it’s proper to use administrative tools, or when you should use custom development instead.

Usually, you’ll need to use Apex development in one of two different scenarios. The first is, as mentioned earlier, when your out-of-the-box, point-and-click tools aren’t enough to build what you’re trying to make for your users. The second is when your org scales up to a huge size with lots of users (such as the 500-user mark), where your point-and-click tools can’t handle the sheer volume of daily transactions your users are making. When you reach that point, it’s time for Apex code to take over and work its magic!


Get Coding With The Force Merch!!

We now have a tee spring store setup so you can buy cool Coding With The Force merchandise! Please check it out! Every purchase goes to supporting the blog and YouTube channel.

Get Coding With The Force Merch Here!


Check Out More Coding With The Force Stuff!

If you liked this post make sure to follow us on all our social media outlets to stay as up to date as possible with everything!

Youtube
Patreon
Github
Facebook
Twitter
Instagram


Salesforce Development Books I Recommend

Advanced Apex Programming
Salesforce Lightning Platform Enterprise Architecture
Mastering Salesforce DevOps
Apex Design Patterns Book

Good Non-SF Specific Development Books:

Clean Code
Clean Architecture
Design Patterns: Elements of Reusable Object-Oriented Software Book

Salesforce Development Tutorial (LWC): How to use Lightning Web Component’s in List View Buttons

Why Bother Using an LWC in a List View Button?

If you need to create some custom functionality that is accessible to your users via a list view (or potentially a related list), then a list view button is the way to go. The reason that you should prefer to utilize an LWC (despite the fact there is no obvious way to use an LWC for a list view button) is because LWC’s load faster than any other component type and, of the available list view button options, they are the most consistent with Salesforce’s Lightning Experience look and feel.

Unfortunately, while it’s super simple to setup and LWC for a list view button, Salesforce has no documentation on how to do so and virtually no answers exist for how to do this anywhere online, but NO MORE!! Today I’ll show you three different methods of creating an LWC List View button! Two methods do not allow you to send the ids of selected records in a list view and one does. I’ll give you the pros and cons of each and how to setup each one below.

One additional note, all of the below solutions will allow the user to traverse from the list view button back to the exact list view they were previously on without the help of visualforce at all! Something else that was undocumented and challenging to figure out.

DISCLAIMER: As of this writing, LWC quick actions are not usable on list views, this could change in the future however, so make sure to investigate that.


Setting up the Lightning Web Component

In any of the three scenarios we are going to use the same Lightning Web Component to demo the functionality, although in the third scenario (a flow based scenario) we will be making slight modifications to allow for the ids of records to get passed through to the component. Let’s take a look at the core of the component below (or on GitHub here).

HTML File:

<template>
	<lightning-button label="Return to List View" onclick={close}></lightning-button>
</template>

JS File:

import {LightningElement} from 'lwc';

export default class ListViewButton extends LightningElement {

	close(){
		setTimeout(
			function() {
				window.history.back();
			},
			1000
		);
	}
}

XML File:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>51.0</apiVersion>
    <description>List View Button</description>
    <isExposed>true</isExposed>
    <masterLabel>List View Button</masterLabel>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__Tab</target>
        <target>lightning__FlowScreen</target>
    </targets>
</LightningComponentBundle>

Alright alright alright, so we have all of the files outlined above, let’s make talk about the close function in the JavaScript file first. I did an ENORMOUS amount of experimentation trying to get a list view button that spawns an LWC to allow me to traverse back to the exact list view that I had previously come from and this was the only way I could consistently get that to happen. I tried navigationmixin and it had trouble remembering where to go no matter what I did, I tried return urls, I tried a ton of junk, but that close function above does the trick every single time (at least in a browser, never tried on a mobile app). It always goes back to the exact list view I was on when I clicked the button.

So what does that function actually do? It basically looks to your browser windows history and moves back one page in time, the set timeout function allows it to take up to one second to make that happen. I would suggest using the set timeout as I had issues using this function without it, occasionally it wouldn’t have enough time to operate and failed. This however is used by thousands of users in my org now with no complaints.

The second thing I wanna go over is the XML File’s targets. For simplicity I just put every target we are going to need when we go through each of the three LWC list view button methods, that being said, you only need to declare the target for the method you choose to use. If you use the App Builder method, use the AppPage target, if you use the Tab method, use the Tab target, etc.


LWC List View Button Method 1: The Lightning App Builder Page Method

WHETHER YOU USE THIS METHOD OR NOT, READ THROUGH IT!! THE VAST MAJORITY OF THE STEPS ARE IDENTICAL FOR ALL OTHER VERSIONS SO THEY WILL ONLY BE SHOWN HERE AND REFERENCED IN THE OTHER SECTIONS!! Admittedly, this is my least favorite method, however it does work and some people may prefer it, so I’m gonna show you how to do it real quick. To use this method we need to create a lightning app builder app page. If you don’t know what that is, check out this trailhead. Once you’ve created the app builder page, you need to drag and drop the LWC (shown in the section above) onto the page. You can find the LWC in the section show below:

After you’ve placed your LWC on the page, save and activate your App Builder page. Then click anywhere in your lightning app page canvas that isn’t specifically your LWC to bring up the page information on the right side of the screen. Grab the “Developer Name” value, you need it for the next step.

Now that an app builder page houses our component, and we have the dev name for the app page, we need to setup a list view button to pop open our page for us. Kewlio Julio, let’s get to it.

Go to the object manager and find the object you are creating a list view button for. On the object page, click the “buttons links and actions” link, then click the “New Button or Link” on the top right of that page.

On the new button or link page, you are gonna fill out the follow:
1) Fill out a Label (this can be whatever you want)
2) Select the “List Button” display type
3) Select the “Display in existing window without sidebar or header” Behavior.
4) Select the “URL” Content Source
5) In the free text area put the following URL: /lightning/n/App_Page_Developer_Name
6) Save your button

To place your new LWC list view button on your objects list view, click on the “Search Layouts for Salesforce Classic” tab on your object and then click the drop down arrow next to the “List View” layout and select the “Edit” value in the drop down.

On the edit page for the list view layout, scroll down to the “Custom Buttons” section and select your new list view button.

Now, if you traverse to your object in the app launcher, you should be able to see your button on any list view and click it. This should result in your LWC popping up for you as shown below!

The Pros and Cons of this approach are the following:
Pros:
1) It’s the second fastest of the three options to load
Cons:
1) You cannot get rid of the app builder title area without janky css hacks
2) The tab method (outlined below) loads considerably faster.
3) This can load in an iframe depending on your settings.
4) Can’t pass in list view selection ids


LWC List View Button Method 2: The Lightning Component Tab Method

This is my absolute favorite method, it loads ultra fast and is the easiest to setup. If you don’t need list view ids passed into your LWC, this is the way to go in my opinion.

This method works much like the first method, the setup is virtually identical aside from the fact that you setup a Lightning Component Tab to use as opposed to a Lightning App Builder App Page. Even the List View button setup is the same, the only difference is that you use the lightning tabs developer name at the end of the URL. So to save my hands some typing I’m only gonna show you the tab setup, please refer to the rest of the steps in the App Builder setup instruction above.

To setup a tab to use instead of an app builder page is simple. In setup go to Tabs. Then on the Tabs screen, scroll down to the “Lightning Component Tabs” and select the “New” button.

On the new lightning component tab screen select your lightning component (the one shown above or the one you’ve built), enter a tab label, a tab name and select a tab style and you’re done. MAKE SURE YOUR LWC HAS A TARGET IN THE XML FOR TABS (this is shown in the code up above), otherwise it won’t be selectable.

Once you’ve created your tab, just follow the exact steps outlined in the app builder app page scenario to for the lightning button setup and you’re done!

Pros and Cons of this approach:
Pros:
1) Fastest load time
2) Easiest setup
3) Never loads in an iFrame
Cons:
1) Cannot load in list view ids from selected list view values


LWC List View Button Method 3: The Flow Screen Method

I will urge you to please not use this method unless you absolutely need the selected list view ids passed into your LWC. I say this because the load times are significantly slower and now you have to involve two technologies (flow and lwc) instead of one, making it more complex to deal with, albeit not by a ton.

The steps for setting up the actual list view button for this method are virtually identical to others as well, aside from the URL structure for the list view button, which we will cover, but refer to the first method for setting up the majority of the actual button.

Alrightyyyyy then, here we go. This final method utilizes a flow to allow us to capture the incoming selected list view ids and send them to our LWC to manipulate.

The first thing we need to do is update our LWC a bit to allow it to receive these incoming list view ids, so let’s do thattttttt. I’ll post the code below and then discuss it.

HTML:

<template>
	<p>These are the list view ids passed: {listViewIds}</p>
	<lightning-button label="Return to List View" onclick={close}></lightning-button>
</template>

JS:

import {LightningElement, api} from 'lwc';

export default class ListViewButton extends LightningElement {
	@api listViewIds;

	close(){
		setTimeout(
			function() {
				window.history.back();
			},
			1000
		);
	}
}

XML:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>51.0</apiVersion>
    <description>List View Button</description>
    <isExposed>true</isExposed>
    <masterLabel>List View Button</masterLabel>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__Tab</target>
        <target>lightning__FlowScreen</target>
        <target>lightning__RecordAction</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__FlowScreen">
            <property name="listViewIds" type="String[]"></property>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

First let’s talk about the JavaScript file. We added two things to that file, the first is that we are now importing api at the top so that we can use the api decorator. The second is that we have created the listViewIds variable with the @api decorator on it. This allows the variable to be written to by the flow.

Next let’s talk about the metadata file, in the metadata file we have added a targetConfig. This target config allows us in the flow builder to declaratively assign the incoming list view ids to the LWC’s listViewIds variable.

Last, in the HTML file we have just created a paragraph tag to view the list view ids when they are brought over.

Now that we’ve updated the component, we need to create the flow. In setup, go to Flows and then select “New Flow” at the top to create a new flow.

You will immediately be presented with options for the type of flow you’d like to create, select “Screen Flow” and press the “Next” button., then select the “Freeform” option. You will then land on the flow builder canvas.

The first thing we need to do is create a variable. In the “Toolbox” area on the left side of the screen click the “Manager” tab and then click the “New Resource” button.

After clicking the “New Resource” button a modal will pop-up. Do the following:
1) For Resource Type select “Variable”
2) Fill out the API Name field with the value “ids” (do not include the surrounding quotes). IT MUST BE THIS VALUE TO WORK!
3) For “Data Type” select “Text”
4) Check the, “Allow Multiple Values (Collection)” checkbox
5) Check the, “Available for input” checkbox
6) Click the “Done” button


After setting up this variable you’ll need to grab a screen flow from the “Elements” tab in the toolbox and drag it onto the flow canvas.

On the Screen element modal that pops up you’ll want to do the following:
1) Enter a label and API Name
2) Uncheck the “Show Header” checkbox
3) Uncheck the “Show Footer” checkbox
4) On the left side of the modal in the “Components” area select your LWC and drop it on the page
5) Fill out the API Name for your component
6) place the “ids” variable we created above in the “listViewIds” box for the LWC
7) Click the “Done” button

Then connect your start node to your new screen node, grab the API name of your flow from the settings area of the flow canvas, activate your flow and you’re done!

The one and ONLY step that changes for the list view button setup for the flow variety is the url structure. The URL structure should be changed to the following: /flow/Flow_Developer_Name

Aside from the above, all of the other steps are the same, so please reference the first LWC Button setup method above for more info.

Pros and Cons of this method:
Pros:
1) This is the only method that can receive the ids of values selected in a list view

Cons:
1) This is by far the slowest loading method
2) It forces you to use a flow to embed your LWC
3) It’s the most complex setup
4) It hosts itself in an iFrame

Alright, that’s all folks, this blog post was long and my hands are tired. Hasta Luego!!!!!


Get Coding With The Force Merch!!

We now have a redbubble store setup so you can buy cool Coding With The Force merchandise! Please check it out! Every purchase goes to supporting the blog and YouTube channel.

Get Shirts Here!
Get Cups, Artwork, Coffee Cups, Bags, Masks and more here!


Check Out More Coding With The Force Stuff!

If you liked this post make sure to follow us on all our social media outlets to stay as up to date as possible with everything!

Youtube
Patreon
Github
Facebook
Twitter
Instagram


Salesforce Development Books I Recommend

Advanced Apex Programming
Salesforce Lightning Platform Enterprise Architecture
Mastering Salesforce DevOps

Good Non-SF Specific Development Books:

Clean Code
Clean Architecture

SoC and the Apex Common Library Tutorial Series Part 8: Implementing the Service Layer with the Apex Common Library

Preparation for the rest of this article

There is NO FRAMEWORK that can be made for service layer classes. This is a business logic layer and it will differ everywhere. No two businesses are identical. That being said, if you would like to leverage all of the other benefits of the Apex Common Library (primarily Apex Mocks) and you would like your service classes to be able to leverage the fflib_Application class to allow for dynamic runtime logic generation, you’ll need to structure your classes as outlined below. If you don’t want to leverage these things, then don’t worry about doing what is listed below… but trust me, in the long run it will likely be worth it as your org grows in size.


The Service Interface

For every service layer class you create you will create an interface (or potentially a virtual class you can extend) that your service layer implementation class will implement (more on that below). This interface will have every method in your class represented in it. An example of a service interface is below. Some people like to prefix their interfaces with the letter I (example: ICaseService), however I prefer to postfix it with _I or _Interface as it’s a bit clearer in my opinion.

This methods in this interface should represent all of the public methods you plan to create for this service class. Private methods should not be represented here.

public interface Task_Service_Interface
{
	void createTasks(Set<Id> recordIds, Schema.SObjectType objectType);
}

The Service Layer Class

This class is where things get a little confusing in my opinion, but here’s the gist of it. This is the class you will actually call in your apex controllers (or occasionally domain classes) to actually execute the code… however there are no real implementation details in it (that exists in the implementation class outlined below). The reason this class sits in as a kind of middle man is because we want, no matter what business logic is actually called at run time, for our controller classes, batch classes, domain classes, etc to not need to alter the class they call to get the work done. In the Service Factory section below we’ll see how that becomes a huge factor. Below is an example of the Service Layer class setup.

//This class is what every calling class will actually call to. For more information on the //Application class check out the fflib_Application class
//part of this wiki.
public with sharing class Task_Service
{
	//This literally just calls the Task_Service_Impl class's createTasks method
	global static void createTasks(Set<Id> recordIds, Schema.SObjectType objectType){
		service().createTasks(recordIds, objectType);
	}

	//This gets an instance of the Task_Service_Impl class from our Application class. 
        //This method exists for ease of use in the other methods 
        //in this class
	private static Task_Service_Interface service(){
            return (Task_Service_Interface) 
                   Application.service.newInstance(Task_Service_Interface.class);
	}
}

The Service Implementation Class

This is the concrete business logic implementation. This is effectively the code that isn’t super abstract, but is the more custom built business logic specific to the specific business (or business unit) that needs it to be executed. Basically, this is where your actual business logic should reside. Now, again, you may be asking, but Matt… why not just create a new instance of this class and just use it? Why create some silly interface and some middle man class to call this class. This isn’t gonna be superrrrrrr simple to wrap your head around, but bear with me. In the next section we tie all these classes together and paint the bigger picture. An example of a Service Implementation class is below.

/**
 * @description This is the true implementation of your business logic for your service layer. 
    These impl classes
 * are where all the magic happens. In this case this is a service class that executes the 
   business logic for Abstract
 * Task creation on any theoretical object.
 */

public with sharing class Task_Service_Impl implements Task_Service_Interface
{
	//This method creates tasks and MUST BE IMPLEMENTED since we are implementing the 
        //Task_Service_Interface
	public void createTasks(Set<Id> recordIds, Schema.SObjectType objectType)
	{
		//Getting a new instance of a domain class based purely on the ids of our 
                //records, if these were case
		//ids it would return a Case object domain class, if they were contacts it 
                //would return a contact
		//object domain class
		fflib_ISObjectDomain objectDomain = Application.domain.newInstance(recordIds);

		//Getting a new instance of our selector class based purely on the object type 
                //passed. If we passed in a case
		//object type we would get a case selector, a contact object type a contact 
                //selector, etc.
		fflib_ISObjectSelector objectSelector = 
                Application.selector.newInstance(objectType);

		//We're creating a new unit of work instance from our Application class.
		fflib_ISObjectUnitOfWork unitOfWork = Application.UOW.newInstance();

		//List to hold our records that need tasks created for them
		List<SObject> objectsThatNeedTasks = new List<SObject>();

		//If our selector class is an instance of Task_Selector_Interface (if it 
                //implement the Task_Selector_Interface
		//interface) call the selectRecordsForTasks() method in the class. Otherwise 
                //just call the selectSObjectsById method
		if(objectSelector instanceof  Task_Selector_Interface){
			Task_Selector_Interface taskFieldSelector = 
                        (Task_Selector_Interface)objectSelector;
			objectsThatNeedTasks = taskFieldSelector.selectRecordsForTasks();
		}
		else{
			objectsThatNeedTasks = objectSelector.selectSObjectsById(recordIds);
		}

		//If our domain class is an instance of the Task_Creator_Interface (or 
                //implements the Task_Creator_Interface class)
		//call the createTasks method
		if(objectDomain instanceof Task_Creator_Interface){
			Task_Creator_Interface taskCreator = 
                        (Task_Creator_Interface)objectDomain;
			taskCreator.createTasks(objectsThatNeedTasks, unitOfWork);
		}

		//Try commiting the records we've created and/or updated in our unit of work 
                //(we're basically doing all our DML at
		//once here), else throw an exception.
		try{
			unitOfWork.commitWork();
		}
		catch(Exception e){
			throw e;
		}
	}
}

The fflib_Application.ServiceFactory class

The fflib_Application.ServiceFactory class… what is it and how does it fit in here. Well, if you read through all of Part 4: The fflib_Application Class then you hopefully have some solid background on what it’s used for and why, but it’s a little trickier to conceptualize for the service class so let’s go over it a bit again. Basically it leverages The Factory Pattern to dynamically generate the correct code implementations at run time (when your code is actually running).

This is awesome for tons of stuff, but it’s especially awesome for the service layer. Why? You’ll notice as your Salesforce instance grows so do the amount of interested parties. All of the sudden you’ve gone from one or two business units to 25 different business units and what happens when those businesses need the same type of functionality with differing logic? You could make tons of if else statements determining what the user type is and then calling different methods based on that users type… but maybe there’s an easier way. If you are an ISV (a managed package provider) what I’m about to show you is likely 1000 times more important for you. If your product grows and people start adopting it, you absolutely need a way to allow flexibility in your applications business logic, maybe even allow them to write their own logic and have a way for your code to execute it??

Let’s check out how allllllllllll these pieces come together below.


Tying all the classes together

Alright, let’s tie everything together piece by piece. Pretend we’ve got a custom metadata type that maps our service interfaces to a service class implementation and a custom user permission (or if you don’t wanna pretend you can check it out here). Let’s first start by creating our new class that extends the fflibApplication.ServiceFactory class and overrides its newInstance method.

/*
   @description: This class is an override for the prebuilt fflib_Application.ServiceFactory 
   that allows
   us to dynamically call service classes based on the running users custom permissions.
 */

public with sharing class ServiceFactory extends fflib_Application.ServiceFactory
{
	Map<String, Service_By_User_Type__mdt> servicesByUserPermAndInterface = new 
        Map<String, Service_By_User_Type__mdt>();

	public ServiceFactory(Map<Type, Type> serviceInterfaceByServiceImpl){
		super(serviceInterfaceByServiceImpl);
		this.servicesByUserPermAndInterface = getServicesByUserPermAndInterface();
	}

	//Overriding the fflib_Application.ServiceFactory newInstance method to allow us to 
        //initialize a new service implementation type based on the 
        //running users custom permissions and the interface name passed in.
	public override Object newInstance(Type serviceInterfaceType){
		for(Service_By_User_Type__mdt serviceByUser: 
                servicesByUserPermAndInterface.values()){
			 
                if(servicesByUserPermAndInterface.containsKey(serviceByUser.User_Permission__c 
                  + serviceInterfaceType)){
			 Service_By_User_Type__mdt overrideClass = 
                         servicesByUserPermAndInterface.get(serviceByUser.User_Permission__c + 
                         serviceInterfaceType.getName());
		         return 
                    Type.forName(overrideClass.Service_Implementation_Class__c).newInstance();
			}
		}
		return super.newInstance(serviceInterfaceType);
	}

	//Creating our map of overrides by our user custom permissions
	private Map<String, Service_By_User_Type__mdt> getServicesByUserPermAndInterface(){
		Map<String, Service_By_User_Type__mdt> servicesByUserType = 
                new Map<String, Service_By_User_Type__mdt>();
		for(Service_By_User_Type__mdt serviceByUser: 
                Service_By_User_Type__mdt.getAll().values()){
			//Checking to see if running user has any of the permissions for our 
                        //overrides, if so we put the overrides in a map
			 
         if(FeatureManagement.checkPermission(serviceByUser.User_Permission__c)){
			servicesByUserType.put(serviceByUser.User_Permission__c + 
                        serviceByUser.Service_Interface__c, serviceByUser);
			}
		}
		return servicesByUserType;
	}
}

Cool kewl cool, now that we have our custom ServiceFactory built to manage our overrides based on the running users custom permissions, we can leverage it in the Application Factory class we’ve hopefully built by now like so:

public with sharing class Application
{
       //Domain, Selector and UOW factories have been omitted for brevity, but should be added 
       //to this class

	//This allows us to create a factory for instantiating service classes. You send it 
        //the interface for your service class
	//and it will return the correct service layer class  
        //Exmaple initialization: Object objectService = 
        //Application.service.newInstance(Task_Service_Interface.class);
	public static final fflib_Application.ServiceFactory service =
                  new ServiceFactory(
                    new Map<Type, Type>{Task_Service_Interface.class => 
                                        Task_Service_Impl.class});
}

Ok we’ve done the hardest parts now. Next we need to pretend that we are using the service class interface, service implementation class and service class that we already built earlier (just above you, scroll up to those sections and review them if you forgot), because we’ve about to see how a controller would call this task service we’ve built.

public with sharing class Abstract_Task_Creator_Controller
{
	@AuraEnabled
	public static void createTasks(Id recordId){
		Set<Id> recordIds = new Set<Id>{recordId};
		Schema.SObjectType objectType = recordId.getSobjectType();
		try{
			Task_Service.createTasks(recordIds, objectType);
		}
		catch(Exception e){
			throw new AuraHandledException(e.getMessage());
		}
	}
}

Now you might be wracking your brain right now and being like… ok, so what… but look closer Simba. This controller will literally never grow, neither will your Application class or your ServiceFactory class we’ve built above (well the Application class might, but very little). This Task_Service middle man layer is so abstract you can swap out service implementations on the fly whenever you want and this controller will NEVER NEED TO BE UPDATED (at least not for task service logic)! Basically the only thing that will change at this point is your custom metadata type (object), the custom permissions you map to users and you’ll add more variations of the Task Service Implementation classes throughout time for your various business units that get onboarded and want to use it. However, your controllers (and other places in the code that call the service) will never know the difference. Wyld right. If you’re lost right now lets follow the chain of events step by step in order to clarify some things:

1) Controller calls the Task_Service class’s (the middleman) createTasks() method.
2) Task_Service’s createTasks() method calls its service() method.
3) The service() method uses the Application classes “service” variable, which is an instance of our custom ServiceFactory class (shown above) to create a new instance of our whatever Task Implementation class (which inherits from the Task_Service_Interface class making it of type Task_Service_Interface) is relevant for our users assigned custom permissions by using the newInstance() method the ServiceFactory class overrode.
4) The service variable returns the correct Task Service Implementation for the running user.
5) The createTasks() method is called for whatever Task Service Implementation was determined to be correct for the running user.
6) Tasks are created!

If you’re still shook by all this, please, watch the video where we build all this together step by step and walk through everything. I promise, even if it’s a bit confusing, it’s worth the time to learn.


Next Section

Part 9: The Template Method Pattern

SoC and the Apex Common Library Tutorial Series Part 9: The Template Method Pattern

What is the Template Method Pattern?

The Template Method Pattern is one of the more popular Behavioral Design Pattern. The Template Design Pattern basically is creating a genericized skeleton class that a sub class can extend and add functionality to. The genericized skeleton class has some core functionality pre-built, but expects you to fill out (although not explicitly) other overridable methods in your sub class, to actually get much benefit out of it. Most trigger frameworks in existence leverage the Template Method Pattern. In fact there are a lot of frameworks in existence out there that leverage this pattern and I’m not even sure the creators know they leveraged it.


Why is it Useful?

This pattern is extremely useful because it allows you to define the core, generic parts of a class implementation (so it doesn’t need to be re-built over and over), while also allowing different developers the ability to implement their unique logic for their specific implementation. Take for instance a simple trigger handler framework. Most of these use the template method pattern. The core functionality is there (when to run a before insert method or how to handle certain trigger context variables, etc) but the object specific logic methods are overridable. For instance, the methods that determine what to do on the insert of a record, that would be overridden in an extended sub class and then on an object by object basis that logic would be able to differ.


Where does it fit into Separation of Concerns?

This fits into the concept of SoC because this pattern makes sure that you don’t repeat yourself (the DRY principle) and you write the minimal amount of code. Basically it allows you to separate out the generic code from the object specific code that has to be executed. You only write the generic code once and then allow subclasses to extend your template class and implement logic for those empty methods in your template class that need to have object or service specific logic.


Where is it used in the Apex Common Library

This design pattern is leveraged heavily by the fflib_SObjectDomain class in the Apex Common Library.


Example Code (Abstract Task Creation App)

fflib_SObjectDomain class – This class in the Apex Common library uses the template method pattern. Observe the many empty overridable methods (onBeforeInsert, onValidate, onBeforeUpdate, etc). It is expecting that a subclass will extend it and override one or more of those methods to make any true functionality occur.

Cases domain class that extends the fflib_SObjectDomain Template Class – The methods onApplyDefaults and onValidate are empty methods in the template class (the fflib_SObjectDomain class) that you need to implement in your subclasses to have any functionality happen.


Next Section

Part 10: The Domain Layer

SoC and the Apex Common Library Tutorial Series Part 10: The Domain Layer

What is the Domain Layer?

The Domain Layer is, “An object model of the domain that incorporates both behavior and data”. – Martin Fowler

In most coding languages you need to connect to the database, query for the data and then you create wrapper classes to represent each underlying table in your database(s) to allow you to define how that particular table (object) should behave. Salesforce, however, already does a lot of this for you, for instance there is no need to connect to a Database, declarative behavior for you tables (objects) are already represented and your tables (objects) already have wrapper classes pre-defined for them (Ex: Contact cont = new Contact()).

However the logic represented in a trigger is an exception to this rule. Apex triggers represent a unique scenario on the Salesforce platform, they are necessary for complex logic, but inherently they do not abide by any object oriented principles. You can’t create public methods in them, you can’t unit test them, you can’t re-use logic placed directly in a trigger anywhere else in your system, etc. Which is a massive detriment we need to overcome. That’s where the domain layer comes in to play.

The Domain Layer will allow you on an object by object basis have an object oriented approach to centralize your logic. Basically, logic specific to a single object will be located in one place and only one place by using the domain layer. This ensures your logic specific to a single object isn’t split into a ton of different places across your org.


When to make a new Domain Layer Class

Basically, at the very least, anytime you need to make a trigger on an object you should implement a Domain Class. However this is a bit generalized, sometimes you don’t actually need a trigger on an object, but you have object specific behavior that should be implemented in a Domain class. For instance, if you have an object that doesn’t need a trigger, but it has a very specific way it should have its tasks created, you should probably create a Domain Layer class for that object and put that task creation behavior there.

A domain layer class is essentially a mixture of a trigger handler class and a class that represents object specific behaviors.


Where should you leverage the domain layer in your code?

You should only ever call to the domain layer code from service class methods or from other domain class methods. Controller, Batch Classes, etc should never call out to the domain directly.


Domain Class Naming Conventions

Class Names – Domain classes should be named as the plural of whatever object you are creating a domain layer for. For instance if you were creating a domain layer class for the Case object, the class would be declared as follows: public inherited sharing class Cases. This indicates that the class should be bulkified and handles multiple records, not a single object record.

Class Constructor – The constructor of these classes should always accept a list of records. This list of records will be leveraged by all of the methods within the domain class. This will be further explained below.

Method Names – Method names for database transaction should use the onTransactionName naming convention (Example: onAfterInsert). If the method is not related to a database transaction it should descriptive to indicate what domain logic is being executed within it (Example: determineCaseStatus).

Parameter Names and Types – You do not typically need to pass anything into your domain layer methods. They should primarily operate on the list of records passed in the constructor in the majority of situations. However some behavior based (non-trigger invoked) methods may need other domain objects and/or units of work passed to them. This will be further explained in the sections below.


Domain Layer Best Practices

Trasnaction Management

In the event you are actually performing DML operations in your Domain class, you should either create a Unit of Work or have one passed into the method doing the DML to appropriately manage your transaction. In the event you are not wanting to leverage the unit of work pattern you should make sure to at the very least set your System.Savepoint savePoint = Database.setSavePoint(); prior to doing your DML statement and use a try catch block to rollback if the DML fails.


Implementing the Domain Layer

To find out how to implement the Domain Layer using Apex Common, continue reading here: Implementing the Domain Layer with the Apex Common Library. If you’re not interested in utilizing the Apex Common library for this layer you can implement really any trigger framework and the core of the domain layer will be covered.

Libraries That Could Be Used for the Domain Layer

Apex Common (Contains a framework for all layers)

Apex Trigger Actions Framework

SFDC Trigger Framework

MyTriggers


Domain Layer Examples

Apex Common Examples (Suggested)

Case Object Domain Layer Example

Contact Object Domain Layer Example

SFDC Trigger Framework Example

Case Object Domain Layer Example


Next Section

Part 11: Implementing the Domain Layer with the Apex Common Library

SoC and the Apex Common Library Tutorial Series Part 12: The Builder Pattern

What is the Builder Pattern?

The Builder Pattern is a Creational Design Pattern that allows you to construct a complex object one step at a time. Think about the construction of a car or your house or maybe something less complicated, like the construction of a desktop computer. When you’re creating a new desktop computer you have to make a ton of selections to build the computer. You have to get the right cpu, motherboard, etc. Instead of passing all that selection information into a class that constructed the computer, it’d be a lot nicer to build it step by step. Let’s check out some examples:

Non-Builder Pattern Computer Building Class Example:

public class ComputerBuilderController(){
    public ComputerCreator createMidTierComputer(){
        return new ComputerCreator(midTierGraphicsCard, midTierCPU, midTierMotherboard, 
        midTierFan, null, null).getComputer();
    }

    public ComputerCreator createTopTierComputer(){
        return new ComputerCreator(topTierGraphicsCard, topTierCPU, topTierMotherboard, 
        topTierFan, topTierNetworkCard, null).getComputer();
    }
}

public class ComputerCreator{
    private CPU compCPU;
    private GPU compGPU;
    private MotherBoard compMotherBoard;
    private Fan compFan;
    private NetworkCard compNetworkCard;
    private Speakers compSpeakers;

    //This could go on for forever and you might have 300 different constructors with 
    //different variations of computer parts... This could become
    //an absolutely enormous class.
    public ComputerCreator(GraphicsCard selectedGraphicsCard, CPU selectedCPU, MotherBoard 
          selectedMotherboard, Fan selectedFan, NetworkCard selectedNetworkCard, Speakers 
          selectedSpeakers){
        setComputer(selectedGraphicsCard, selectedCPU, selectedMotherboard, selectedFan, 
                    selectedNetworkCard, selectedSpeakers);
    }

    //Because of how this is setup, we're setting everything for the computer, even if we're 
    //just setting the computer parts to null
    private void setComputer(GraphicsCard selectedGraphicsCard, CPU selectedCPU, MotherBoard 
            selectedMotherboard, Fan selectedFan, NetworkCard selectedNetworkCard, Speakers 
            selectedSpeakers){
                    this.compGPU= selectedGraphicsCard;
                    this.compCPU = selectedCPU;
                    this.compMotherBoard = selectedMotherboard; 
                    this.compFan= selectedFan; 
                    this.compNetworkCard = selectedNetworkCard; 
                    this.compSpeakers = selectedSpeakers;   
    }

    public ComputerCreator getComputer(){
        return this;
    }
}

You can see in the above example, this setup is not exactly ideal, nor does it lend itself to easy code changes. If you go with the single constructor approach and just allow developers to pass in nulls to the constructor, every time you need to add another option for the computers your code might build, you’ll have to update every piece of code that calls the ComputerCreator class because the constructor will change. Alternatively if you go with new constructor variations for each new option you could end up with hundreds of constructors over time… also not great at all. That can be extremely confusing and difficult to upkeep. So let’s look at how to leverage the builder pattern to achieve the same thing.

Builder Pattern Computer Building Class Example:

public class ComputerBuilderController(){
       
    public ComputerCreator createMidTierComputer(){
        return new ComputerCreator().
                   setCPU(midTierCPU).
                   setGPU(midTierGPU).
                   setMotherBoard(midTierMotherBoard).
                   setFan(midTierFan);
    }

    public void createTopTierComputer(){
        return new ComputerCreator().
                   setCPU(topTierCPU).
                   setGPU(topTierGPU).
                   setMotherBoard(topTierMotherBoard).
                   setFan(topTierFan).
                   setNetworkCard(topTierNetworkCard);
    }
}

public class ComputerCreator{
    private CPU compCPU;
    private GPU compGPU;
    private MotherBoard compMotherBoard;
    private Fan compFan;
    private NetworkCard compNetworkCard;
    private Speakers compSpeakers;
    
    public ComputerCreator setCPU(CPU selectedCPU){
        this.compCPU = selectedCPU;
        return this;
    }

    public ComputerCreator setGPU(GPU selectedGPU){
        this.compGPU = selectedGPU;
        return this;
    }

    public ComputerCreator setMotherBoard(MotherBoard selectedMotherBoard){
        this.compMotherBoard = selectedMotherBoard;
        return this;
    }

    public ComputerCreator setFan(Fan selectedFan){
        this.compFan = selectedFan;
        return this;
    }

    public ComputerCreator setNetworkCard(NetworkCard selectedNetworkCard){
        this.compNetworkCard = selectedNetworkCard;
        return this;
    }

    public ComputerCreator setSpeakers(Speaker selectedSpeakers){
        this.compSpeakers= selectedSpeakers;
        return this;
    }
}

You can see in the above example that using the builder pattern here gives us an enormous amount of flexibility. We no longer need to pass null values into a constructor or build a bajillion constructor variations, we only need to call the methods to set each piece of the computer should we need to set them. You can see we now only worry about setting values for things we actually need to set for our computer. Additionally, you can add new options for computer parts to set in the ComputerCreator class easily and it won’t affect that code that has already been written. For instance if I created a setWebcam method it would be no big deal. My createMidTierComputer and createTopTierComputer methods would not be impacted in any way and continue to function just fine. Builder Pattern FTW!


Why is it Useful?

Take the computer example above, without the builder pattern you get one of two things. You either get an enormous constructor you send all your computer parts to (that you will likely pass a ton of nulls to) or you have a ton of constructors to represent different computer variations… either choice is not a great choice. Complex objects typically have potentially hundreds of optional choices you can make, you need something more robust to select those options.

The builder pattern allows you to select those options piece by piece if you want them. Take for instance the computer example again. Desktop computers do not need things like network cards or speakers or a webcam to function. That being said, many people building a computer may want them for one reason or another to make their specific computer useful for them. Instead making constructor variations for every combination of those items, why not just use the builder pattern to add them as needed? It makes the code a whole lot easier to deal with and easier to extend in the future.


Where does it fit into Separation of Concerns?

Builder classes are typically service classes of some sort, maybe you create some super elaborate Opportunities in your org. You might have an Opportunity_Builder_Service or something along those lines. It can help in a lot of areas to reduce your code in the long term and to increase your codes flexibility for allowing new options for the object you are building, and I think we all know (if you’ve been doing this long enough), businesses like to add and subtract things from the services they create on a whim.


Where is it used in the Apex Common Library?

This design pattern is leveraged heavily by the fflib_QueryFactory class in the Apex Common Library. It allows us to build complex SOQL queries by building them step by step.


Example Code

The fflib_QueryFactory class is an example of a class designed using the builder pattern.

The Case_Selector class I’ve created has several examples of how it looks when you call and utilize a class leveraging the builder pattern.


Next Section

Part 13: The Selector Layer

SoC and the Apex Common Library Tutorial Series Part 13: The Selector Layer

What is the Selector Layer

The Selector Layer is Salesforce is based off Martin Fowler’s Data Mapper Layer concept. It’s, “a layer of Mappers that moves data between objects and a database while keeping them independent of each other and the Mapper itself”.

In most tech stacks when you want to represent records in a database table you create classes in your code base to represent them to hold them in memory and prep them for transit to the actual database. These are what Martin references as “objects” in the above quote. Salesforce already creates these classes for you in the background to represent your Custom and Standard Objects. It’s why you can just inherently write Case cs = new Case(); in Apex and it creates a brand new Case record for you.

Since Salesforce already does that work for you, the Data Mapper Layer, just turns into the Selector Layer and within the Selector Layer we are basically just concerned with housing and performing queries for our respective objects. You will ideally call upon the Selector Layer every single time you need to make a query in Apex. The largest goal with this layer is to avoid having repetitive queries everywhere within the system and to have some overall consistency with your object queries (the fields always queried, limits, order by clause, etc).


When to make a new Selector Layer Class

Whenever you need to create queries on an object you’ve never done queries on before, you would create a new Selector Layer Class. So for instance if you needed to create some queries for the case object to use in your service or domain layer classes, you would create a Case Selector class. There should typically be one selector class per object you intend to query on.


Selector Layer Naming Conventions

Class Names – Your classes should ideally follow the naming conventions of the domain layer just with Selector appended to the end of them, unless you have common cross object queries then it’s a bit different.

Selector Class Naming Examples (Note that I prefer underscores in names, this is personal preference):

Accounts_Selector
Opportunities_Selector
OpportunityQuotes_Selector

Method Naming and Signatures – The names of the methods in a selector class should all start with the word “select”. They should also only return a list, map or QuerySelector and should only accept bulkified parameters (Sets, Lists, Maps, etc). A few good examples of method examples are below.

Selector Method Examples

public List<sObject> selectById(Set<Id> sObjectIds)
public List<sObject> selectByAccountId(Set<Id> accountIds)
public Database.QueryLocator selectByLastModifiedDate(Date dateToFilterOn)

Selector Layer Security

The Selector Layer classes should all ideally inherit their sharing from the classes calling them. So they should typically be declared as follows:

public inherited sharing class Account_Selector

If there are queries for your object that you absolutely must have run in system context (without sharing) you would want to elevate those permissions through the use of a private inner class like so:

public inherited sharing class Account_Selector 
{
    public List<Account> selectAccountsById(Set<Id> acctIds){
        return new Account_Selector_WithoutSharing().selectAccountsByIdElevated(acctIds);
    } 

    private without sharing Account_Selector_WithoutSharing{
        public List<Account> selectAccountsByIdElevated(Set<Id> acctIds){
            return [SELECT Id FROM Account WHERE Id IN : acctIds]; 
        }
    }
}

Implementing the Selector Layer

To find out how to implement the Selector Layer using Apex Commons, continue reading here: Implementing the Selector Layer with the Apex Common Library . If you’re not interested in utilizing the Apex Common library for this layer there are pretty sparing options out there that are pre-built, the only other option I’m aware of at this time is Query.apex. Outside of that, you could certainly roll your own selector layer, but it is no small feat if done right.

Libraries That Could Be Used for the Domain Layer

Apex Common (Contains a framework for all layers)

Query.apex


Selector Layer Examples

Apex Common Examples (Suggested)

Case Object Selector Example (Lots of comments)

Contact Object Selector Example

Task Object Selector Example

Non Apex Common Examples

Case Object Selector Simple Example


Next Section

Part 14: Implementing the Selector Layer with the Apex Common Library

SoC and the Apex Common Library Tutorial Series Part 14: Implementing the Selector Layer with the Apex Common Library

The Template for every Selector Class you create

Every Selector layer class you create should at least implement the following methods for it to work as anticipated.

//Selector layer classes should all use the inherited sharing keyword so that the caller //determines to context it operates in.
//It should also always extend the fflib_SObjectSelector so it can inherit that classes //methods and functionality.
public inherited sharing class Contact_Selector extends fflib_SObjectSelector
{
	public Contact_Selector(){
                /*This is calling the fflib_SObjectSelector classes constructor and setting 
                  the following booleans:
                  1) If the selector queries should use field sets
                  2) If you would like to enforce CRUD security
                  3) If you would like to enforce FLS
                  4) If you would like to sort selected fields
                */
		super(false, true, true, false);
	}

        //Add the base fields for the object that should just be used in absolutely every 
        //query done by this class
	public List<Schema.SObjectField> getSObjectFieldList(){
		return new List<Schema.SObjectField>{
				Contact.Id,
				Contact.Name,
				Contact.FirstName,
				Contact.LastName
		};
	}

        //Allows you to easily get the object type for the object being queried by this class
	public Schema.SObjectType getSObjectType(){
		return Contact.SObjectType;
	}

        //Allows you to create a query that selects records by a set of ids (basically adds 
        //the WHERE Id IN :ContactIds to the query)
	public List<Contact> selectById(Set<Id> contactIds){
		return (List<Contact>) selectSObjectsById(contactIds);
	}
}

The fflib_SObjectSelector Constructor Parameters and what each of them mean

When you create a Selector class that extends the fflib_SObjectSelector class you have the option to send some parameters to its constructor that determine how to the selector class functions. They are the following (in order of parameters passed to the constructor):

1) Would you like to allow your class to use field sets when building the initial query fields for your selector layer class? By default this parameter is set to false.

2) Would you like to enforce CRUD (Object level create, read, update, delete) security on your selector layer class? By default this parameter is set to true.

3) Would you like to enforce FLS (Field level security) on your selector layer class? By default this parameter is set to false.

4) Would you like your selected fields in your query to be sorted alphabetically when your query is created (this is literally just a sort call on a list of strings in the code)? By default this parameter is set to true.

If you would like to alter any of these settings for your selector class you can do the following:

public inherited sharing class Contact_Selector extends fflib_SObjectSelector
{
        //In our selector classes constructor we are calling the fflib_SObjectSelector using the super() call
        //and setting out parameters.
	public Contact_Selector(){
                //This is completely optional. If you like the defaults listed above you do not have to call the super class constructor at all.  
		super(false, true, true, false);
	}
}

Note that this is completely optional, if you like the default behavior listed above, just don’t bother calling the super method and overriding them!


How to set the default field selection for your Selector Class

One of the biggest benefits of the selector layer is selected field consistency in your queries. If 99% of the time you are querying for the subject field on your Case object, why not just query for it by default without ever thinking about it again right?? Well the getSObjectFieldList method that you implement in your Selector classes does just that. Here’s how to implement that method in your selector:

public List<Schema.SObjectField> getSObjectFieldList(){
        //Note that this is using concrete references to the fields, not dynamic soql (here at 
        //least). This is to ensure the system knows
        //your code is dependent on these fields so you don't accidentally delete them some 
        //day.
	return new List<Schema.SObjectField>{
                        //In this list, place every field you would like to be queried for by 
                        //default when creating a query
                        //with your selector class.
			Contact.Id,
			Contact.Name,
			Contact.FirstName,
			Contact.LastName
	};
}

If you choose to enable field sets to allow for default field selection for your selector class, you can implement the following method to select fields from the field set to be included in your queries:

public override List<Schema.FieldSet> getSObjectFieldSetList(){
    return new List<Schema.FieldSet>{SObjectType.Case.FieldSets.CaseFieldSetForSelector};
}

The major benefit of using the field sets for query fields is you can add new fields on the fly without adding extra code. This becomes super important if you’re building a managed package.


How to set your default OrderBy clause in your Selector Class

By default all Selector Layer Classes that extend the fflib_SObjectSelctor are ordered by the Name field (if the name field isn’t available on the queried object it defaults to CreatedDate). If that’s kewl with you, no need to override it, but if you’d prefer the default sort order for your select class be different then you just need to override the following method like so:

public override String getOrderBy(){
    return 'Subject';
}

If you wanted to order by multiple fields you would just do the following (basically just create a comma separated list in the form of a string):

public override String getOrderBy(){
    return 'Subject, Name, CustomField__c, CustomLookup__r.Name';
}

The fflib_QueryFactory class and Custom Queries

Chances are you’re gonna wanna query something that’s not immediately available via the fflib_SObjectSelect class, well lucky for you the fflib_QueryFactory class is here just for that! Here is an example of a custom query via the use of the fflib_QueryFactory class (a list of all available query factory methods are at the bottom of this wiki article).

//This allows us to select all new cases in the system using the QueryFactory in //fflib_SObjectSelector
public List<Case> selectNewCases(){
    return (List<Case>) Database.query(newQueryFactory().
    selectField(Case.Origin).
    setCondition('Status = \'New\'').
    setLimit(1000).
    toSOQL());
}

There are also tons of other methods that allow you to add offsets, subselects, set ordering and more (outlined in the method cheat sheet section).


How to Do Sub-Select Queries (Inner Queries)

There’s a kinda handy way to do sub-select queries by using the fflib_QueryFactory class. You can use it in your selector class’s methods as outlined below:

//Pretend this method exists in a Case_Selector class
public List<Case> innerQueryExample(){
    //Using this Case_Selectors newQueryFactory method that it inherits from the 
    //fflib_SObjectSelector class it extends
    fflib_QueryFactory caseQueryFactory = newQueryFactory();

    //Creating a new instance of our Task_Selector class and using the 
    //addQueryFactorySubselect method to add the task query as a 
    //inner query for the caseQueryFacorty
    fflib_QueryFactory taskSubSelectQuery = new 
    Task_Selector().addQueryFactorySubselect(caseQueryFactory);
  
    //Querying for our data and returning it.
    return (List<Case>) Database.query(caseQueryFactory.toSOQL());
}

How to do Aggregate Queries

There’s not really a built-in method in either the fflib_SObjectSelector or the QueryFactory class to deal with this. So you just deal with aggregate queries by building a method in your Selector Class in the following way:

public List<AggregateResult> selectAverageTacosPerTacoBell(){
    List<AggregateResult> tacoData = new List<AggregateResult>();
    for(AggregateResult result: [SELECT Id, AVG(Tacos_Sold__c) avgTacos FROM Taco_Bell__c 
        GROUP BY Taco_Type__c]){
        tacoData.add(result);
    }
    return tacoData;
}

The fflib_SObjectSelector Class methods Cheat Sheet

While there are many other methods within the fflib_SObjectSelector class below are the methods most commonly utilized in implementations.

1) getSObjectName()_ – Returns the name of the object that your select was built for.

2) selectSObjectsById(Set<Id> idSet) – Returns a query that selects all the records in your id set. It constructs a query based on the fields you declare in your selector class’s getSObjectFieldsList method and orders them by whatever is represented in the m_orderBy variable.

3) queryLocatorById(Set<Id> idSet) – This method is basically the same as the selectSObjectsById method except that it returns a query locator instead. This should be leveraged for batch classes that need query locators.

4) newQueryFactory – This method returns a new instance of the fflib_QueryFactory class and uses your selector classes fields listed in the getSObjectFieldsList method and orders them by whatever you set the default orderby to in your selector class.

5) addQueryFactorySubselect(fflib_QueryFactory parentQueryFactory) – This method basically just creates a subselect query (an inner query) for the “parentQueryFactory” and then returns the parent query with a subselect query that represents the query for your objects selector class (more info on how this method works in the sub-select query section in this wiki article).


The fflib_QueryFactory Class methods Cheat Sheet

While there are many other methods within the fflib_QueryFactory class below are the methods most commonly utilized in implementations.

1) assertIsAccessible() – This method checks to see if the running user can actually read to object this selector was built for.

2) setEnforceFLS(Boolean enforce) – This method determines whether or not to enforce field level security on the query you are running.

3) setSortSelectFields(Boolean doSort) – If you would like the list of fields selected to be selected in alphabetical order, you can use this method to make your selected fields be selected in alphabetical order.

4) selectField(Schema.SObjectField field) – Use this method to select a field for your query.

5) selectFields(Set fields) – Use this method to select multiple fields for your query at the same time.

6) selectFieldSet(Schema.FieldSet fieldSet) – Use this method to select fields for your query from a field set.

7) setCondition(String conditionExpression) – Use this method to set the conditions for your query (basically you are setting the WHERE clause in your query. Do NOT add the WHERE to the string you pass into to this method).

8) setLimit(Integer limitCount) – Sets a limit for your query.

9) setOffset(Integer offsetCount) – Sets an offset for your query.

10) addOrdering(Ordering o) – Sets up an ORDER BY clause for your query. You need to build an fflib_QueryFactory.Ordering object to pass to this method. There are a ton of ordering method permutations in this class, so definitely check them all out.

11) subselectQuery(String relationshipName) – Sets up a subquery for the query. You need to pass in a string representation of the relationship fields developer name to this method.

12) toSOQL() – Takes the fflib_QueryFactory you’ve just built and turns it into an actual string representation of the query that you can use in a Database.query() call.

13) deepClone() – Creates a clone of your fflib_QueryBuilder query in case you’d like an easy way to generate another permutation of this query without rebuilding the whole thing.


Next Section

Part 15: The Difference Between Unit Tests and Integration Tests

SoC and the Apex Common Library Tutorial Series Part 15: The Difference Between Unit Tests and Integration Tests

What is Unit Testing?

Unit Testing, is a way to test the logic in one class and ONLY one class at a time. Most classes in your system at some point do one of the following:

1) Call to another class to get some work done.
2) Query the database directly in the class.
3) Do DML transactions directly in the class.

However, in unit testing, we ideally don’t want to do any of those things, we don’t care if the querying or the DML transactions or the calls to those other classes work, because what we want to test is that the logic of our class works in every theoretical permutation we can think of AND THAT’S IT! We just want to know if our logic, that we designed for this one class actually works as we anticipate it to work.

You might be thinking, “How is that possible? We need those queries and those dml statements and those classes to successfully run our code!”. Well that my friends is simply not true. With the implementation of separation of concerns and by leveraging one of the many available mocking frameworks we can fake all of those things to build true unit tests.


When Should I use Unit Testing?

Just because you are leveraging unit testing doesn’t mean there still isn’t a need for integration tests (more on that below), so when should you do Unit Tests in favor of Integration tests? It’s a pretty simple answer. The logic in your class’s code could have 40+ paths it could take… maybe even 100… The code in your class could have logic that runs when your code fails, logic that runs when your codes successful, logic that runs when someone creates a $200,000,000 opportunity as opposed to a $2,000 opportunity. There could be so many paths. We DO NOT need an integration test for every single one of those paths. It could take 20+ minutes to run integration tests for all those paths whereas unit testing them could take just seconds. As your codebase grows, if you didn’t make these unit tests your test class runs to deploy to prod could take hours… maybe days… we don’t want that homie. So when do you unit test? You unit test to test the bajillions of permutations of your class’s logic. When do we choose integration tests?? Keep reading. You’ll find out below.

An additional benefit to unit testing/mocking responses is testing hard to test or impossible to test error catching scenarios. One common scenario that I find myself frequently building error catching around is record locking… but how on earth can you test that with real data at run time? It’s borderline impossible, however unit testing makes testing for errors a breeze. It’s so easy you’ll cry, lol, the dream of 100% code coverage can go from just a dream to a very real and easily obtainable thing with unit tests and mocking.


What is Integration Testing?

Integration testing is when you test your code from point A all the way to point Z. What I mean by that is, you actually have your code in your test classes doing SOQL statements, DML transactions, calling the other classes it depends on, etc. Basically your code is truly calling all the real logic from beginning to end, no mocking or fake return results anywhere. Integration testing is what 90%+ of Salesforce orgs seem to do 100% of the time and that is one dangerous game to play. The majority of your tests should not be integration tests… maybe like 20% of them or so. If 100% of your test classes are integration tests, over time you’ll suffer from long test execution and deployment times (or alternatively poorly tested code to reduce those times). If you’ve ever been stuck in a 6+ hour deployment, I think you know what I mean… and what if one test fails during that deploy?… it really hurts, lol. Please, don’t get me wrong though, you can not replace integration tests with unit tests, they are of equal importance, it’s just important that you only use integration tests when needed.


When Should I use Integration Testing?

All apex classes should have some level of integration testing. I like to write somewhere around 20% of my tests as integration tests and 80% of my tests for a class as unit tests. Typically I will, for each class that has dependencies (classes that the class I’m currently testing calls) write two integration tests for each dependency. One integration test that tests a successful path through my classes code and its dependencies and another that tests failures. This may be, in some peoples opinion, overkill, but I personally feel that it’s not an enormous amount of overhead (typically) and it gives me some piece of mind that all of the classes my class I’m testing depends on still operate well with it. So, when to use integration testing? In my opinion, in every test class, but use them sparingly, use them to check that your transactions between classes still work, don’t use them to test every logical path in your class’s code. That will spiral out of control.


Next Section

Part 16: Unit Test Mocks with Separation of Concerns

SoC and the Apex Common Library Tutorial Series Part 16: Unit Test Mocks with Separation of Concerns

How does Unit Testing fit into Separation of Concerns?

The answer to this is simple, without Separation of Concerns, there is no unit testing, it just simply isn’t possible. To unit test you need to be able to create stub (mock) classes to send into your class you are testing via dependency injection (or through the use of a factory, more on this in the next section). If all of your concerns are in one class (DML transactions, SOQL queries, service method, domain methods, etc) you cannot fake anything. Let’s take a look at a couple examples to illustrate this problem:

Unit Testing a class with SoC Implemented

//This is the class we would be testing
public with sharing class SoC_Class
{
	private DomainClass domainLayerClass;
	private SelectorClass selectorLayerClass;

	public SoC_Class(){
		//This is calling our private constructor below
		this(new domainLayerClass(), new selectorLayerClass());
	}

	//Using a private constructor here so our test class can pass in dependencies we would
	//like to mock in our unit tests
	@TestVisible
	private SoC_Class(DomainClass domainLayerClass, SelectorClass selectorLayerClass){
		this.domainLayerClass = domainLayerClass;
		this.selectorLayerClass = selectorLayerClass;
	}

	public List<Case> updateCases(Set<Id> objectIds){
		//Because of our dependency injection in the private constructor above we can 
                //mock the results of these class calls.
		List<Case> objList = selectorLayerClass.selectByIds(objectIds);
		if(!objList.isEmpty()){
			List<Case> objList = domainLayerClass.updateCases(objList);
			return objList;
		}
		else{
			throw new Custom_Exception();
		}
	}
}

//This is the class that we build to unit test the class above
@IsTest
public with sharing class SoC_Class_Test
{
	@IsTest
	private static void updateCases_OppListResults_UnitTest(){
		//Creating a new fake case id using the IdGenerator class. We do this
		//to avoid unnecessary dml insert statements. Note how the same id is used 
                //everywhere.
		Id mockCaseId = fflib_IDGenerator.generate(Case.SObjectType);
		//Creating a set of ids that we pass to our methods.
		Set<Id> caseIds = new Set<Id>{mockCaseId};
		//Creating the list of cases we'll return from our selector method
		List<Case> caseList = new List<Case>{new Case(Id = mockCaseId, Subject = 'Hi', 
                Status = 'New', Origin = 'Email')};
		List<Case> updatedCaseList = new List<Case>{new Case(Id = mockCaseId, Subject 
                = 'Panther', Status = 'Chocolate', Origin = 'Email')};

		//Creating our mock class representations by using the ApexMocks class's mock 
                //method and passing it the appropriate class type.
		fflib_ApexMocks mocks = new fflib_ApexMocks();
		DomainClass mockDomain = (DomainClass) mocks.mock(DomainClass.class);
		SelectorClass mockSelector = (SelectorClass) mocks.mock(SelectorClass.class);

		//After you've setup your mocks above, we need to stub (or setup the expected
		//method calls and what they would return.
		mocks.startStubbing();

		//This is the actual selectByIds method that we call in the
		//createNewOpportunities method that we are testing
		//Here we are setting up the fake return result it will return.
		mocks.when(mockSelector.selectByIds(caseIds)).thenReturn(caseList);

		mocks.when(mockDomain.updateCases(caseList)).thenReturn(updatedCaseList);

		//When you are done setting these up, DO NOT FORGET to call the stopStubbing 
                //method or you're gonna waste hours of your life confused
		mocks.stopStubbing();

		Test.startTest();
		//Passing our mock classes into our private constructor
		List<Case> updatedCases = new SoC_Class(mockDomain, 
                mockSelector).updateCases(caseIds);
		Test.stopTest();

		System.assertEquals('Panther', updatedCases[0].Subject, 
                                    'Case subject not updated');
		//Verifying this method was never called, we didn't intend to call it, so
		//just checking we didn't
		((Cases)mocks.verify(mockDomain, mocks.never().description('This method was 
                called but it shouldn\'t have been'))).createOpportunities();
		//Checking that we did indeed call the createTasks method as expected.
		((Cases)mocks.verify(mockDomain)).updateCases(caseList);
	}
}

Above you can see we are passing in fake/mock classes to the class we are testing and staging fake return results for the class methods we are calling. Thanks to separating out our concerns this is possible. Let’s take a look at how impossible this is without SoC in place.

Unit Testing a class without SoC Implemented

//This is the class we would be testing
public with sharing class No_SoC_Class
{
	public List<Case> updateCases(Set<Id> objectIds){
		//Because of our dependency injection in the private constructor above we can 
                //mock the results of these class calls.
		List<Case> objList = [SELECT Id, Name FROM Case WHERE Id IN: objectIds]
		if(!objList.isEmpty()){
			for(Case cs: objList){
				cs.Subject = 'Panther';
				cs.Status = 'Chocolate';
			}

			update objList;
			return objList;
		}
		else{
			throw new Custom_Exception();
		}
	}
}

@IsTest
public with sharing class No_SoC_Class_Test
{
	@TestSetup
	private static void setupData(){
		Case newCase = new Case(Subject = 'Hi', Status = 'New', Origin = 'Email');
		insert newCase;
	}

	@IsTest
	private static void updateCases_CaseListResults_IntegrationTest(){
		Set<Id> caseIds = new Map<Id, SObject>([SELECT Id FROM Case]).keySet();
		List<Case> updatedCases = new No_SoC_Class().updateCases(caseIds);
		System.assertEquals('Panther', updatedCases[0].Subject, 'Case subject not 
                updated');
	}
}

You can see above we did no mocking… it wasn’t possible, we had no way of passing in fake/mock classes to this class at all so we had to do an integration test where we create real data and update real data. This test will run considerably slower.


How do I transition my Existing Code to start leveraging SoC so I can use Unit Test Mocking?

It’s not a simple path unfortunately, there is a lot of work ahead of you to start this transition, but it is possible. The key is to start small, if you are a tech lead the first thing you need to do is find the time to train your devs on what SoC and mocking is and why you would use it. It’s critical they understand the concepts before trying to roll something like this out. You cannot do everything as a lead even if you’d like to, you need to build your team’s skillset first. If you aren’t a lead, you first need to convince your lead why it’s critical you start taking steps in that direction and work to get them onboard with it. If they ignore you, you need a new lead… After accomplishing either the above you should do the following:

1) Frame your situation in a way that the business arm of your operation understands the importance of altering your code architecture to leverage SoC and unit testing. This is typically pretty easy, just inform them that by spending a few extra points per story to transition the code you are going to gain more robust testing (resulting in less manual tests) and that the code will become more flexible over time, allowing for easier feature additions to your org. Boom, done, product owner buy in has been solidified. Ok, lol, sometimes it’s not quite this easy, but you know your business people, give them something they won’t ignore, just be careful to not make yourself or your team sound incompetent, don’t overcommit and make promises you can’t keep and frame it in words business people understand (mostly dollar signs).

2) Start small, take this on a story by story basis. Say you have a new story to update some UI in your org, with business owner buy-in, tack on a few extra points to the story to switch it to start using SoC and Unit Testing. Then, MAKE SURE YOUR TESTS ARE INCREDIBLE AND YOU TRUST THEM! I say this because, if your tests are incredible you never have to ask for permission again… I mean think about it, wtf does the average business person know about code. As long as I don’t introduce any new bugs I could change half the code base and they’d never even know. If your tests are golden, your ability to change on a whim is as well. Make those test classes more trustworthy than your dog (or cat I guess… but I wouldn’t trust a cat).

3) Over time, your transition will be done… it might take a year, it might take 5 years, depends on how busted your codebase was to begin with. Hopefully, by the time you are done, you have an extremely extensible codebase with tests you can trust and you never have to ask for permission to do a damn thing again.


Additional Information

If the above didn’t make how to implement mocking via separation of concerns any clearer, I also have a video covering the subject here.


Next Section

Part 17: Implementing Mock Unit Testing with Apex Mocks