CollectionUtils is an Apex utility class for Salesforce. It provides generic, type-safe methods to convert lists of SObjects into Maps. These methods use a specified field as the key, including nested fields. It supports both single-value and list-value Maps, and works with both Id and String keys.

The library provides three main methods: idMapFromCollectionByKey, stringMapFromCollectionByKey, and idMapFromCollectionByKeyForList. These methods allow you to transform your data with ease, giving you more time to focus on what really matters.

• idMapFromCollectionByKey –
  1. The idMapFromCollectionByKey method is a generic, reusable, and type-safe method for generating a Map<Id, Some_SObject> from a list.
  2. This method stops developers from writing countless for loops. It also helps transform a list of SObjects. In the transformation, the map’s key is something other than the Id field.
  3. This method maintains type safety by accepting a generic list of SObjects. It determines the concrete SObject type of the incoming list’s first object. The concretely typed map is cast to a Map<Id, SObject>, and generic SObject methods construct the map.
• stringMapFromCollectionByKey
  1. The stringMapFromCollectionByKey method functions similarly to the idMapFromCollectionByKey method but generates a Map<String, Some_SObject> from a list.
  2. The key parameter must be something castable to a string. Developers are responsible for ensuring the uniqueness of the key’s value when using this method.
• idMapFromCollectionByKeyForList –
  1. The idMapFromCollectionByKeyForList method accepts an incoming List of sObjects and generates a Map<Id, List<sObject>>.
  2. This method helps avoid cluttering the codebase with for loops. For example, it can take a list of Contacts and return a Map<AccountId, List<Contact>>.
• stringMapFromCollectionByKeyForList
  1. The stringMapFromCollectionByKeyForList method functions similarly to the idMapFromCollectionByKeyForList but returns a Map<String, List<sObject>>.
  2. It groups the SObjects into lists. Each key is derived from a string-castable field. The developer must ensure key uniqueness.

Internal Logic and Helpers

Input Validation

All public methods first call isInvalidInput to check if the key is blank or the list is null/empty. If so, they return an empty Map.

Dynamic Map Creation

• Uses Type.forName and newInstance() to create Maps of the correct type at runtime, ensuring type safety.
• If dynamic creation fails, falls back to a generic Map.

Field Value Extraction

• Uses getFieldValue to extract the value for the key field from each SObject.
• Supports one level of nesting (e.g., 'Account.OwnerId').

Map Population

• For single-value Maps, each key maps to one SObject (last one wins if duplicates).
• For list-value Maps, each key maps to a list of SObjects sharing that key.

Example: How a Method Works

Let’s look at idMapFromCollectionByKey:

public static Map<Id, SObject> idMapFromCollectionByKey(String key, List<SObject> incomingList) {
    if (isInvalidInput(key, incomingList)) {
        return new Map<Id, SObject>();
    }
    return generateIdMap(key, incomingList);
}

• Checks input.
• Calls generateIdMap, which:
  • Dynamically creates a Map<Id, SObjectType>.
  • Loops through the list, gets the key value using getFieldValue.
  • Puts the SObject into the Map using the key.

Nested Field Support

The getFieldValue method allows you to use keys like 'Account.OwnerId'. It splits the key by ., gets the parent SObject, then the child field.

Sample Code:

Here is the sample CollectionUtils class –

Core Features

• Generic and Reusable: Write once, use everywhere.
• Type-Safe: Maintain type integrity in your maps.
• Dynamic: Handle nested keys effortlessly (e.g., Account.OwnerId).

Sample Scenarios Examples :

Let’s see how CollectionUtils can be used in different scenarios:

idMapFromCollectionByKey –

Example 1: Grouping Contacts by Id:

Contact[] contacts = [SELECT Id, FirstName, LastName FROM Contact];
Map<Id, Contact> contactsByAccountId = (Map<Id, Contact>) 
    CollectionUtils.idMapFromCollectionByKey('Id', contacts);

stringMapFromCollectionByKey –

Example 1: Grouping Contacts by Email:

Contact[] contacts = [SELECT Email, FirstName, LastName FROM Contact];
Map<String, Contact> contactsByEmail = ((Map<String, Contact>)  
    CollectionUtils.stringMapFromCollectionByKey('Email', contacts);

Example 2: Grouping Leads by Email

Lead[] leads = [SELECT Email, Name FROM Lead];
Map<String, Lead> leadsByEmail = (Map<String, Lead>) 
    CollectionUtils.stringMapFromCollectionByKey('Email', leads);

idMapFromCollectionByKeyForList –

Example 1: Grouping Contacts into lists by Account Id:

Contact[] contacts = [SELECT AccountId, FirstName, LastName FROM Contact];
Map<Id, List<Contact>> groupedContacts = ((Map<Id, List<Contact>>)  
    CollectionUtils.idMapFromCollectionByKeyForList('AccountId', contacts);

Example 2: Grouping Contacts into lists by Account.Owner Id

Contact[] contacts = [SELECT Account.OwnerId, FirstName, LastName FROM Contact];
Map<Id, List<Contact>> groupedContactsAccountOwnerId = (Map<Id, List<Contact>>)  
    CollectionUtils.idMapFromCollectionByKeyForList('Account.OwnerId', contacts);

stringMapFromCollectionByKeyForList –

Example 1: Grouping Opportunities into lists by Stage Name

Opportunity[] opportunities = [SELECT StageName, Amount FROM Opportunity];
Map<String, List<Opportunity>> opportunitiesByStage = (Map<String, List<Opportunity>>) 
    CollectionUtils.stringMapFromCollectionByKeyForList('StageName', opportunities);

Advantages of CollectionUtils

• No More Repetitive Loops: Skip the boilerplate code and focus on business logic.
• Handle Complex Keys: Easily work with nested relationships like Account.OwnerId.
• Readable Code: Makes your codebase cleaner and easier to understand.

Summary Table

Conclusion

The CollectionUtils class is a must-have in any Salesforce developer’s toolkit. By abstracting away repetitive for-loops, it streamlines data transformations, making your Apex code cleaner and more efficient. Whether you’re a seasoned developer or just getting started, this utility class will save you time and effort.

💡 Tip: Always validate your keys for uniqueness or nullability when using these methods to avoid runtime issues.

Source Reference – https://github.com/trailheadapps/apex-recipes

For more helpful articles please visit – https://thesalesforcedev.in/