In a project I’m currently working on we’re using LiveCycle Data Services to expose Java back-end services to a Flex client application. The back-end is structured in several layers using some flavors of Spring “glue”. You can see below the basic building blocks of the back-end :

As you can see, the architecture is quite simple. We have a layer of service API which is implemented by another layer, a LCDS-based implementation which, in turn, uses an implementation of a DAO layer. In the diagram, I grayed out the DAO layers because they are of no interest to our current subject.
Briefly, the service API only contains the interfaces of the services along with related objects : exceptions and DTOs.

We use our custom business exceptions to signal to service clients any issues encountered during service operations. Each custom exception has a public code which indicates its nature and meaning.

Simple exception mechanism

At first, we decided to simply throw business exceptions from the service implementations. This meant that the Flex client application would receive a fault event, which it had to strip to get to the actual exception.
Here is the Java service exception and method :

public class InvalidCriteriaException extends Exception
{
    ...
    public String getCode()
    {
        return ExceptionCode.INVALID_CRITERIA.toString();
    }
}
 
public SearchResultDto searchById(SearchCriteriaDto criteria) throws InvalidCriteriaException
{
    try {
        // do some processing, use the DAO layer
        ...
    }
    catch (SomeDaoException e)
    {
        // convert the DAO exception into a service exception and then throw the new exception
        ...
    }
    catch (Throwable e)
    {
        // any unexpected exception is caught and a new service exception is created and thrown further
        ...
    }
}

And the corresponding Flex code :

    private function handleException(event:FaultEvent) : void {
        var errorMessage:ErrorMessage = event.message as ErrorMessage;
        Alert.show(errorMessage.rootCause.code);
    }

As you can see, the Java service code is cluttered within a try..catch block, which also contains the details on converting possible exceptions to service exceptions. On top of this, the client-side code is not very clean either, because it uses an untyped object ( rootCause ) on which we make assumptions and assumptions are generally a bad thing to do in your code. The right solution on the client-side would be to take advantage of the properties of the ErrorMessage object.

A better exception mechanism

In order to leverage the properties of the Flex class ErrorMessage, we decided to only throw instances of flex.messaging.MessageException, which is shipped in LCDS (and BlazeDS). To do this in an easy way, we proceeded in making sure that each of our custom exception would inherit MessageException :

public class InvalidCriteriaException extends MessageException
{
    ...
}

The service layer would now throw only MessageException-derived exceptions, which get deserialized on the client-side as instances of ErrorMessage. The Java exception has a field called code, who is translated in the Flex class as the field faultCode. So the only thing left to do is make sure that the code field is set to a proper value on the server side.

Using Spring BlazeDS Integration and a custom exception translator

The solution described in the previous paragraph still comes with some flaws. First of all, we didn’t get rid of the try..catch block in the service code. Uh, ugly.
Second, there is a design issue : the service API layer is exposing the service interfaces along with the exceptions, which are now derived from a LCDS exception. This makes the service API layer dependent on LCDS, which is not what we want. The service API should be clean and free of any implementation-specific dependencies.

These flaws were removed once we switched to using the Spring BlazeDS Integration to expose our Spring-based services as LCDS destinations. Along with other great features, Spring BlazeDS Integration comes with the notion of custom exception translators. The translator makes sure that exceptions thrown from the Spring-exposed LCDS destinations are converted to meaningful exceptions for the client, all of this far away from the service code which will be far more simple and clean.

First of all, we create our own exception translator :

public class ExceptionTranslatorImpl implements ExceptionTranslator
{
    public boolean handles(final Class<?> clazz)
    {
        return Boolean.TRUE;
    }
 
    public MessageException translate(final Throwable throwable)
    {
        final MessageException exception = new MessageException();
        exception.setCode(ExceptionCode.SYSTEM.name());
 
        if (throwable != null)
        {
            if (throwable instanceof BaseCustomException)
            {
                exception.setCode(((BaseCustomException) throwable).getCode().name());
            }
 
            exception.setRootCause(throwable);
            exception.setMessage(throwable.getMessage());
        }
 
        return exception;
    }
}

Then we need to register it in the application context :

  	<bean id="allExceptionTranslator" class="com.adobe.myproject.exception.ExceptionTranslatorImpl" />
 
	 <flex:message-broker services-config-path="/WEB-INF/flex/services-config.xml"  >
        <flex:exception-translator ref="allExceptionTranslator"/>
		<flex:message-service/>
		<flex:secured />
	</flex:message-broker>

We can now remove all the exception conversion logic from the service code and let the exception translator handle all of these ugly details for us. Much better, isn’t it ?