Spring SOAP Fault Handling

Introduction

When developing SOAP web services with Spring, proper error handling is crucial for creating robust applications. SOAP faults provide a standardized way to communicate errors back to clients, enabling them to understand what went wrong and respond accordingly.

In this tutorial, we'll explore how to implement effective SOAP fault handling in Spring Web Services. You'll learn how to create custom fault definitions, throw SOAP faults from your endpoint methods, and configure fault message resolvers to properly translate exceptions into well-structured SOAP fault responses.

Understanding SOAP Faults

A SOAP fault is a specific message structure that contains error information. According to the SOAP specification, a fault consists of the following elements:

Fault Code: A code for identifying the error
Fault String: A human-readable explanation of the error
Fault Actor: Information about who caused the fault (optional)
Detail: Application-specific error information (optional)

In SOAP 1.2, these elements are slightly renamed and reorganized, but the concept remains the same.

Here's a simple example of what a SOAP fault looks like:

xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Account not found</faultstring>
         <detail>
            <error:AccountError xmlns:error="http://example.com/errors">
               <error:id>12345</error:id>
               <error:message>Could not find account with ID 12345</error:message>
            </error:AccountError>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Spring WS Fault Handling Approach

Spring Web Services provides several ways to handle exceptions and convert them into SOAP faults:

Exception handling in endpoints: Throwing specific exceptions in your endpoint methods
SoapFaultMappingExceptionResolver: Maps specific exception types to SOAP faults
SoapFaultAnnotationExceptionResolver: Uses annotations to define SOAP fault details
Custom exception resolvers: Creating your own implementation of SoapFaultExceptionResolver

Let's explore each approach with examples.

Basic SOAP Fault Handling

The simplest way to return a SOAP fault is by throwing a SoapFaultClientException or SoapFaultServerException from your endpoint method.

Example: Throwing a Simple SOAP Fault

java
import org.springframework.ws.soap.SoapFaultException;
import org.springframework.ws.soap.server.endpoint.annotation.Endpoint;
import org.springframework.ws.soap.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.soap.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.soap.server.endpoint.annotation.ResponsePayload;
import org.springframework.ws.soap.SoapFault;

@Endpoint
public class AccountEndpoint {
    
    private static final String NAMESPACE_URI = "http://example.com/account";
    
    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "GetAccountRequest")
    @ResponsePayload
    public GetAccountResponse getAccount(@RequestPayload GetAccountRequest request) {
        String accountId = request.getAccountId();
        
        if (accountId == null || accountId.isEmpty()) {
            throw new SoapFaultException("Account ID cannot be empty");
        }
        
        // Process the request and return response
        GetAccountResponse response = new GetAccountResponse();
        // ...
        return response;
    }
}

This approach is straightforward but limited in terms of customization. For more advanced fault handling, we need to use Spring's exception resolvers.

Using SoapFault Class

For more control over the SOAP fault structure, you can use the SoapFault interface along with SoapFaultException:

java
import org.springframework.ws.soap.SoapFaultException;
import org.springframework.ws.soap.SoapFault;
import org.springframework.ws.soap.server.endpoint.annotation.Endpoint;
import org.springframework.ws.soap.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.soap.SoapMessageFactory;
import org.springframework.ws.soap.SoapVersion;

@Endpoint
public class ProductEndpoint {

    private final SoapMessageFactory messageFactory;

    public ProductEndpoint(SoapMessageFactory messageFactory) {
        this.messageFactory = messageFactory;
    }

    @PayloadRoot(namespace = "http://example.com/products", localPart = "GetProductRequest")
    public GetProductResponse getProduct(GetProductRequest request) {
        String productId = request.getProductId();
        
        if (productId == null || productId.isEmpty()) {
            SoapMessage message = messageFactory.createWebServiceMessage();
            SoapBody body = message.getSoapBody();
            SoapFault fault = body.addClientOrSenderFault("Invalid product ID", Locale.ENGLISH);
            
            // Add fault detail
            SoapFaultDetail detail = fault.addFaultDetail();
            detail.addFaultDetailElement(new QName("http://example.com/errors", "ProductError"))
                  .addText("Product ID cannot be empty");
            
            throw new SoapFaultException(fault);
        }
        
        // Normal processing...
        return new GetProductResponse();
    }
}

Implementing SoapFaultMappingExceptionResolver

For a more structured approach to error handling, you can configure a SoapFaultMappingExceptionResolver bean that maps exceptions to SOAP faults:

java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.ws.soap.server.endpoint.SoapFaultMappingExceptionResolver;
import org.springframework.ws.soap.server.endpoint.SoapFaultDefinition;
import org.springframework.ws.soap.SoapFault;

import java.util.Properties;

@Configuration
public class WebServiceConfig {

    @Bean
    public SoapFaultMappingExceptionResolver exceptionResolver() {
        SoapFaultMappingExceptionResolver resolver = new SoapFaultMappingExceptionResolver();
        
        // Define default fault
        SoapFaultDefinition defaultFault = new SoapFaultDefinition();
        defaultFault.setFaultCode(SoapFaultDefinition.SERVER);
        defaultFault.setFaultStringOrReason("Server error");
        resolver.setDefaultFault(defaultFault);
        
        // Map specific exceptions to specific faults
        Properties errorMappings = new Properties();
        errorMappings.setProperty(AccountNotFoundException.class.getName(), 
                                 SoapFaultDefinition.CLIENT + ",Account not found");
        errorMappings.setProperty(InvalidInputException.class.getName(), 
                                 SoapFaultDefinition.CLIENT + ",Invalid input provided");
        resolver.setExceptionMappings(errorMappings);
        
        // Set order for multiple resolvers
        resolver.setOrder(1);
        
        return resolver;
    }
}

Now, when your endpoint throws specific exceptions, they will be automatically converted to appropriate SOAP faults:

java
@Endpoint
public class AccountEndpoint {
    
    @PayloadRoot(namespace = "http://example.com/account", localPart = "GetAccountRequest")
    @ResponsePayload
    public GetAccountResponse getAccount(@RequestPayload GetAccountRequest request) {
        String accountId = request.getAccountId();
        
        if (accountId == null || accountId.isEmpty()) {
            throw new InvalidInputException("Account ID cannot be empty");
        }
        
        Account account = accountRepository.findById(accountId);
        if (account == null) {
            throw new AccountNotFoundException("Account with ID " + accountId + " not found");
        }
        
        // Process the request and return response
        GetAccountResponse response = new GetAccountResponse();
        // ...
        return response;
    }
}

Custom Exception Classes

Let's define our custom exception classes that will be used with the exception resolver:

java
public class AccountNotFoundException extends RuntimeException {
    public AccountNotFoundException(String message) {
        super(message);
    }
}

public class InvalidInputException extends RuntimeException {
    public InvalidInputException(String message) {
        super(message);
    }
}

Using DetailSoapFaultDefinitionExceptionResolver

For more detailed fault information, you can use the DetailSoapFaultDefinitionExceptionResolver which allows adding custom XML to the fault detail section:

java
import javax.xml.namespace.QName;
import org.springframework.ws.soap.SoapFault;
import org.springframework.ws.soap.server.endpoint.SoapFaultDefinition;
import org.springframework.ws.soap.server.endpoint.SoapFaultMappingExceptionResolver;

public class DetailSoapFaultDefinitionExceptionResolver extends SoapFaultMappingExceptionResolver {

    @Override
    protected void customizeFault(Object endpoint, Exception ex, SoapFault fault) {
        if (ex instanceof AccountNotFoundException) {
            SoapFaultDetail detail = fault.addFaultDetail();
            detail.addFaultDetailElement(new QName("http://example.com/errors", "AccountError"))
                  .addText("Account could not be found in the system");
        } else if (ex instanceof InvalidInputException) {
            SoapFaultDetail detail = fault.addFaultDetail();
            detail.addFaultDetailElement(new QName("http://example.com/errors", "ValidationError"))
                  .addText("Input validation failed: " + ex.getMessage());
        }
    }
}

Then configure this resolver in your application:

java
@Bean
public DetailSoapFaultDefinitionExceptionResolver detailExceptionResolver() {
    DetailSoapFaultDefinitionExceptionResolver resolver = new DetailSoapFaultDefinitionExceptionResolver();
    
    // Define default fault
    SoapFaultDefinition defaultFault = new SoapFaultDefinition();
    defaultFault.setFaultCode(SoapFaultDefinition.SERVER);
    defaultFault.setFaultStringOrReason("Server error");
    resolver.setDefaultFault(defaultFault);
    
    // Map specific exceptions to specific faults
    Properties errorMappings = new Properties();
    errorMappings.setProperty(AccountNotFoundException.class.getName(), 
                             SoapFaultDefinition.CLIENT + ",Account not found");
    errorMappings.setProperty(InvalidInputException.class.getName(), 
                             SoapFaultDefinition.CLIENT + ",Invalid input provided");
    resolver.setExceptionMappings(errorMappings);
    
    resolver.setOrder(0);  // Higher priority than the standard resolver
    
    return resolver;
}

Using @SoapFault Annotation

Spring Web Services also provides a convenient annotation-based approach to defining SOAP faults. Configure the resolver:

java
@Bean
public SoapFaultAnnotationExceptionResolver annotationExceptionResolver() {
    SoapFaultAnnotationExceptionResolver resolver = new SoapFaultAnnotationExceptionResolver();
    resolver.setOrder(2);  // Lower priority than the other resolvers
    return resolver;
}

Then use the @SoapFault annotation on your exception classes:

java
import org.springframework.ws.soap.server.endpoint.annotation.SoapFault;
import org.springframework.ws.soap.SoapFaultDefinition;

@SoapFault(faultCode = SoapFaultDefinition.CLIENT,
           faultStringOrReason = "Account could not be found")
public class AccountNotFoundException extends RuntimeException {
    public AccountNotFoundException(String message) {
        super(message);
    }
}

@SoapFault(faultCode = SoapFaultDefinition.CLIENT,
           faultStringOrReason = "Input validation failed")
public class InvalidInputException extends RuntimeException {
    public InvalidInputException(String message) {
        super(message);
    }
}

Testing SOAP Fault Handling

Let's see how to test your SOAP fault handling with a simple unit test:

java
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;
import org.springframework.ws.test.server.MockWebServiceClient;
import org.springframework.xml.transform.StringSource;

import static org.springframework.ws.test.server.RequestCreators.*;
import static org.springframework.ws.test.server.ResponseMatchers.*;

@SpringBootTest
public class AccountEndpointTest {

    @Autowired
    private ApplicationContext applicationContext;

    private MockWebServiceClient mockClient;

    @BeforeEach
    public void setUp() {
        mockClient = MockWebServiceClient.createClient(applicationContext);
    }

    @Test
    public void testGetAccountWithInvalidId() {
        // Create a request with an empty account ID
        String request = 
            "<acc:GetAccountRequest xmlns:acc='http://example.com/account'>" +
            "  <acc:accountId></acc:accountId>" +
            "</acc:GetAccountRequest>";

        // Verify that we get a SOAP fault with the expected values
        mockClient
            .sendRequest(withPayload(new StringSource(request)))
            .andExpect(serverOrReceiverFault("Invalid input provided"))
            .andExpect(xpath("//faultstring").evaluatesTo("Invalid input provided"));
    }

    @Test
    public void testGetAccountWithNonExistentId() {
        // Create a request with a non-existent account ID
        String request = 
            "<acc:GetAccountRequest xmlns:acc='http://example.com/account'>" +
            "  <acc:accountId>999999</acc:accountId>" +
            "</acc:GetAccountRequest>";

        // Verify that we get a SOAP fault with the expected values
        mockClient
            .sendRequest(withPayload(new StringSource(request)))
            .andExpect(clientOrSenderFault("Account not found"))
            .andExpect(xpath("//detail/err:AccountError")
                .namespaceContext(createNsContext())
                .exists());
    }
    
    private SimpleNamespaceContext createNsContext() {
        SimpleNamespaceContext nsContext = new SimpleNamespaceContext();
        nsContext.bindNamespaceUri("err", "http://example.com/errors");
        return nsContext;
    }
}

Real-world Example: Banking Web Service

Let's look at a more comprehensive example for a banking system web service:

java
@Endpoint
public class BankingEndpoint {
    
    private static final String NAMESPACE_URI = "http://example.com/banking";
    private final AccountService accountService;
    
    public BankingEndpoint(AccountService accountService) {
        this.accountService = accountService;
    }
    
    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "FundTransferRequest")
    @ResponsePayload
    public FundTransferResponse transferFunds(@RequestPayload FundTransferRequest request) {
        // Validate input
        if (request.getSourceAccountId() == null || request.getTargetAccountId() == null) {
            throw new InvalidInputException("Source and target account IDs must be provided");
        }
        
        if (request.getAmount() <= 0) {
            throw new InvalidInputException("Transfer amount must be positive");
        }
        
        try {
            // Process transfer
            TransferResult result = accountService.transferFunds(
                request.getSourceAccountId(),
                request.getTargetAccountId(),
                request.getAmount()
            );
            
            // Create response
            FundTransferResponse response = new FundTransferResponse();
            response.setTransactionId(result.getTransactionId());
            response.setStatus(result.isSuccessful() ? "SUCCESS" : "FAILED");
            response.setMessage(result.getMessage());
            return response;
            
        } catch (InsufficientFundsException e) {
            throw new TransactionException("Insufficient funds for transfer", e);
        } catch (AccountNotFoundException e) {
            throw e; // Already handled by our configured resolver
        } catch (Exception e) {
            // Unexpected errors become server faults
            throw new ServerProcessingException("Unable to process transaction", e);
        }
    }
}

And define the appropriate exception classes:

java
@SoapFault(faultCode = SoapFaultDefinition.CLIENT, 
           faultStringOrReason = "Transaction could not be completed")
public class TransactionException extends RuntimeException {
    public TransactionException(String message, Throwable cause) {
        super(message, cause);
    }
}

@SoapFault(faultCode = SoapFaultDefinition.SERVER, 
           faultStringOrReason = "Internal server error")
public class ServerProcessingException extends RuntimeException {
    public ServerProcessingException(String message, Throwable cause) {
        super(message, cause);
    }
}

Best Practices for SOAP Fault Handling

Be specific: Create distinct exception types for different error scenarios.
Don't expose sensitive information: Be careful not to include sensitive data in fault messages.
Use appropriate fault codes: Use client faults (4xx) for client errors and server faults (5xx) for server-side issues.
Include actionable information: Provide information that helps clients understand and potentially resolve the issue.
Structure detail information: Organize fault details in a way that clients can programmatically process.
Document your faults: Include information about possible faults in your WSDL or documentation.
Log detailed errors: While the client gets a sanitized fault message, log detailed error information server-side.
Use consistent error handling: Ensure consistent fault generation across your application.

Summary

In this tutorial, you learned how to implement effective SOAP fault handling in Spring Web Services using various approaches:

Simple SoapFaultException throwing
Using the SoapFault interface for more control
Configuring SoapFaultMappingExceptionResolver to map exceptions to faults
Creating custom exception resolvers for detailed fault information
Using annotations to define fault behavior
Testing your fault handling logic

Proper SOAP fault handling is essential for creating robust and user-friendly web services. By following the patterns outlined in this tutorial, you can provide clear error information to clients while maintaining security and following SOAP standards.

Additional Resources

Exercises

Create a custom exception resolver that adds timestamp information to all SOAP faults.
Implement a web service endpoint that validates a complex object and returns appropriate SOAP faults for different validation failures.
Write tests for your SOAP fault handling using MockWebServiceClient.
Extend the banking example with additional operations and appropriate fault handling.
Create a client that consumes your web service and properly handles the various faults that can be returned.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

Understanding SOAP Faults​

Spring WS Fault Handling Approach​

Basic SOAP Fault Handling​

Example: Throwing a Simple SOAP Fault​

Using SoapFault Class​

Implementing SoapFaultMappingExceptionResolver​

Custom Exception Classes​

Using DetailSoapFaultDefinitionExceptionResolver​

Using @SoapFault Annotation​

Testing SOAP Fault Handling​

Real-world Example: Banking Web Service​

Best Practices for SOAP Fault Handling​

Summary​

Additional Resources​

Exercises​