A colleague of mine used to reference the following when talking about naming:

In my career so far, I have come to realize that there is some truth in this statement. Naming conventions have never been so important on Force.com as it is currently without a means to group or structure code files, using a directory structure for example. Instead, all classes are effectively in one root folder called /classes.

Thus, it comes down to the use of naming conventions to help clarify purpose (for developers, both new and old, working on the codebase) and to which layer in your architecture a class belongs. Naming does not, however, stop at the class name level; the enums, methods, and even parameter names all matter.

The following points break down some specific guidelines for the Service layer, though some are also applicable throughout your application code:

These guidelines should not only help you to ensure that your Service layer remains more neutral to its callers and thus more consumable now and in the future, but also to follow some best practices around the platform. Finally, as we will discuss in Chapter 9, Providing Integration and Extensibility, following these guidelines leaves things in good shape to expose as an actual API, if desired.

It's well known that the best practice of Apex is to implement bulkification within Apex Triggers, mainly because they can receive and process many records of the same type. This is also true for the use of StandardSetController classes or Batch Apex, for example.

As we identified in the previous chapter, handling bulk sets of records is a common requirement. In fact, it's one that exists throughout your code paths, since DML or SOQL in a loop at any level in your code will risk hitting governor limits.

For this reason, when designing methods on the Service layer, it is appropriate that you consider list parameters by default. This encourages development of bulkified code within the method and avoids the caller having to call the Service method in a loop.

The following is an example of non-bulkified code:

RaceService.awardChampionShipPoints(Id raceId)

The following is another example of non-bulkified code:

RaceService.awardChampionShipPoints(Set<Id>raceIds)

A non-bulkified method with several parameters might look like this, for example:

RaceService.retireFromRace(Id raceId, String reason)

A bulkified version of the preceding method signature can utilize an Apex inner class as described earlier and shown in the following example in the Defining and passing data sub-section.

As discussed in the previous chapter, by default Apex code runs in system mode, meaning no sharing rules are enforced. However, business logic behavior should, in general, honor sharing rules. To avoid sharing information to which the user does not have access, sharing rule enforcement must be a concern of the Service layer.

Salesforce security review requires Apex controller class entry points to honor this, although your Service layer will be called by these classes and thus could inherit this context. Keep in mind that your Service layer is effectively an entry point for other points of access and integrations (as we will explore in a later chapter and throughout the book).

Thus the default concern of the Service layer should be to enforce sharing rules. Code implemented within the Service layer or called by it should inherit this. Code should only be elevated to running in a context where sharing rules are ignored when required, otherwise known as the without sharing context. This would be in cases where the service is working on records on behalf of the user. For example, a service might calculate or summarize some race data but some of the raw race data records (from other races) may not be visible to the user.

To enforce sharing rules by default within a Service layer the with sharing keyword is used on the class definition as follows:

public with sharing class RaceService

Other Apex classes you create, including those we will go on to discuss around the Selector and Domain patterns, should leave it unspecified such that they inherit the context. This allows them to be reused in either context more easily.

If a without sharing context is needed, a private inner class approach, as shown in the following example, can be used to temporarily elevate the execution context to process queries or DML operations in this mode:

// Class used by the Service layer
public class SomeOtherClass {

  // Work in this method inherits with sharing context from Service
  public static void someMethod { 
    // Do some work in inherited context
    // ...

    // Need to do some queries or updates in elevated context
    new ElevatedContext().restOfTheWork(workToDo);
  }

  private void restOfTheWork(List<SomeWork>workToDo) {
    // Additional work performed by this class
    // ...
  }

  private without sharingclass ElevatedContext {
    public void restOfTheWork(List<SomeWork>workToDo) {
      // Do some work in a elevated (without sharing) context
      SomeOtherClass.restOfWork(workToDo);
      }
  }

}

Note you can consider making the ability to run logic, a parameter of your Service layer if you feel certain callers will want to disable this enforcement. The preceding code sample could be adapted to conditionally execute the restOfWork method directly or via the ElevatedContext inner class in this case.

While defining data to be exchanged between the Service layer and its callers, keep in mind that the responsibility of the Service layer is to be caller-agnostic. Unless you're explicitly developing functionalities for such data formats, avoid returning information through JSON or XML strings; allow the caller (for example, a JavaScript remoting controller) to deal with these kinds of data-marshalling requirements.

As per the guidelines, using inner classes is a good way to express and scope data structures used by the service methods. The following code also illustrates a bulkified version of the multi-parameter non-bulkified method shown in the previous section.

