Exception Translation

[Ivan Krizsan]

Hi!
I have an application service that receives certain exceptions from the domain layer and possibly underlying layers.
I would like to translate received exceptions to application-specific exceptions, but would prefer to separate the code that performs the translation, so that it does not make the code in the service class more difficult to understand.
Is there a way to accomplish this in Scala?
Thanks in advance!

[Ivan Krizsan]

Hi!
As at some previous occasions, I will answer my own question. I will do it with an example that uses pure Scala.
In this very simplistic example, there is one domain class that is used by an application service. In addition there is a client of the service.
The domain class is written to throw different kinds of generic exceptions:

package com.ivan.scala.exceptiontranslation.domain

import java.io.IOException

/**
 * This class implements a domain class that performs some important
 * business function that throws generic exceptions.
 * 
 * @author Ivan Krizsan
 */
class MyDomainClass {

    /**
     * Performs some domain-specific processing using the supplied message
     * and the supplied number.
     * 
     * @param inMessage Message use in processing. Must not be shorter than
     * three characters.
     * @param inNumber Number to use in processing. Must be greater than,
     * or equal to, zero.
     */
    def doSomethingWithMessageAndNumber(inMessage : String, inNumber : Integer)
    	: Unit = {
        /* Throws IllegalArgumentException if message length is too small. */
        require(inMessage.length() > 3, "message length must exceed 3 characters")
        /* Throws IllegalARgumentException if number is negative. */
        require(inNumber >= 0, "number cannot be negative")
        /* 
         * Throws AssertionError if the result of multiplying the number
         * with two is not four.
         */
        assume((inNumber * 2 != 4), "the result of doubling the number must not become 4")
        
        /* Throw IOException if no other exception were thrown. */
        throw new IOException("cannot read data")
    }
}

Then there is the application service class that calls the above domain class.

package com.ivan.scala.exceptiontranslation.services

import com.ivan.scala.exceptiontranslation.domain.MyDomainClass

/**
 * This class contains the implementation of an application service.
 * Note that only application logic is implemented in this class, no
 * exception translation.
 * 
 * @author Ivan Krizsan
 */
class MyApplicationService {

    /**
     * Performs some kind of application service using the supplied
     * string and the supplied number.
     * 
     * @param inMessage Message string.
     * @param inNumber Number.
     */
    def performApplicationService(inMessage : String, inNumber : Integer)
    	: Unit = {
        val theDomainClassInstance = new MyDomainClass()
        
        /*
         * Note that the domain class throws different kinds of generic
         * errors. We do not want those to leak out to clients of this
         * service, but want them to receive application-specific
         * exceptions.
         * In addition, we do not want to implement exception translation
         * in this class, since it would obscure the logic of the service.
         */
        theDomainClassInstance.doSomethingWithMessageAndNumber(inMessage, inNumber)
    }
}

As you can see, the service class do not contain any exception handling or translation. This is the goal of this exercise - I do not want to clutter the service class, containing application logic, with error handing, logging, exception translation etc. Despite this, I want the service to throw application-specific exceptions to clients in case of errors.

As an interlude and in order to make the example complete, here are the classes implementing the application-specific exceptions:

package com.ivan.scala.exceptiontranslation.exceptions

/**
 * Application-specific exception that indicates that a problem has
 * arisen due to an assumption being broken.
 * Typically, the exception should indicate more information about
 * what assumption that was broken.
 * 
 * @author Ivan Krizsan
 */
class AssumptionBrokenException(message : String, cause : Throwable) extends
    Exception(message, cause) {

}

package com.ivan.scala.exceptiontranslation.exceptions

/**
 * Application-specific exception that indicates that a problem has
 * arisen due to a message being too short.
 * 
 * @author Ivan Krizsan
 */
class MessageTooShortException(message : String, cause : Throwable) extends
    Exception(message, cause) {

}

package com.ivan.scala.exceptiontranslation.exceptions

/**
 * Application-specific exception that indicates that a problem has
 * arisen due to a number being too small.
 * 
 * @author Ivan Krizsan
 */
class NumberTooSmallException(message : String, cause : Throwable) extends
    Exception(message, cause) {

}

Then there is a client of the application service, which also is the starter class of this example:

package com.ivan.scala.exceptiontranslation

import com.ivan.scala.exceptiontranslation.services.MyApplicationService
import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.NumberTooSmallException
import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.AssumptionBrokenException
import java.io.IOException
//import com.ivan.scala.exceptiontranslation.services.MyApplicationServiceWithExceptionTranslation

/**
 * Application showing how to separate exception translation in
 * a service from business logic code.
 * 
 * @author Ivan Krizsan
 */
object ExceptionTranslationExample extends App {
	def service : MyApplicationService = new MyApplicationService()
	
	/* Try with a message that is too short. */
	try {
	    println("Trying with a message that is too short")
		service.performApplicationService("a", 100)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : MessageTooShortException =>
	        println("   Received a MessageTooShortException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with a number that is too small (negative). */
	try {
	    println("Trying with a number that is too small (negative)")
		service.performApplicationService("abcdef", -1)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : NumberTooSmallException =>
	        println("   Received a NumberTooSmallException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with a number that breaks an assumption. */
	try {
	    println("Trying with a number that breaks an assumption")
		service.performApplicationService("abcdef", 2)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : AssumptionBrokenException =>
	        println("   Received a AssumptionBrokenException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with an exception that should be passed through as is. */
	try {
	    println("Trying with good parameters, which should result in an exception that should be passed through")
	    service.performApplicationService("abcdef", 42)
	    println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : IOException =>
	        println("   Received IOException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
}

If we run the example program in its current incarnation, we obtain the following output:

Trying with a message that is too short
Unexpectedly received another exception :java.lang.IllegalArgumentException
Trying with a number that is too small (negative)
Unexpectedly received another exception :java.lang.IllegalArgumentException
Trying with a number that breaks an assumption
Unexpectedly received another exception :java.lang.AssertionError
Trying with good parameters, which should result in an exception that should be passed through
Received IOException as expected: cannot read data

In three of the four cases, the client received an exception that I did not want it to receive.
So, how do we fix this without adding code to the service class and use only pure Scala?
The solution I have devised uses traits. I separate all the exception translation code into the following trait:

package com.ivan.scala.exceptiontranslation.services

import java.lang.IllegalArgumentException
import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.NumberTooSmallException
import com.ivan.scala.exceptiontranslation.exceptions.AssumptionBrokenException

/**
 * This trait implements exception handling for the MyApplicationService
 * service.
 * A trait like this could be reused for different kinds of services.
 * A hierarchy of exception translation traits could be constructed where
 * a general trait contains exception translation that applies to all
 * services and child traits contain exception translation that applies to
 * groups of services or individual services.
 * 
 * @author Ivan Krizsan
 */
trait MyApplicationServiceExceptionHandling {

    /**
     * Handles exceptions arising from the method performApplicationService
     * in the MyApplicationService.
     * 
     * @param inException Exception thrown when executing the method.
     * @param inMessageParameter Message parameter to the service method.
     * @param inNumberParameter Number parameter to the service method.
     */
    def handlePerformApplicationServiceException(inException : Throwable,
        inMessageParameter : String, inNumberParameter : Integer) : Unit = {
        
    	inException match {
    	    case theException : IllegalArgumentException =>
    	        /*
    	         * Need to examine the parameters to see what went wrong.
    	         * This is a crude way to determine the cause of the error
    	         * and there is room for improving this part.
    	         */
    	        if (inMessageParameter != null && inMessageParameter.length() <= 3) {
    	            throw new MessageTooShortException(
    	                "The message '" + inMessageParameter + "' is too short",
    	                theException)
    	        }
    	        if (inNumberParameter < 0) {
    	            throw new NumberTooSmallException(
    	                "The number '" + inNumberParameter + "' is too small",
    	                theException)
    	        }
    	    
    	    case theException : AssertionError =>
    	        throw new AssumptionBrokenException(
    	            "Assumption broken: " + theException.getMessage(),
    	            theException)
    	    
    	    case theException : Throwable =>
    	        /* Pass on other exceptions. */
    	        throw theException
    	}
    }
}

To bring the above trait together with the service class, I implement a child class to the service class:

/**
 *
 */
package com.ivan.scala.exceptiontranslation.services

/**
 * A MyApplicationService service with exception translation.
 * 
 * @author Ivan Krizsan
 */
class MyApplicationServiceWithExceptionTranslation extends MyApplicationService 
	with MyApplicationServiceExceptionHandling {
    
    /**
     * Performs the application service of the original service and
     * adds exception translation in the case of any exceptions
     * arising.
     */
    override def performApplicationService(inMessage : String, inNumber : Integer)
    	: Unit = {
        try {
            /* Invoke the original service method. */
            super.performApplicationService(inMessage, inNumber)
        } catch {
            /* 
             * Catch all exceptions and let the exception translation
             * trait perform exception translation.
             */
            case theException : Throwable =>
                handlePerformApplicationServiceException(
                    theException, inMessage, inNumber)
        }
    }
}

Finally, we modify the client to instantiate the child service class instead of the original service class. Note also that I have uncommented one import:

...
import com.ivan.scala.exceptiontranslation.services.MyApplicationServiceWithExceptionTranslation

/**
 * Application showing how to separate exception translation in
 * a service from business logic code.
 * 
 * @author Ivan Krizsan
 */
object ExceptionTranslationExample extends App {
	def service : MyApplicationService = new MyApplicationServiceWithExceptionTranslation()
	
	/* Try with a message that is too short. */
...

If we now run the example program, we get the following output:

Trying with a message that is too short
Received a MessageTooShortException as expected: The message 'a' is too short
Trying with a number that is too small (negative)
Received a NumberTooSmallException as expected: The number '-1' is too small
Trying with a number that breaks an assumption
Received a AssumptionBrokenException as expected: Assumption broken: assumption failed: the result of doubling the number must not become 4
Trying with good parameters, which should result in an exception that should be passed through
Received IOException as expected: cannot read data

I succeeded in separating application logic, in the application service, and exception translation!
There is more, but interested readers need to wait for my next book to read about the details.
Best wishes!

[chris webster]

Thanks for sharing your solution, Ivan. Many of us around here are only just starting to learn Scala, so it's always good to see how other people solve problems like this.

[Ivan Krizsan]

Hi again!
I have further improved the solution I earlier posted. Changes are:

Introduce a trait as interface of the service.

Remove the service child class that mixed in the trait(s) implementing non-business concerns.

Perform mixin of the trait(s) implementing non-business concerns at service instance creation time.

Eliminated the MyApplicationServiceExceptionHandling trait.

Eliminated the class MyApplicationServiceWithExceptionTranslation.

Added a trait to perform logging (non-business concern).

Code speaks louder than words, so here is the modified example program. The domain and exception classes are the same as in the above post, so please refer to that post for implementation of those classes.

package com.ivan.scala.exceptiontranslation.services

import com.ivan.scala.exceptiontranslation.domain.MyDomainClass

/**
 * Trait defining the interface of MyApplicationService.
 * 
 * @author Ivan Krizsan
 */
trait MyApplicationServiceInterface {

  /**
   * Performs some kind of application service using the supplied
   * string and the supplied number.
   * 
   * @param inMessage Message string.
   * @param inNumber Number.
   */
  def performApplicationService(inMessage : String, inNumber : Integer) : Unit
}

package com.ivan.scala.exceptiontranslation.services

import com.ivan.scala.exceptiontranslation.domain.MyDomainClass

/**
 * This class contains the implementation of an application service.
 * Note that only application logic is implemented in this class, no
 * exception translation.
 * 
 * @author Ivan Krizsan
 */
class MyApplicationService extends MyApplicationServiceInterface {
    
    /**
   * Performs some kind of application service using the supplied
   * string and the supplied number.
   * 
   * @param inMessage Message string.
   * @param inNumber Number.
   */
  def performApplicationService(inMessage : String, inNumber : Integer)
  	: Unit = {
      val theDomainClassInstance = new MyDomainClass()
      
      /*
       * Note that the domain class throws different kinds of generic
       * errors. We do not want those to leak out to clients of this
       * service, but want them to receive application-specific
       * exceptions.
       * In addition, we do not want to implement exception translation
       * in this class, since it would obscure the logic of the service.
       */
      theDomainClassInstance.doSomethingWithMessageAndNumber(inMessage, inNumber)
  }
}

package com.ivan.scala.exceptiontranslation.services

import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.AssumptionBrokenException
import com.ivan.scala.exceptiontranslation.exceptions.NumberTooSmallException

/**
 * Trait implementing exception translation for the MyApplicationService.
 * 
 * @author Ivan Krizsan
 */
trait MyApplicationServiceExceptionTranslation extends MyApplicationServiceInterface {

    /**
     * Implements exception translation for the performApplicationService
     * method of MyApplicationService.
     * 
     * @param inMessage Message string.
     * @param inNumber Number.
     * @see MyApplicationService.performApplicationService
     */
    abstract override def performApplicationService(
        inMessage : String, inNumber : Integer) : Unit = {
        try {
            super.performApplicationService(inMessage, inNumber)
        } catch {
    	    case theException : IllegalArgumentException =>
    	        /*
    	         * Need to examine the parameters to see what went wrong.
    	         * This is a crude way to determine the cause of the error
    	         * and there is room for improving this part.
    	         */
    	        if (inMessage != null && inMessage.length() <= 3) {
    	            throw new MessageTooShortException(
    	                "The message '" + inMessage + "' is too short",
    	                theException)
    	        }
    	        if (inNumber < 0) {
    	            throw new NumberTooSmallException(
    	                "The number '" + inNumber + "' is too small",
    	                theException)
    	        }
    	    
    	    case theException : AssertionError =>
    	        throw new AssumptionBrokenException(
    	            "Assumption broken: " + theException.getMessage(),
    	            theException)
    	    
    	    case theException : Throwable =>
    	        /* Pass on other exceptions. */
    	        throw theException
        }
    }
}

package com.ivan.scala.exceptiontranslation.services

/**
 * Trait implementing logging for MyApplicationService.
 * 
 * @author Ivan Krizsan
 */
trait MyApplicationServiceLogging extends MyApplicationServiceInterface {

    /**
     * Implements logging for the performApplicationService
     * method of MyApplicationService.
     * 
     * @param inMessage Message string.
     * @param inNumber Number.
     * @see MyApplicationService.performApplicationService
     */
    abstract override def performApplicationService(
        inMessage : String, inNumber : Integer) : Unit = {
        var theThrownException : Throwable = null
        try {
            println(
                "Entering MyApplicationService.performApplicationService " +
                "with message: '" + inMessage + " and number: " + inNumber)
            super.performApplicationService(inMessage, inNumber)
            println(
                "Successfully invoked " +
                "MyApplicationService.performApplicationService " +
                "with message: '" + inMessage + " and number: " + inNumber)
        } catch {
    	    case theException : Throwable =>
    	        theThrownException = theException
    	        println("An error occurred invoking " +
    	        	"MyApplicationService.performApplicationService with " +
    	        	"message: '" + inMessage + " and number: " + inNumber)
    	        theException.printStackTrace()
        }
        
        println(
                "Exiting MyApplicationService.performApplicationService with " +
                "message: '" + inMessage + " and number: " + inNumber)
        
        /* Re-throw any exception that was thrown by the service method. */
        if (theThrownException != null) {
            throw theThrownException
        }
    }
}

package com.ivan.scala.exceptiontranslation

import com.ivan.scala.exceptiontranslation.services.MyApplicationService
import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.NumberTooSmallException
import com.ivan.scala.exceptiontranslation.exceptions.MessageTooShortException
import com.ivan.scala.exceptiontranslation.exceptions.AssumptionBrokenException
import java.io.IOException
import com.ivan.scala.exceptiontranslation.services.MyApplicationServiceWithExceptionTranslation
import com.ivan.scala.exceptiontranslation.services.MyApplicationServiceExceptionTranslation
import com.ivan.scala.exceptiontranslation.services.MyApplicationServiceLogging

/**
 * Application showing how to separate exception translation in
 * a service from business logic code.
 * 
 * @author Ivan Krizsan
 */
object ExceptionTranslationExample extends App {
	def service : MyApplicationService =
	    new MyApplicationService() with
	    	MyApplicationServiceExceptionTranslation with
	    	MyApplicationServiceLogging
	
	/* Try with a message that is too short. */
	try {
	    println("Trying with a message that is too short")
		service.performApplicationService("a", 100)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : MessageTooShortException =>
	        println("   Received a MessageTooShortException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with a number that is too small (negative). */
	try {
	    println("Trying with a number that is too small (negative)")
		service.performApplicationService("abcdef", -1)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : NumberTooSmallException =>
	        println("   Received a NumberTooSmallException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with a number that breaks an assumption. */
	try {
	    println("Trying with a number that breaks an assumption")
		service.performApplicationService("abcdef", 2)
		println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : AssumptionBrokenException =>
	        println("   Received a AssumptionBrokenException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
	
	/* Try with an exception that should be passed through as is. */
	try {
	    println("Trying with good parameters, which should result in an exception that should be passed through")
	    service.performApplicationService("abcdef", 42)
	    println("   Unexpectedly did not receive any exception.")
	} catch {
	    case theException : IOException =>
	        println("   Received IOException as expected: " +
	            theException.getMessage())
	    case theException : Throwable =>
	        println("   Unexpectedly received another exception :" +
	            theException.getClass().getCanonicalName())
	}
}

Note that the order in which the traits are mixed in is significant. Try experimenting with the logging trait first and look at the exceptions logged.
I feel that this new solution is more elegant than the previous one. One possible drawback may be that it will be difficult to re-use traits implementing non-business concerns with different services.
Best wishes!