Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Exception handling

Exception handling

This section reviews exception handling practices in Java as well as how they are handled in the Web tier, AJAX, and Elastic Path Web Services. The following exception handling tips and practices should be observed.

  • Never throw java.lang.RuntimeException or java.lang.Exception. Use a more specific exception that indicates the nature of the problem.
  • Never catch an exception just to log it and then ignore it or rethrow the same exception to a higher application layer. In the Elastic Path applications, all exceptions will be caught and logged in the web layer.
  • You may catch a checked exception, wrap it with a generic exception (see list of generic exceptions below), and throw it to a higher layer.
  • If you create a new exception in a method, remember to put it in the method declaration header. This is especially important for runtime exceptions.
  • Throw exceptions appropriate to the abstraction. In other words, exceptions thrown by a method should be defined at an abstraction level consistent with what the method does, not necessarily with the low-level details of how it is implemented.
  • Fail early; Fail loudly - If you have an error let it be thrown and don't hide it. It is better to throw it early than find out later.
  • Be sure to throw the proper type of exception, e.g. do not throw an EpDomainException in service layer code.
  • Make the exception message well versed since these messages may be exposed to end-user in the Commerce Manager or through a web service.

The following code snippet shows examples of preferred and discouraged error handling practices.

//The error handling approach in this method is discouraged.
//Objects of the wrong type are ignored, potentially hiding
//a serious error.
public int compare(Object o1, Object o2) {
    int result = 0;
    String time1 = "";
    String time2 = "";
    if (o1 instanceof String && o2 instanceof String) {
        final String time1 = (String)o1;
        final String time2 = (String)o2;
        result = Timestamp.valueOf(time1).compareTo(Timestamp.valueOf(time2));
    return result;

//This method is preferred. In this example, the code is less complex
//and passing an object of the wrong type will throw an exception,
//potentially uncovering a serious bug.
public int compare(Object o1, Object o2) {
    final String time1 = (String)o1;
    final String time2 = (String)o2;
    return Timestamp.valueOf(time1).compareTo(Timestamp.valueOf(time2));

Generic Elastic Path exceptions by layer

When a new exception type is not warranted, throw an existing exception corresponding to the application layer. The following exception types are available.

  • EpPersistenceException
  • EpServiceException
  • EpDomainException
  • EpSfWebException

Uncaught exceptions in the Web layer

A list of ordered HandlerExceptionResolver objects can be configured in the web layer with Spring MVC. Make sure the most generic one, namely, has the lowest order number. This handler will catch all uncaught exceptions in the web layer and redirect the user to the general error page where the exception is displayed.