Have a look at the following code:

public class ContestantService{

  public class RaceRetirement{
  public Id contestantId;
    public String reason;
  }

  public static void retireFromRace(List<RaceRetirement> retirements) {
    // Process race retirements... 
  }
}

Always keep in mind that the service method really only needs the minimum information to do its job, and express this through the method signature and related types so that callers can clearly see that only that information is required or returned. This avoids doubt and confusion in the calling code, which can result in it passing too little or redundant information.

The preceding example utilizes read and write member variables in the RaceRetirement class, indicating both are required. The inner class of the RaceRetirement class is only used as an input parameter to this method. Give some consideration before using an inner class such as both input and output type, since it is not always clear which member variables in such classes should be populated for the input use case or which will be populated in the output case.

However, if you find such a need for the same Apex type to be used as both an output and input parameter, and some information is not required on the input, you can consider indicating this via the Apex property syntax by making the property read-only. This prevents the caller from populating the value of a member field unnecessarily. For example, consider the following service methods in the RaceService method:

public static Map<Id, List<ProvisionalResult>>calculateProvisionalResults(Set<Id>raceIds) 
{
  // Implementation 
}

public static void applyRaceResults (Map<Id, List<ProvisionalResult>> provisionalResultsByRaceId)
{
  //Implementation
}

public class ProvisionalResult{
  public Integer racePosition {get; set;}
  public Id contestantId {get; set;}
  public String contestantName {get; private set;} 
}

While calling the calculateProvisionalResults method, the contestantName field is returned as a convenience, but is marked as read-only since it is not needed when applied in the context of the applyRaceResults method.

RaceService.awardChampionShipPoints(List<Race__c> races)

RaceService.awardChampionShipPoints(Set<Id>raceIds)

A simple expectation of the caller when calling the Service layer methods is that if there is a failure via an exception, any work done within the Service layer up until that point is rolled back. This is important as it allows the caller to handle the exception without fear of any partial data being written to the database. If there is no exception, then the data modified by the Service method can still be rolled back, but only if the entire execution context itself fails, otherwise the data is committed.

This can be implemented using a try/catch block in combination with Database.Savepoint and the rollback method, as follows:

public static void awardChampionshipPoints(Set<Id>raceIds){
  // Mark the state of the database
System.SavepointserviceSavePoint = Database.setSavePoint();
Try{
    // Do some work 
  } catch (Exception e){
    // Rollback any data written before the exception
Database.rollback(serviceSavePoint);
    // Pass the exception on for the caller to handle
    throw e;
  }
}

Later in this chapter, we will look at the Unit Of Work pattern, which helps manage the Service layer transaction management in a more elegant way than having to repeat the preceding boilerplate code in each Service method.

As your Service layer evolves, your callers may find themselves needing to call multiple Service methods at a time, which should be avoided.

To explain this, consider that a new application requirement has arose for a single custom button to update the Drivers standings (their position in the overall season) in the championship with a feature to issue a new season newsletter.

The code behind the Apex controller action method might look like the following code:

try {
  Set<Id> seasons = new Set<Id> { seasonId };
  SeasonService.updateStandings(seasons); 
  SeasonService.issueNewsLetters(seasons);
}
catch (Exception e) {
  ApexPages.addMessage(e);
}

The problem with the preceding code is that it erodes the encapsulation and thus reuses the application Service layer by putting functionality in the controller, and also breaks the transactional encapsulation.

For example, if an error occurs while issuing the newsletter, the standings are still updated (since the controller handles exceptions), and thus, if the user presses the button again, the driver standings in the championship will be updated twice!

The best way to address this type of scenario, when it occurs, is to create a new compound service, which combines the functionality into one new service method call. The following example also uses an inner class to pass the season ID and provide the issue newsletter option:

try {

  SeasonService.UpdateStandingsupdateStandings = new SeasonService.UpdateStandings();
  updateStandings.seasonId = seasonId;
  updateStandings.issueNewsletter = true;

  SeasonService.updateStandings(new List <SeasonService.UpdateStandings> { updateStandings })
}

catch (Exception e) {
  ApexPages.addMessage(e);
} 

It may be desirable to retain the original Service methods used in the first example in cases where this combined behavior is not always required.

Later in this chapter, we will see how the implementation of the preceding new Service method will reuse the original methods and thus introduce the ability for existing Service methods to be linked to each other.

Here is a useful table that summarizes the earlier guidelines: