Table of Contents

(4) Implementation of Custom Basic Steps

(I) Complete Steps Requirements

（2）Registration Method Explanation

Through Spring Boot’s spring.factories File (Recommended Method)

Manually register in the startup class (Not recommended)

Five. Practical Custom Example

Six, Some Suggestions

Seven, Conclusion

---

Valuable insights shared, thank you for reading!

In the world of programmers, errors are like the neighbor’s dog, always barking in your code as if to say, “Hey, look at me, I’m here again!” When you elegantly finish writing a piece of code and press Enter with great anticipation, suddenly an unexpected exception pops up. It feels like opening the door to find a big black dog—startling and frightening!

However, don’t worry. Today’s “FailureAnalyzer” is like an experienced vet, specifically diagnosing problems for your code and taming those unexpected errors that drop in uninvited! Not only can it identify where the issues lie, but it also provides corresponding solutions, bringing your code back to life, as lively as a cheerful puppy wagging its tail towards a bright future!

In this article, we’ll explore the secrets of FailureAnalyzer together, learning how to customize it for those stubborn errors. Ready? Let’s put on our “programmer’s safety glasses” and embark on this challenging and fun adventure!

1. Getting to Know FailureAnalyzer

Imagine you’re developing a network application based on Spring Boot. You’ve written a bunch of code, made various configurations, and finally can’t wait to start your application to see if it runs as you expected.

You excitedly run the startup command, but suddenly, the console displays a stack of red error messages. For example:

You will immediately notice that this error originates from LoggingFailureAnalysisReporter, which is essentially the troubleshooting tool known as FailureAnalyzer within Spring Boot. You decide to give it a try and see if it can help resolve your issue.

You should feel surprised and excited because FailureAnalyzer not only identifies the problem but also provides a solution: by implementing the suggested configuration fixes and restarting the application, everything runs smoothly this time.

Through this simple scenario, you instantly recognize the value and magic of FailureAnalyzer. It functions like an insurance policy for your application startup, enabling you to quickly find solutions when problems arise, thereby making your development process more seamless and efficient.

II. How It Works in Spring Boot

Spring Boot already includes some FailureAnalyzer configurations in the spring.factories file (located in the META-INF directory). Implementations of FailureAnalyzer are typically declared in the spring.factories file so they can be automatically discovered and registered by Spring Boot during application startup.

org.springframework.boot.diagnostics.FailureAnalyzer=\
org.springframework.boot.autoconfigure.jdbc.DataSourceFailedAnalyzer,\
org.springframework.boot.autoconfigure.jms.activemq.ActiveMQConnectFailureAnalyzer,\
org.springframework.boot.autoconfigure.jms.artemis.ArtemisJmsConnectionFailureAnalyzer,\
org.springframework.boot.autoconfigure.jms.hornetq.HornetQConnectFailureAnalyzer,\
org.springframework.boot.autoconfigure.jms.hornetq.HornetQDependencyExceptionAnalyzer,\
org.springframework.boot.autoconfigure.solr.SolrExceptionAnalyzer,\
org.springframework.boot.autoconfigure.web.servlet.DispatcherServletRegistrationBeanNotAvailableAnalyzer,\
org.springframework.boot.cloud.CloudPlatformConnectorsFailureAnalyzer,\
org.springframework.boot.cloud.CloudFoundryVcapEnvironmentPostProcessorFailureAnalyzer,\
org.springframework.boot.context.properties.ConfigurationPropertiesBindingPostProcessorChecker,\
org.springframework.boot.devtools.autoconfigure.DevToolsMissingFilterFailureAnalyzer,\
org.springframework.boot.devtools.autoconfigure.LocalDevToolsAutoConfiguration$LocalDevToolsFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.NoSuchBeanDefinitionFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.NoUniqueBeanDefinitionFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.BeanCurrentlyInCreationFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.BeanDefinitionOverrideAnalyzer,\
org.springframework.boot.diagnostics.analyzer.IllegalComponentScanFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.InvalidConfigurationPropertyNameFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.InvalidConfigurationPropertyValueFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.InvalidEmbeddedServletContainerConfigurationFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.InvalidTemplateAvailabilityProviderAnalyzer,\
org.springframework.boot.diagnostics.analyzer.NonCompatibleConfigurationClassFailureAnalyzer,\
org.springframework.boot.diagnostics.analyzer.SingleConstructorInjectionAnalyzer

When the application fails to start, Spring Boot will automatically trigger this mechanism, attempting to identify and handle the reasons for the failed startup, and provide useful diagnostic information and solutions.

Three、Why Might You Need to Customize FailureAnalyzer

Of course, if necessary, we can customize the FailureAnalyzer to handle application startup failures more flexibly, provide more precise fault diagnosis and solutions, especially for those working on infrastructure.

Reasons	Description
Handling Specific Error Scenarios	The default FailureAnalyzer cannot accurately identify or handle specific error scenarios. By customizing, you can write tailored diagnostic logic for these specific errors, providing more precise fault diagnosis and solutions.
Additional Diagnostic Information	The default FailureAnalyzer only provides basic diagnostic information. In some cases, more detailed information may be needed to accurately diagnose issues. Customization allows adding extra diagnostic logic to collect more useful information for better understanding of the problem.
Integration with External Systems	If the application integrates with external systems, startup failures may be caused by issues during interaction with these systems. Customization enables additional logic such as calling external APIs or checking external system status to diagnose and resolve issues related to external systems.
Customized Solutions	Some errors require specific solutions. Customization allows providing tailored solutions based on the application’s specific needs or constraints, better meeting the application’s requirements.

Four、Implementing Custom Basic Steps

（One）Complete step requirements

To implement a custom FailureAnalyzer, we need to complete the following steps:

1. Define custom exceptions and create check requirements.
2. Create a class that implements the AbstractFailureAnalyzer interface and override the analyze() method to analyze exceptions and return a FailureAnalysis object.
3. Register the custom FailureAnalyzer class with the Spring Boot application.

Note that in a Spring Boot application, multiple custom failure analyzers do not have a fixed order of implementation. When the application starts, Spring Boot automatically scans and registers all failure analyzers, then invokes them based on the order of their class names. This means that regardless of how you organize or write your failure analyzer classes, they will be registered simultaneously when the application starts and there is no predefined order.

（

1. Create a file named META-INF/spring.factories in the src/main/resources directory (skip this step if it already exists).
2. Add the custom FailureAnalyzer class for implementation to the spring.factories file, following the same format as shown in the example.

Manually Registering in the Main Application Class

To manually register the FailureAnalyzer in your Spring Boot application’s main class annotated with @SpringBootApplication:

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(ZYFApplication.class);
        application.addListeners(new ConfigFileFailureAnalyzer());
        application.run(args);
    }

Subsequent examples will be listed, but the situation should be based on actual project requirements. I usually follow the above suggestions for registration.

Next, create a checker class to perform basic checks on the required system files and return information about missing configuration files:

package org.zyf.javabasic.spring.failureanalyzer.checker;
import com.google.common.collect.Lists;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ResourceLoader;
import org.springframework.stereotype.Component;
import org.zyf.javabasic.spring.failureanalyzer.exception.ConfigFileNotFoundException;
import javax.annotation.PostConstruct;
import java.util.List;
/**
* @project: zyfboot-javabasic
* @description: This component checks for essential configuration files required by the system
* @author: zhangyanfeng
* @create: 2024-05-02 18:14
**/
@Component
public class ConfigFileNotFoundChecker {
private final ResourceLoader resourceLoader;
public ConfigFileNotFoundChecker(ResourceLoader resourceLoader) {
this.resourceLoader = resourceLoader;
}
public boolean exists(String fileName) {
Resource resource = resourceLoader.getResource("classpath:" + fileName);
return resource.exists();
}
@PostConstruct
public void checkConfigFiles() throws ConfigFileNotFoundException {
// List of files to be checked
List<String> filesToCheck = Lists.newArrayList();
filesToCheck.add("application.yml");
filesToCheck.add("zyf_application_context.xml");
filesToCheck.add("report-config.xml");
filesToCheck.add("urlzyf.properties");
// List of missing files
List<String> notFoundFiles = Lists.newArrayList();
// Check each file for existence
for (String fileName : filesToCheck) {
if (!exists(fileName)) {
notFoundFiles.add(fileName);
}
}
// If any files are missing, throw an exception
if (!notFoundFiles.isEmpty()) {
throw new ConfigFileNotFoundException(notFoundFiles.toString());
}
}
}

Next create and implement AbstractFailureAnalyzer, override analyze() method as follows:

package org.zyf.javabasic.spring.failureanalyzer.analyzer;
import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;
import org.zyf.javabasic.spring.failureanalyzer.exception.ConfigFileNotFoundException;
import org.zyf.javabasic.spring.failureanalyzer.exception.RequiredPropertyException;
/**
* @program: zyfboot-javabasic
* @description: Check if necessary files exist exception
* @author: zhangyanfeng
* @create: 2024-05-02 18:26
**/
public class ZYFConfigFileFailureAnalyzer extends AbstractFailureAnalyzer<ConfigFileNotFoundException> {
@Override
protected FailureAnalysis analyze(Throwable rootFailure, ConfigFileNotFoundException cause) {
String description = description(cause);
String action = action(cause);
return new FailureAnalysis(description, action, cause);
}
private String description(ConfigFileNotFoundException ex) {
return String.format("Failed to load configuration file '%s'.", ex.getFileNames());
}
private String action(ConfigFileNotFoundException ex) {
return String.format("Check if the configuration file:'%s' exists.", ex.getFileNames());
}
}

spring.factories

Define a basic configuration error message of this type as follows:

package org.zyf.javabasic.spring.failureanalyzer.model;
/**
* @program: zyfboot-javabasic
* @description: Indicates different error types, such as missing required properties, property value format errors, etc.
* @author: zhangyanfeng
* @create: 2024-05-02 19:57
**/
public class ConfigFileFormatErrorInfo {
private final boolean fileNotFound;
private final ErrorType errorType;
private final String fileName;
public ConfigFileFormatErrorInfo(boolean fileNotFound, ErrorType errorType, String fileName) {
this.fileNotFound = fileNotFound;
this.errorType = errorType;
this.fileName = fileName;
}
public boolean isFileNotFound() {
return fileNotFound;
}
public ErrorType getErrorType() {
return errorType;
}
public String getFileName() {
return fileName;
}
public DescriptionAndAction getDescriptionAndAction() {
String description;
String action;
if (fileNotFound) {
description = "Configuration file '" + fileName + "' not found";
action = "Check if the configuration file exists.";
} else {
switch (errorType) {
case MISSING_PROPERTY:
description = "Missing required property in configuration file '" + fileName + "'";
action = "Ensure all required properties are provided in the configuration file.";
break;
case INVALID_VALUE:
description = "Invalid value for property in configuration file '" + fileName + "'";
action = "Correct the value of the property in the configuration file.";
break;
case OTHER:
default:
description = "Other configuration file format error in file '" + fileName + "'";
action = "Review the configuration file for formatting issues.";
break;
}
}
return new DescriptionAndAction(description, action);
}
public enum ErrorType {
MISSING_PROPERTY,
INVALID_VALUE,
OTHER
}
}
package org.zyf.javabasic.spring.failureanalyzer.model;
/**
* @program: zyfboot-javabasic
* @description: DescriptionAndAction
* @author: zhangyanfeng
* @create: 2024-05-02 20:19
**/
public class DescriptionAndAction {
private final String description;
private final String action;
public DescriptionAndAction(String description, String action) {
this.description = description;
this.action = action;
}
public String getDescription() {
return description;
}
public String getAction() {
return action;
}
}

Then define the basic exception information as follows:

package org.zyf.javabasic.spring.failureanalyzer.exception;
import com.alibaba.fastjson.JSON;
import org.zyf.javabasic.spring.failureanalyzer.model.ConfigFileFormatErrorInfo;
/**
* @program: zyfboot-javabasic
* @description: configuration file format error exception
* @author: zhangyanfeng
* @create: 2024-05-02 19:23
**/
public class ConfigFileFormatException extends RuntimeException {
private final ConfigFileFormatErrorInfo errorInfo;
public ConfigFileFormatException(ConfigFileFormatErrorInfo errorInfo) {
super("Configuration file format error: " + JSON.toJSONString(errorInfo));
this.errorInfo = errorInfo;
}
public ConfigFileFormatErrorInfo getErrorInfo() {
return errorInfo;
}
}

Check if the specified configuration file (report-config.xml) meets the expected format requirements:

1. Must contain a Bean definition named "dataSource" for configuring database connection information.
2. The "dataSource" Bean must include the following properties:driverClassName: Database driver class name;url: Database connection URL;username: Database username;password: Database password.
3. The password property must be encrypted, i.e., it starts with a specific string.
4. Must contain a Bean definition named "reportGenerator" for configuring the report generator.
5. The "reportGenerator" Bean must include a property named dataSource that references the previously defined "dataSource" Bean.

If the configuration file does not meet one of the above requirements, an appropriate exception will be thrown to indicate a configuration format error. The specific implementation for each check is as follows:

package org.zyf.javabasic.spring.failureanalyzer.checker;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ResourceLoader;
import org.springframework.stereotype.Component;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.xml.sax.InputSource;
import org.zyf.javabasic.spring.failureanalyzer.exception.ConfigFileFormatException;
import org.zyf.javabasic.spring.failureanalyzer.model.ConfigFileFormatErrorInfo;
import javax.annotation.PostConstruct;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import java.io.InputStream;
import static org.zyf.javabasic.spring.failureanalyzer.model.ConfigFileFormatErrorInfo.ErrorType.*;
/**
* @program: zyfboot-javabasic
* @description: Specifies the validation logic for configuration files
* @author: zhangyanfeng
* @create: 2024-05-02 20:12
**/
@Component
public class ConfigFileFormatChecker {
@Autowired
private ResourceLoader resourceLoader;
@PostConstruct
public void checkConfigFileFormat() {
String fileName = "report-config.xml";
Resource resource = resourceLoader.getResource("classpath:" + fileName);
if (!resource.exists()) {
throw new ConfigFileFormatException(new ConfigFileFormatErrorInfo(true, null, fileName));
}
Element root = null;
try (InputStream inputStream = resource.getInputStream()) {
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();
Document document = builder.parse(new InputSource(inputStream));
// Get the root element
root = document.getDocumentElement();
} catch (Exception e) {
throw new ConfigFileFormatException(new ConfigFileFormatErrorInfo(true, OTHER, fileName));
}
// Check dataSource bean definition
checkDataSourceDefinition(root, fileName);
// Check report generator definition
checkReportGeneratorDefinition(root, fileName);
}
private void checkDataSourceDefinition(Element root, String fileName) {
// Get dataSource elements
NodeList dataSourceList = root.getElementsByTagName("bean");
for (int i = 0; i < dataSourceList.getLength(); i++) {
Element dataSourceElement = (Element) dataSourceList.item(i);
String id = dataSourceElement.getAttribute("id");
if ("dataSource".equals(id)) {
// Get driverClassName property
String driverClassName = dataSourceElement.getElementsByTagName("property")
.item(0)
.getAttributes()
.getNamedItem("value")
.getNodeValue();
// Get url property
String url = dataSourceElement.getElementsByTagName("property")
.item(1)
.getAttributes()
.getNamedItem("value")
.getNodeValue();
// Get username property
String username = dataSourceElement.getElementsByTagName("property")
.item(2)
.getAttributes()
.getNamedItem("value")
.getNodeValue();
// Get password property
String password = dataSourceElement.getElementsByTagName("property")
.item(3)
.getAttributes()
.getNamedItem("value")
.getNodeValue();
if (StringUtils.isAnyBlank(driverClassName, url, username, password)) {
throw new ConfigFileFormatException(new ConfigFileFormatErrorInfo(false, MISSING_PROPERTY, fileName));
}
if (!isPasswordEncrypted(password)) {
throw new ConfigFileFormatException(new ConfigFileFormatErrorInfo(false, INVALID_VALUE, fileName));
}
}
}
}
private void checkReportGeneratorDefinition(Element root, String fileName) {
// Get reportGenerator elements
NodeList reportGeneratorList = root.getElementsByTagName("bean");
for (int i = 0; i < reportGeneratorList.getLength(); i++) {
Element reportGeneratorElement = (Element) reportGeneratorList.item(i);
String id = reportGeneratorElement.getAttribute("id");
if ("reportGenerator".equals(id)) {
// Get report generator configuration
}
}
}
private boolean isPasswordEncrypted(String password) {
// Implement password encryption check logic here
return false;
}
}

Next, create and implement AbstractFailureAnalyzer, overriding the analyze() method as follows:

package org.zyf.javabasic.spring.failureanalyzer.analyzer;
import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;
import org.zyf.javabasic.spring.failureanalyzer.exception.ConfigFileFormatException;
import org.zyf.javabasic.spring.failureanalyzer.model.ConfigFileFormatErrorInfo;
import org.zyf.javabasic.spring.failureanalyzer.model.DescriptionAndAction;

/**
* @program: zyfboot-javabasic
* @description: Specific requirements for configuration file format
* @author: zhangyanfeng
* @create: 2024-05-02 20:31
**/
public class ZYFConfigFileFormatFailureAnalyzer extends AbstractFailureAnalyzer<ConfigFileFormatException> {
@Override
protected FailureAnalysis analyze(Throwable rootFailure, ConfigFileFormatException cause) {
ConfigFileFormatErrorInfo errorInfo = cause.getErrorInfo();
String description;
String action;
if (errorInfo.isFileNotFound()) {
description = "Configuration file '" + errorInfo.getFileName() + "' not found";
action = "Check if the configuration file exists.";
} else {
DescriptionAndAction descriptionAndAction = errorInfo.getDescriptionAndAction();
description = descriptionAndAction.getDescription();
action = descriptionAndAction.getAction();
}
return new FailureAnalysis(description, action, cause);
}
}

spring.factories

xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- Database connection information -->
<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName" value="com.mysql.jdbc.Driver"/>
<property name="url" value="jdbc:mysql://localhost:3306/zyf"/>
<property name="username" value="root"/>
<property name="password" value="Zsyf2014"/>
</bean>

Because the database encryption is incorrect, the program starts with the following error:

6. A Few Suggestions

If you have determined the need to create a custom FailureAnalyzer, there are several precautions to consider:

• Ensure that the FailureAnalyzer can accurately identify the cause of failures, avoiding misleading diagnostics to help quickly locate and resolve issues.
• Provide as detailed information as possible in the diagnosis, including specifics about the failure reason and where it occurred.
• Offer clear suggestions or solutions, which may include code fixes, configuration adjustments, or other recommended actions.

The relevant source code remains in the commonly used GitHub repository.

Seven: Summary

In this article, we delve into the powerful tool of FailureAnalyzer, which not only helps us quickly identify and address errors in our code but also significantly enhances our development efficiency. Through detailed case analyses, we understand how FailureAnalyzer can handle various types of exceptions with custom logic, enabling programmers to pinpoint issues more effectively and find solutions swiftly.

With FailureAnalyzer at our disposal, we no longer have to be overwhelmed by complex errors; instead, we can approach them with confidence. This capability not only strengthens the robustness of our code but also maintains a high level of productivity and assurance during development. As mentioned in the introduction, when faced with errors that constantly "cry" for attention, FailureAnalyzer is like a caring friend who stays by our side, guiding us toward solutions.

Finally, mastering the use of FailureAnalyzer not only helps us handle errors more effectively but also encourages continuous growth in our programming journey. I hope this article inspires you to fully utilize this tool in future projects, consistently improving your code quality and development skills. Let's move forward together towards a more stable and efficient programming world!