DEV Community: Michael Gantman

Zero-Code-Change Stacktrace Filtering for Spring Boot: An Infrastructure-Level Integration

Michael Gantman — Wed, 22 Apr 2026 17:36:28 +0000

This article is intended for software architects, senior backend engineers, and platform engineers working on commercial Java systems where stacktraces are often dominated by framework and infrastructure noise. It is particularly relevant for teams using Spring Boot or other layered architectures who want to improve diagnostic clarity without introducing changes to application code.
This article focuses on how to integrate the MgntUtils stacktrace filtering feature at the infrastructure level. The focus is not the filtering algorithm itself, but rather how to integrate it cleanly so it fits naturally into existing commercial systems and development workflows.

Brief feature Recap

We are talking about the stacktrace filtering feature — one of the most widely used utilities of the open-source MgntUtils library.

A detailed technical deep-dive describing the algorithm and its behavior is available in my article “Java Stacktrace filtering utility”, published on LinkedIn and DZone. If you are interested in the internal mechanics, please refer to that piece. This article assumes you already know the value of the feature and want to know how to deploy it.)

In short, the feature provides intelligent stacktrace filtering that removes framework-related noise (Spring, Hibernate, CGLIB proxies, reflection, servlet chains, etc.). It leaves a concise, easy-to-read stacktrace focused strictly on your application-level code, effectively eliminating the dreaded “stacktrace scroll of death” problem.

The Integration Pain Point

In the original article, the recommended usage pattern was to replace logging statements from:
logger.info("Message", e);
to
logger.info("Message" + TextUtils.getStacktrace(e));

However, when a senior architect responsible for platform quality and long-term maintainability sees a recommendation like this, it immediately raises two major NO-GO flags:

Massive Refactoring Effort: Replacing every logging statement across an existing commercial codebase is expensive, risky, and nearly impossible to justify to management.
Ongoing Maintainability Cost: Developers would need to remember to always use this special logging pattern. Inevitably, some log statements would be written incorrectly, leading to inconsistencies and reducing the value of the solution.

Because of these concerns, even a highly useful feature is often rejected purely due to integration friction.

The Goal of This Article

This article demonstrates an integration approach that resolves these concerns by moving the feature integration to the infrastructure level.

The proposed solution:

Requires ZERO changes to your existing application code.
Preserves standard logging syntax (developers just log exactly as they always have).
Introduces no additional cognitive burden on your team.
Remains fully transparent to the application layer.

As a bonus, we will also introduce a hot runtime toggle, allowing Admin or SRE users to enable or disable the filtering dynamically at runtime - without a redeployment or server restart.

An integration example is demonstrated in the MgntUtilsUsage project—a working, out-of-the-box Spring Boot Application with this full infrastructure integration implemented. The project is available as a public GitHub repository.

Integration Steps

For the purposes of this article, we will assume the commercial project is using either Logback (which is the default logging implementation for Spring Boot) or Log4j2. For both of those logging implementations, the proposed integration is roughly the same:

Prerequisite: Since the stacktrace filtering feature is provided by the MgntUtils library, you will first need to include this library in your project. Here are the Maven and Gradle coordinates:

Maven:

<dependency>
    <groupId>com.github.michaelgantman</groupId>
    <artifactId>MgntUtils</artifactId>
    <version>1.7.0.7</version>
</dependency>

Gradle:

implementation("com.github.michaelgantman:MgntUtils:1.7.0.7")

Note: Version 1.7.0.7 is the latest version at the time of writing. To ensure you have the latest release, please check the MgntUtils page on Maven Central.

Write a Java class that will handle any incoming exception using the MgntUtils stacktrace filtering utility.
Register this class with the logging framework to act as a custom exception handler.
Initialize the relevant package prefixes for the MgntUtils stacktrace filtering utility, so it knows which packages should be considered important (which controls how the stacktrace filtering is done).

Integration Steps for Logback

1. Write the Logback Interceptor (The "Magic" Engine)

Logback controls how exceptions are formatted via converters. We will create a custom converter that intercepts the exception, strips out the framework noise using MgntUtils, and returns the clean string.

Create this class in your project:

package com.example.stamboot.config.logging;

import com.mgnt.utils.TextUtils;
import ch.qos.logback.classic.pattern.ThrowableProxyConverter;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.classic.spi.IThrowableProxy;
import ch.qos.logback.classic.spi.ThrowableProxy;

/**
 * Global Logback interceptor to filter all stack traces using MgntUtils.
 */

public class MgntStackTraceConverter extends ThrowableProxyConverter {
    private static boolean cutTheBS = true;

    @Override
    public String convert(ILoggingEvent event) {
       IThrowableProxy proxy = event.getThrowableProxy();
       if (proxy == null) {
          return "";
       }

       // Extract the raw java.lang.Throwable from Logback's proxy object
       if (proxy instanceof ThrowableProxy) {
          Throwable rawException = ((ThrowableProxy) proxy).getThrowable();
          //remove first new line and add new line at the end
          return TextUtils.getStacktrace(rawException, cutTheBS).substring(1) + "\n";
       }

       // Fallback: If the exception is serialized over a network,
       // fallback to standard Logback formatting.
       return super.convert(event);
    }

    public static synchronized boolean isCutTheBS() {
       return cutTheBS;
    }

    public static synchronized void setCutTheBS(boolean cutTheBs) {
       MgntStackTraceConverter.cutTheBS = cutTheBs;
    }
}

Note that we added two methods here: isCutTheBS() and setCutTheBS(). Those methods are not required by the ThrowableProxyConverter interface, but they will be used for a hot switch that will allow us to programmatically turn the filtering feature on and off without restarting the project.

2. Wire it into logback.xml (or logback-spring.xml)

If you are starting a new project (and not integrating this feature into an existing one), you just need to tell Logback to replace its default exception printing logic (usually denoted by %ex) with your new custom converter. Create a new file named logback.xml and place it in your classpath (if it is a Spring Boot project, place it in your src/main/resources folder):

<configuration>
    <conversionRule conversionWord="ex" 
          converterClass="com.example.stamboot.config.logging.MgntStackTraceConverter" />
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n%ex</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
</configuration>

If you are integrating this feature into an existing project, you most likely already have your Logback configuration in a logback.xml or logback-spring.xml file. In this case, you will need to do two things:

A. Add the <conversionRule>
You must add this line near the top of the <configuration> block:

<conversionRule conversionWord="ex" 
converterClass="com.example.stamboot.config.logging.MgntStackTraceConverter" />

B. Update the <pattern> for all Appenders (The Invocation)
Just because you taught Logback the word %ex doesn't mean the appenders are actually using it. You must check the <pattern> strings inside your existing <appender> blocks and make sure they invoke your token.

The Spring Boot Gotcha: By default, standard Logback uses %ex to print exceptions. But if a project is using Spring Boot, developers often copy-paste Spring's default patterns, which use %wEx (Whitespace Throwable Proxy) or %xEx (Extended Throwable Proxy).

If an existing appender looks like this:

<pattern>%d{yyyy-MM-dd} [%thread] %-5level %logger{36} - %msg%n%wEx</pattern>

Your filter will not run, because Logback is looking for the %wEx logic, not your %ex logic! They must change the end of their pattern to use the exact conversionWord you defined in step 1:

<pattern>%d{yyyy-MM-dd} [%thread] %-5level %logger{36} - %msg%n%ex</pattern>

3. Configure your relevant packages

You will need to invoke the method TextUtils.setRelevantPackage("com.example.stamboot.") somewhere in your project initialization to specify which packages should be considered important.

Note that this method supports multiple prefixes. In my example, I used a single prefix ("com.example.stamboot.") since I took it from the MgntUtilsUsage project - a working, out-of-the-box Spring Boot Application with this full infrastructure integration implemented. In that repo, all my code resides in packages that start with that prefix. You will need to set the correct prefix (or multiple prefixes) for your specific project.

For a detailed discussion of this mechanism, see the Java Stacktrace filtering utility article I mentioned above, as well as the Javadoc for the getStacktrace() method.

Important Note: If your project is a Spring Boot project, we will discuss exactly where to place this initialization code for maximum efficiency at the end of the article.

Integration Steps for Log4J2

To replace the default exception formatter in Log4j2 without XML, you just write the converter and annotate it. At compile time, Log4j2 finds it and wires it up automatically.

1. Write the Log4j2 Plugin (The Converter)

Instead of implementing an interface, you extend ThrowablePatternConverter and tag it with Log4j2's @Plugin and @ConverterKeys annotations.

By taking over the keys {"ex", "throwable", "exception"}, you are telling Log4j2: "Anytime a layout pattern asks for an exception, use me instead of the default."

So your class for Log4J2 option will look as follows:

package com.example.stamboot.config.logging;

import com.mgnt.utils.TextUtils;
import org.apache.logging.log4j.core.LogEvent;
import org.apache.logging.log4j.core.config.Configuration;
import org.apache.logging.log4j.core.config.plugins.Plugin;
import org.apache.logging.log4j.core.pattern.ConverterKeys;
import org.apache.logging.log4j.core.pattern.PatternConverter;
import org.apache.logging.log4j.core.pattern.ThrowablePatternConverter;

/**
 * Global Log4j2 interceptor to filter stack traces using MgntUtils.
 */
@Plugin(name = "MgntStackTraceConverter", category = PatternConverter.CATEGORY)
@ConverterKeys({ "ex", "throwable", "exception" }) // Overrides default tokens
public class MgntStackTraceConverter extends ThrowablePatternConverter {
    private static boolean cutTheBS = true;

    // Log4j2 plugins REQUIRE a static newInstance method to be instantiated!
    public static MgntStackTraceConverter newInstance(final Configuration config, final String[] options) {
        return new MgntStackTraceConverter(config, options);
    }

    protected MgntStackTraceConverter(Configuration config, String[] options) {
        super("MgntThrowable", "throwable", options, config);
    }

    @Override
    public void format(final LogEvent event, final StringBuilder toAppendTo) {
        Throwable rawException = event.getThrown();

        if (rawException != null) {
            // Route the exception through MgntUtils!
            String cleanTrace = TextUtils.getStacktrace(rawException, cutTheBS);
            //remove first new line and add new line at the end
            toAppendTo.append(cleanTrace.substring(1)).append("\n"); 
        }
    }

    public static synchronized boolean isCutTheBS() {
        return cutTheBS;
    }

    public static synchronized void setCutTheBS(boolean cutTheBs) {
        MgntStackTraceConverter.cutTheBS = cutTheBs;
    }
}

2. Wire it into log4j2.xml (or log4j2-spring.xml)

If you are starting a new project with Log4j2, you will create a new log4j2.xml file in your src/main/resources folder.

Because your custom converter uses the @Plugin and @ConverterKeys annotations, Log4j2 absorbs the logic natively. You do not need a complex <conversionRule> mapping like Logback. You simply need to provide the packages attribute in the root configuration tag so Log4j2 knows where to scan for your class:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="com.example.stamboot.config.logging">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout>
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n%ex</Pattern>
            </PatternLayout>
        </Console>
    </Appenders>

    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

If you are integrating this feature into an existing project, you most likely already have a log4j2.xml (or log4j2-spring.xml) file. In this case, you only need to verify two things:

A. Add the packages attribute to the root tag
Find your existing <Configuration> tag at the very top of the file and add your package path to it:

<Configuration status="WARN" packages="com.example.stamboot.config.logging">

B. Update the <Pattern> for all Appenders
Just like with Logback, you must check your existing <Pattern> strings. If your project is a Spring Boot application, developers may have copied Spring's default patterns which use %wEx or %xEx.

If an existing appender looks like this:

<Pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{36} - %msg%n%wEx</Pattern>

Your filter will not trigger! You must change the end of the pattern to use %ex (or %throwable or %exception), which match the @ConverterKeys defined in your Java class:

<Pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{36} - %msg%n%ex</Pattern>

3. Configure relevant packages

This step is the same regardless of whether you use Logback, Log4j2, or any other logging framework in your project. You will need to invoke the method TextUtils.setRelevantPackage("com.example.stamboot.") somewhere in your project initialization to specify which packages should be considered important. Earlier in the article, we promised to discuss in detail where to place this initialization code if your project is Spring Boot-based. So, as promised, here is the recommendation:

If you are using a modern IoC framework like Spring Boot, you might be tempted to put this initialization inside a Spring component, perhaps using an @EventListener(ContextRefreshedEvent.class) or a @PostConstruct method. Do NOT do this. If you rely on the Spring lifecycle to initialize your stacktrace filter, you create a massive logging blind spot during application startup. In Spring Boot, application startup isn't just server configuration - it is exactly when the framework uses reflection to instantiate and execute your code. Consider the two most common (and painful) startup crashes:

The @PostConstruct Crash: Imagine a developer writes a service that pre-loads cache data from the database the moment the bean is created. If loadData() throws a NullPointerException or BadSqlGrammarException, the crash happens before the application context is fully ready.
The Bad @Configuration Bean: If a configuration class manually instantiates a bean and throws an exception (e.g., trying to read a missing file or parse a bad JWT secret), Spring wraps your exception in a massive BeanCreationException.

If your prefixes are not set yet because you are waiting for an ApplicationReadyEvent, you will get the dreaded 200-line "Scroll of Death" consisting almost entirely of org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory noise.

The Solution: The main() method

To guarantee your filter is already configured and armed during the most chaotic part of the application lifecycle, you must move the initialization entirely outside of the Spring context. Place it in your pure Java main() method, right before SpringApplication.run(...) is called:

package com.example.stamboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.mgnt.utils.TextUtils;

@SpringBootApplication
public class StamBootApplication {

    public static void main(String[] args) {
        // 1. Arm the stacktrace filter FIRST
        TextUtils.setRelevantPackage("com.example.stamboot.");

        // 2. Start the Spring machinery
        SpringApplication.run(StamBootApplication.class, args);
    }
}

By doing this, MgntUtils will see your application packages on the stack during a startup crash, filter out the 190 lines of Spring Boot factory noise, and point you exactly to the line in your @PostConstruct or @Configuration class that broke the deployment.

On the other hand MgntUtils filtering feature has a built-in safety measure: if your entire stacktrace does NOT contain any lines that match your configured prefixes, the stacktrace is printed in full and not filtered at all. Because of this fail-safe, you do not risk losing important diagnostic information if a crash occurs purely within the framework and does not involve your code.

Bonus Feature: Hot enable/disable filtering switch

Earlier in the article we promised a hot runtime toggle, allowing Admin or SRE users to enable or disable the filtering dynamically at runtime - without a redeployment or server restart. So, here it is.

If you look at our MgntStackTraceConverter class implementation from earlier, we introduced two seemingly redundant methods:

public static synchronized boolean isCutTheBS() {
    return cutTheBS;
}

public static synchronized void setCutTheBS(boolean cutTheBs) {
    MgntStackTraceConverter.cutTheBS = cutTheBs;
}

These methods are the getter and setter for the cutTheBS flag which in our MgntStackTraceConverter implementation controls whether the stacktrace is filtered or not. These methods are our hooks. All we need now is to provide some user interface that will allow user to control this flag.

In our working Spring Boot example (mentioned earlier and discussed below) we provide a REST controller that gives the user two APIs to see the current value of the flag and to change its setting.

Here is the proposed controller implementation:

package com.example.stamboot.config.logging;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("config/log/stacktrace")
public class LoggerConfigController {

  @GetMapping
  public ResponseEntity<String> setFilteringFlag(@RequestParam Boolean filter) {
    MgntStackTraceConverter.setCutTheBS(filter);
    return ResponseEntity.ok(
      "Stacktrace filtering flag is set to: " + MgntStackTraceConverter.isCutTheBS());
  }

  @GetMapping("/filter/status")
  public ResponseEntity<String> getFilteringFlag() {
    return ResponseEntity.ok(
      "Stacktrace filtering flag current value is: " + MgntStackTraceConverter.isCutTheBS());
  }
}

By calling the provided URLs user can:

Check the current status: http://localhost:8080/config/log/stacktrace/filter/status
Set the status to true or false:

http://localhost:8080/config/log/stacktrace?filter=true
http://localhost:8080/config/log/stacktrace?filter=false

Important Notes:

Using @GetMapping here is a deliberate trade-off. By definition, GET must be safe (no side effects) and idempotent — it should never mutate state. Using it here is a clear violation of HTTP semantics, and in a real commercial implementation this endpoint should use @PutMapping or @PostMapping. However, for the purposes of this demo, GET allows you to trigger the toggle directly from a browser URL bar with no REST client required. The point this demo is meant to illustrate is the mechanism — that you can expose a runtime configuration toggle with no restart or redeployment — and not the choice of HTTP method.
In our simple demo, these APIs are open to all. In a real-life commercial application, appropriate security measures (such as Spring Security) should be applied to restrict these endpoints to Admin and SRE users only.

Repository with working example

Here is the link to the repository with an out-of-the-box working example: https://github.com/michaelgantman/MgntUtilsUsage

This repo contains a Spring Boot application that uses Logback for logging functionality, which is the Spring Boot default. We recommend you clone the repository and actually run the example. But regardless, let's look at the relevant parts:

The Converter: The MgntStackTraceConverter class that contains the actual custom filtering logic (and shown above in this article) is located here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/config/logging/MgntStackTraceConverter.java.
The Configuration: The logback.xml is here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/resources/logback.xml. This configuration tells Logback to use custom logic for printing stacktraces provided in MgntStackTraceConverter instead of its own.
The Toggle API: The LoggerConfigController that provides hot on/off toggle for the feature (also shown above) is here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/config/logging/LoggerConfigController.java
The Initialization: Setting the relevant package prefix can be seen in StamBootApplication (line 12) here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/StamBootApplication.java
The Demo Endpoint: And finally, the most interesting part - the controller that actually demonstrates the log output with filtered/unfiltered stacktrace (depending on the current toggle state) is here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/controller/LogFilteringDemoController.java. See method logEndPoint(). Note that this method is exposed by API http://localhost:8080/log. The method throws an exception with 50% probability and returns a text message notifying the user if an exception was or was not thrown.

How to run the example

Clone the repo from https://github.com/michaelgantman/MgntUtilsUsage, open it in your IDE, and run it.
Once it runs, hit the URL http://localhost:8080/config/log/stacktrace/filter/status to check the current status of the toggle (It is true by default).
Hit the URL http://localhost:8080/log. This URL causes a backend exception with 50% probability. It will either return a message "[Current Timestamp]: No Exception" or "[Current Timestamp]: Exception occurred, check the logs".
If you got "No Exception," re-run the API (refresh your browser) until you get the message "Exception occurred, check the logs". Go to your IDE and see in the console that the exception is indeed printed by the logger and it is cleanly filtered. You will see the following output:

INFO  c.e.s.c.LogFilteringDemoController - Raw Exception:
java.lang.Exception: Demo Exception
at com.example.stamboot.controller.LogFilteringDemoController.callHandler(LogFilteringDemoController.java:49)
at com.example.stamboot.controller.LogFilteringDemoController.logEndPoint(LogFilteringDemoController.java:36)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
...

Now run the API http://localhost:8080/config/log/stacktrace?filter=false to switch off the filtering.
Run http://localhost:8080/log again until you get "Exception occurred, check the logs" message. Go back to your IDE and see that the output now is the full "Scroll of Death"

INFO  c.e.s.c.LogFilteringDemoController - Raw Exception:
java.lang.Exception: Demo Exception
at com.example.stamboot.controller.LogFilteringDemoController.callHandler(LogFilteringDemoController.java:49)
at com.example.stamboot.controller.LogFilteringDemoController.logEndPoint(LogFilteringDemoController.java:36)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:498)
at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:205)
at org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:150)
at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:117)
at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:895)
at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:808)
at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)
at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1067)
at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:963)
at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006)
at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:898)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:655)
at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:764)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:227)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100)
at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93)
at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)
at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:197)
at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:97)
at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:540)
at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:135)
at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92)
at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:78)
at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:357)
at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:382)
at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)
at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:895)
at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1732)
at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
at org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191)
at org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659)
at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
at java.lang.Thread.run(Thread.java:750)

Conclusion

As demonstrated in this article, integrating the MgntUtils stacktrace filtering feature at the infrastructure level requires a small one-time effort and results in clean, focused stacktraces across your entire project — without any changes to your application code. Developers on your team will not need to learn any new logging patterns or conventions. The hot runtime toggle provides additional control for Admin and SRE users to manage the feature at runtime without a redeployment. The MgntUtilsUsage repository linked throughout this article contains a fully working example of all of this implemented out of the box.

Infrastructure for Extensible Multi-Stage Workflows Across Multiple Data Types

Michael Gantman — Mon, 12 Jan 2026 23:45:11 +0000

Introduction and Purpose of This Article

This is an in-depth technical article for Java developers. It presents a lightweight yet powerful architectural approach for implementing extensible, multi-stage processing workflows that support multiple data types, multiple processing stages, and arbitrary future extensibility — all without modifying existing code.

Before diving into the infrastructure, let’s first clearly define the problem using a simple, generic example.

What Is a Multi-Stage Processing Workflow for Multiple Data Types?

Assume you have input data files that need to be processed through several consecutive steps. For this example, let’s define the workflow stages as:

Pre-Processing
Processing
Post-Processing

This sequence forms a workflow, where each stage performs its own transformation.

Now assume that your system must support multiple data types, where:

Each data type goes through the same sequence of stages, but
Each data type requires its own type-specific implementation for each stage

For example, suppose your input files may arrive in JSON or XML format. However:

The system must be able to support an extension to an arbitrary number of formats in the future
The system must also be able to extend or reorder the number of workflow stages

This is precisely what the expression “multi-stage processing workflow for multiple data types” refers to.

Although JSON and XML are used here as simple illustrative examples, the pattern generalizes to virtually any domain. Some representative examples include:

Image formats (BMP, JPEG, PNG)
Sensor telemetry formats
Message and protocol formats
Validation pipelines
ETL stages
Document generation
Many other processing domains

The key properties of this pattern are:

The number of stages is not fixed — the workflow may contain any number of steps.
The number of supported data types is not fixed — and adding a new type should NOT require any changes to existing code.

This is where the proposed solution becomes essential.

Overall Solution and Demo Description

The solution described in this article is based on the self-populating factory infrastructure provided by the open-source MgntUtils library, and demonstrated by a real-world example in the MgntUtilsUsage repository.

MgntUtils Resources

GitHub: https://github.com/michaelgantman/Mgnt
Maven Central: https://central.sonatype.com/artifact/com.github.michaelgantman/MgntUtils
Javadoc: https://michaelgantman.github.io/Mgnt/docs/

MgntUtilsUsage Demo Repository

https://github.com/michaelgantman/MgntUtilsUsage

This architectural approach emphasizes:

Zero-configuration extensibility (The system is completely data-type-agnostic. New types are added simply by providing type-specific implementations for each stage — with no additional configuration or registration.)
Automatic component discovery
Clean separation of responsibilities (Workflow orchestration is never aware of type-specific implementation details.)
Elimination of switch statements, large registries, and manual wiring
Support for arbitrarily complex workflows (Stages can be added, removed, or reordered.)
Strong error handling with discoverable valid types (This is demonstrated in the demo. Although not an inherent part of the pattern itself, it is included in the demo to keep it real-world like.)

What is self-populating factory infrastructure?

Before diving into the solution details, it is important to briefly explain what a self-populating factory infrastructure is, since this concept is the cornerstone of the proposed solution. At its core, this idea is an extension of the classic Factory pattern. In the traditional Factory pattern, you typically have:

An interface
Several concrete implementations of that interface
A factory that returns a concrete implementation based on some key

While this pattern is well-known and widely used, it usually requires explicit registration of implementations inside the factory — often through configuration files, static initialization blocks, or manual wiring.

The Self-Populating Factory Idea

The key idea behind a self-populating factory is that each concrete implementation is factory-aware and is responsible for registering itself with the factory when it is instantiated.

In other words:

The factory does not need to know about concrete implementations
Concrete implementations insert themselves into the factory automatically
Factory population happens implicitly, not through external configuration

This behavior is exactly what gives the pattern its name — self-populating factory.

How MgntUtils Implements This Infrastructure

The factory-awareness and automatic self-registration behavior are provided by the self-populating factory infrastructure in the MgntUtils library, located in the package:

com.mgnt.lyfecycle.management

Package-level Javadoc: https://michaelgantman.github.io/Mgnt/docs/com/mgnt/lifecycle/management/package-summary.html

This package contains only two core classes:

To use this infrastructure, you need to:

Create a factory class that extends BaseEntityFactory
Ensure that all concrete implementations extend BaseEntity

Since concrete implementations must contain some mandatory infrastructure-related code, it is recommended to:

Create an interface that will define what your implementations must do — a method signature (or a set of method signatures)
Create a single abstract base implementation that implements your interface
Place all mandatory infrastructure code into that abstract base class
Have all concrete implementations extend that abstract base class

Once this structure is in place, each concrete implementation instance automatically registers itself with its factory when its constructor is invoked.

As a result:

You never need to explicitly populate the factory
You do not need to worry about when or how the factory is populated
Factory population happens transparently and consistently

After the concrete implementations are instantiated, you can retrieve them from the factory anywhere in your code.

Factory Key Options (A Crucial Design Point)

There are two ways a concrete implementation can be registered in a factory:

Using the concrete class name as the factory key
Using a custom, user-defined key

While the second option might initially appear as an insignificant feature, it is absolutely critical for the workflow design presented later in this article.

The ability to register implementations under custom keys, rather than class names, enables multiple different factories to share the same set of keys (much like the namespace pattern). This is the foundation that enables:

Clean multi-stage workflows
Consistent type-based routing across multiple factories
Strong decoupling between workflow orchestration and implementation details

This point will become especially important when we transition from the simple XML/JSON example to the full Letter Formatting workflow in the MgntUtilsUsage repository.

Runnable Example in MgntUtils

The MgntUtils library contains a clear, runnable example that demonstrates the self-populating factory mechanism. It can be found in the package:

com.mgnt.lifecycle.management.example

Example package git repo link: https://github.com/michaelgantman/Mgnt/tree/master/src/main/java/com/mgnt/lifecycle/management/example

Example Walkthrough

The example defines an interface called InfoFormatter with a single method:

String formatMessage(String message);

InfoFormatter interface: https://github.com/michaelgantman/Mgnt/blob/master/src/main/java/com/mgnt/lifecycle/management/example/InfoFormatter.java

As described earlier, there is a common abstract base class called BaseInfoFormatter, which contains the mandatory infrastructure-related code:

BaseInfoFormatter (mandatory code: lines 11–39): https://github.com/michaelgantman/Mgnt/blob/master/src/main/java/com/mgnt/lifecycle/management/example/BaseInfoFormatter.java

Note that all concrete implementations extend this BaseInfoFormatter class.

Two concrete implementations are provided:

In this example:

Each concrete implementation registers itself in the factory
Registration uses custom keys: “JSON” and “XML”

The UsageExample class is a runnable class (has main() method). So, if you downloaded the Mgnt git repository and want to run the example — just run UsageExample class as java application.

UsageExample: https://github.com/michaelgantman/Mgnt/blob/master/src/main/java/com/mgnt/lifecycle/management/example/UsageExample.java

The main method looks very simple:

public static void main(String... args) {
  init();
  printFormattedGreetings();
}

method init() sole purpose is to instantiate all concrete implementations. Once those constructors are executed, the factory is automatically populated by the infrastructure.
Method printFormattedGreetings() Uses InfoFormatterFactory to retrieve implementations by their custom keys and run the concrete implementations methods. This demonstrates that no explicit factory population code exists.

InfoFormatterFactory: https://github.com/michaelgantman/Mgnt/blob/master/src/main/java/com/mgnt/lifecycle/management/example/InfoFormatterFactory.java

Main point: The factory is populated automatically by the infrastructure — without configuration files, manual registration, or wiring logic. The factory population is triggered by method init() which in our case is a bootstrapping code that ensures that factory is initialized before it is used in business logic method printFormattedGreetings().

This example provides a minimal but complete demonstration of the self-populating factory infrastructure.

To visualize the class structure described above, see the diagram below. It shows how the MgntUtils infrastructure classes (BaseEntity, BaseEntityFactory) interact with user-defined interfaces, base classes, and concrete implementations to enable automatic factory population.

An important note: For this mechanism to work, concrete implementations must actually be instantiated — that is, their constructors must be invoked. Since self-registration happens during object construction, a class that is never instantiated will never register itself with the factory. (See the description of init() method above)

This requirement makes frameworks that use the Inversion of Control (IoC) pattern — such as Spring and Spring Boot — particularly well suited for this utility. In such frameworks, concrete implementations can be instantiated automatically as part of the application startup process. In the case of Spring Boot, this typically means declaring the implementations as Spring beans with lazy initialization disabled, ensuring they are eagerly created during context initialization. You can see the example of this in declaration of one of the concrete implementations in MgntUtilsUsage library, Here is the link to CustomerLetterPreFomatter class: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/preformat/implementations/CustomerLetterPreFormatter.java

See lines 8–10 they look like

@Component 
@Lazy(false) 
public class CustomerLetterPreFormatter extends BaseLetterPreFormatter {

As a result, factory population becomes a natural side effect of application startup, requiring no additional wiring or bootstrap code.

Important detail: Note annotation @Lazy(false). This turns off lazy mode and ensuring that this bean is instantiated at SpringBoot application startup as opposed to the first time it is requested. Without it it won’t be initialized and won’t register in the factory. And so, the search in the factory for that bean will fail.

Also note that while SpringBoot or any other IoC frameworks fit very well with self-populating factory pattern they are not required. For non-IoC environments you will need to write your own simple bootstrap code — just like method init() in the example above.

In the next section, we will build directly on this foundation and show how the same mechanism enables a clean, extensible, multi-stage workflow architecture in a real-world system using the MgntUtilsUsage repository.

Complete multi-stage workflow architecture example

Let’s first define the concrete task for which the following example demonstrates the proposed solution.

Assume that you need to develop a system responsible for formatting corporate letters.

Input Requirements

The system receives:

Letter content — a plain text string
Letter type — one of a predefined set of values, for example: LEGAL, INTERNAL, CUSTOMER

Processing Requirements

The system must format the letter using three distinct processing stages:

Pre-formatting Adds a type-dependent greeting that appears before the letter content.
Formatting Adds a type-dependent signature that appears after the letter content.
Post-formatting Adds a type-dependent letter header that appears above the greeting and content.

Each stage performs an independent transformation and is unaware of the internal logic of other stages.

Extensibility Requirements

The architecture must satisfy the following extensibility constraints:

Type extensibility The system must support adding an arbitrary number of new letter types without modifying existing code.
Stage extensibility The number of processing stages must not be fixed. Stages can be added, removed, or reordered.
Conditional workflow support The next stage may be determined based on: The result of a previous stage and External conditions or metadata

These requirements rule out hardcoded workflows and require a fully dynamic solution.

Let’s run the demo and show some examples:

How to Run the demo project

Clone MgntUtilsUsage git repo. Repo link: https://github.com/michaelgantman/MgntUtilsUsage (Clone URL: https://github.com/michaelgantman/MgntUtilsUsage.git).
Open the project in your IDE and run class com.example.stamboot.StamBootApplication.java as Java application.

Running example requests:

It is assumed that when you start your application the listening port is 8080.

In your browser run the following link:

http://localhost:8080/letter?content=Hello world&type=CUSTOMER

For the letter content “Hello world” and type “CUSTOMER” the result should be:

2025-12-20 Customer communication

Dear customer,
Hello world

Best regards,
Your Service provider

In the example above

The line “2025–12–20 Customer communication” is added by post-formatting stage
The line “Dear customer,” is added by pre-formatting stage
The 2 lines “Best regards, Your Service provider” are added by formatting stage

The same content but with the type “INTERNAL”
(Link: http://localhost:8080/letter?content=Hello world&type=INTERNAL)
Should yield the following result:

2025-12-20 Internal (Confidential) communication

Dear employees,
Hello world

Senior Management

This task definition captures a realistic business requirement while remaining simple enough to clearly demonstrate how a self-populating, multi-stage workflow architecture can be applied in practice.

In the next section, we will walk through how this task is implemented using the self-populating factory infrastructure provided by the open-source MgntUtils library, showing how multiple factories, shared type keys, and staged processing work together to produce the final result.

Example resources

The complete, runnable example discussed in this section can be found in the MgntUtilsUsage Git repository: https://github.com/michaelgantman/MgntUtilsUsage

The most important files and packages are listed below.

Project Configuration pom.xml https://github.com/michaelgantman/MgntUtilsUsage/blob/main/pom.xml Note that the MgntUtils library is declared as a dependency on lines 30–34. The entire example is built on top of the self-populating factory infrastructure provided by this open-source library.
API Entry Point LetterFormattingController class https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/controller/LetterFormattingController.java This class serves as the entry point for the example. It exposes a GET endpoint that demonstrates the complete multi-stage formatting workflow.For simplicity and demonstration purposes only: both letter content and Letter type are passed as a URL parameter. This approach is used strictly for example convenience. In a real-world implementation, passing letter content via URL parameters would not be practical or advisable. A production-ready design would typically use:
- A POST request
- A request body (for example, JSON)
- Proper validation and payload size handling
The choice of a GET method here keeps the example easy to invoke and focus remains on the workflow architecture, rather than on REST API design details.
Letter Formatting Implementation package com.example.stamboot.letterformatting https://github.com/michaelgantman/MgntUtilsUsage/tree/main/src/main/java/com/example/stamboot/letterformatting

The Core Design Idea

Conceptually, the system behaves as a lightweight workflow engine:

Each processing stage is implemented as an independent, self-populating factory.

For each workflow stage, we create:

A dedicated factory
A set of concrete implementations, one per letter type

Specifically, for the three stages defined earlier, the solution introduces the following factories:

LetterPreFormatterFactory
LetterFormatterFactory
LetterPostFormatterFactory

Each factory contains three concrete implementations, one for each supported letter type:

LEGAL
INTERNAL
CUSTOMER

The Crucial Design Insight: Shared Custom Keys

As explained earlier in the discussion of the self-populating factory infrastructure, concrete implementations can be registered in a factory using custom keys, rather than class names.

This capability is the cornerstone of the entire workflow design.

In this example:

All factories use exactly the same set of custom keys
Each key corresponds to a letter type
The keys are identical across all factories: LEGAL, INTERNAL, CUSTOMER

As a result:

Each factory is completely independent
No factory is aware of any other factory
No stage contains logic to translate or map types

Yet all factories implicitly conform to the same convention.

How This Enables a Clean Workflow

As the workflow progresses from stage to stage, the code simply retrieves the appropriate implementation for the current letter type from the corresponding factory. For every stage and every factory, the retrieval logic is always the same:

factory.getInstance(LETTER_TYPE)

There is:

No conditional logic
No switch statements
No type mapping code
No coupling between stages

Each stage:

Knows only its own responsibility
Retrieves the correct implementation using the shared key convention
Produces its output independently

This design allows the workflow to be:

Type-extensible (new letter types can be added)
Stage-extensible (new stages can be introduced)
Order-flexible (stages can be reordered or conditionally chained)

— all without modifying existing code.

Architectural Diagram of the Multi-Stage Letter Formatting System

The diagram below presents the architectural structure of the multi-stage letter formatting system. Each processing stage is implemented as an independent self-populating factory with its own interface, abstract base class, and concrete implementations. All factories share an identical set of custom keys corresponding to letter types, which allows the workflow to progress through stages without any coupling between them.

The workflow

Let’s now examine how the workflow is executed at runtime. There are three main components involved:

LetterFormattingController https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/controller/LetterFormattingController.java
LetterFormattingService https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/service/LetterFormattingService.java
LetterFormattingManager https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/bl/LetterFormattingManager.java

The following diagram illustrates the runtime workflow and interaction between the main components involved in letter formatting. It shows how an incoming request propagates through the controller and service layers into the business logic manager, and how the manager orchestrates the execution of individual processing stages using self-populating factories.

LetterFormattingController is the entry point of the application. It exposes a GET HTTP endpoint that receives letter content and letter type as request parameters (this is done purely for example convenience and is not intended as a real-world API design).

Upon receiving a request, the controller delegates the formatting task to LetterFormattingService by invoking

letterFormattingService.formatLetter(content, type)

(see line 35).

The controller receives the formatted letter as a result, logs it, and builds an HTTP response containing the formatted output. If an error occurs, the exception is caught, an appropriate log message is written, and an HTTP error response is returned.

LetterFormattingService performs two responsibilities:

It validates the letter type against the predefined set of supported types and throws an exception if the type is invalid.
It delegates the actual formatting workflow execution to LetterFormattingManager.

This separation keeps validation and orchestration concerns outside of the controller while keeping business flow logic out of the service layer.

LetterFormattingManager is the core business logic engine. It is responsible for determining which stages are executed and in what order.

In this example, the workflow is unconditional and consists of three sequential stages:

Pre-formatting
Formatting
Post-Formatting

However, this logic can be arbitrarily complex. Stages may be reordered, skipped, or conditionally executed based on the result of previous stages or other business rules. Crucially, this logic is implemented without any knowledge of concrete implementations.

For each stage, the manager retrieves a concrete implementation from the corresponding factory using the letter type and invokes the stage-specific processing method.

The most important architectural point here is that all stage factories share the same identical set of keys, representing the supported letter types. This guarantees that for any stage, retrieving a concrete implementation is always a simple and uniform operation:

factory.getInstance(dataType)

As a result, stages remain completely decoupled from each other, while the workflow logic remains independent of both the number of stages and the number of supported letter types.

Type and Stage Extensibility and Conditional Workflow

In this section, we will finally discuss the repeatedly mentioned benefits of the proposed infrastructure.

At the end of “The Core Design Idea” section, we stated that this design allows the framework to be:

Type-extensible (new letter types can be added)
Stage-extensible (new processing stages can be introduced)
Order-flexible (stages can be reordered or conditionally chained)

— all without modifying existing code.

Let’s now demonstrate how this is achieved, point by point.

Conditional Workflow Logic

Here we will discuss how processing stages can be reordered or conditionally executed based on the results of previous stages or any other runtime conditions.

As stated earlier, the business logic engine is implemented in com.example.stamboot.letterformatting.bl.LetterFormattingManager (see source code here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/bl/LetterFormattingManager.java)

The workflow is controlled by the method:

public String handleLetterFormatting(String content, DocumentType documentType) { 
  String preformattedContent = preformatLetter(content, documentType);
  String formattedContent = formatLetter(preformattedContent,  documentType);
  String postFormattedString = postFormatLetter(formattedContent, documentType);
  return postFormattedString; 
}

(see lines 15–20 in the class source)

As shown above, the stages are executed in a simple, unconditional sequence:

Pre-formatting (pre-appends a greeting to the letter content)
Formatting (post-appends a signature)
Post-formatting (pre-appends a header)

Reordering Stages

Let’s start with a simple unconditional modification: changing the execution order by switching the formatting and post-formatting stages.

Originally, the flow was:

Pre-append greeting → Post-append signature → Pre-append header

After reordering, the flow becomes:

Pre-append greeting → Pre-append header → Post-append signature

To achieve this, we only need to modify the handleLetterFormatting() method as follows:

public String handleLetterFormatting(String content, DocumentType documentType) { 
  String preformattedContent = preformatLetter(content, documentType);
  String postFormattedString = postFormatLetter(preformattedContent, documentType); 
  String formattedContent = formatLetter(postFormattedString, documentType); 
  return formattedContent; 
}

This is the only change required.

In this particular example, because pre-formatting and post-formatting both prepend content and formatting appends content, changing their order does not affect the final output. However, if you run it in debug mode and inspect the intermediate values, you will clearly see that the order of stage execution has changed.

This trivial example demonstrates an important architectural point: stage execution order can be changed without modifying any stage implementations, and without any awareness of how many implementations (letter types) exist.

Conditional Workflow

Now let’s introduce conditional logic.The core point remains the same: workflow control logic is decoupled from the number of supported types and from their implementation details.

Assume that we want to perform a document modification only if the content does not already conform to the expected standard.

For example, the pre-formatting stage prepends a greeting. Let’s modify the workflow so that this stage is executed only if the original letter content does not already contain a greeting.

Introducing Letter Metadata

We introduce a simple metadata class in the package com.example.stamboot.letterformatting.bl:

public class LetterMetadata {
 private boolean headerPresent; 
 private boolean greetingPresent;
 private boolean signaturePresent;
}

(Getter and setter methods are omitted for brevity.)

Next, we introduce a helper class LetterInspector with a single static method:

public static LetterMetadata inspectLetter(String letterContent);

The implementation is not shown here, as it is not relevant to the example. Conceptually, this method analyzes the letter content and returns metadata describing which structural elements are already present.

Conditional Stage Execution

We now modify the business logic method as follows:

public String handleLetterFormatting(String content, DocumentType documentType) {
 LetterMetadata metadata = LetterInspector.inspectLetter(content);
 if(!metadata.isGreetingPresent()) {
   content = preformatLetter(content, documentType);
   metadata = LetterInspector.inspectLetter(content); 
 }
 if(!metadata.isSignaturePresent()) {
   content = formatLetter(content, documentType);
   metadata = LetterInspector.inspectLetter(content);
 }
 if(!metadata.isHeaderPresent()) {
   content = postFormatLetter(content, documentType);
 }
 return content;
}

With this our flow looks like this:

With this approach, each stage is executed only if required, based on:

The current content state
The result of previously executed stages

The workflow dynamically adapts at runtime while remaining fully deterministic and centrally controlled.

Architectural Implications

This example demonstrates that:

Conditional workflow logic resides entirely in LetterFormattingManager
Stage implementations remain completely unaware of the workflow
Factories and their registered implementations are untouched

Type Extensibility

This section will demonstrate how to add a new letter type (or more generically new concrete implementation) to the framework. Throughout this article I referred to 3 letter types in our example progect (MgntUtilsUsage repo: https://github.com/michaelgantman/MgntUtilsUsage). The types are: LEGAL, INTERNAL, CUSTOMER. However, if you look at the repo it comes with 4 letter types where FINANCE is the additional, not mentioned type. The truth is that as I developed my project I originally had only 3 types, and added the 4th (FINANCE) at a later stage to showcase how the new type could be added. So, I will simply list here all the changes that were made to add the additional letter type. Here they are:

The enum com.example.stamboot.letterformatting.DocumentType (https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/DocumentType.java) was modified. The additional enum value FINANCE was added (See Line #7 in the source code) Here is the modified enum:

public enum DocumentType {
 LEGAL, 
 INTERNAL,
 CUSTOMER,
 FINANCE; //This is the newly added line
}

2. For each stage a new concrete implementation class was added.

IMPORTANT NOTE: Each new implementation MUST use the newly added FINANCE Letter type value as a custom key for registration in its stage factory via the superclass constructor invocation:

super(DocumentType.FINANCE.toString());

- For pre-formatting stage the new class is: com.example.stamboot.letterformatting.preformat.implementations.FinancialDocumentPreformatter (See source code here: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/preformat/implementations/FinancialDocumentPreformatter.java See line 13 — the registration with FINANCE key)

- For formatting stage the new class is: com.example.stamboot.letterformatting.format.implementations.FinancialDocumentFormatter (Source code: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/format/implementations/FinancialDocumentFormatter.java See line 13 — the registration with FINANCE key)

- For post-formatting stage the new class is: com.example.stamboot.letterformatting.postformat.implementations.FinancialDocumentPostFormatter (Source code: https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/postformat/implementations/FinancialDocumentPostFormatter.java See line 15 — the registration with FINANCE key)

This is it! No change anywhere else, just add new implementations for each stage and it is automatically picked up, registered and ready to use.

Stage Extensibility

Adding a new stage is a little bit more work than adding a new type, but it is still very structured and isolated modification that does not involve changing pre-existing structure. Back in the “Complete multi-stage workflow architecture example” section of this article in the “The Core Design Idea” paragraph we stated the following:

Each processing stage is implemented as an independent, self-populating factory.

So, adding another stage is just creating another self-populating factory set. In the same section on the next paragraph “Architectural Diagram of the Multi-Stage Letter Formatting System” there is a diagram showing 3 independent sets of self-populating factories. If you look at the code in our MgntUtilsUsage repository each such set is implemented in a separate package:

com.example.stamboot.letterformatting.preformat (see https://github.com/michaelgantman/MgntUtilsUsage/tree/main/src/main/java/com/example/stamboot/letterformatting/preformat)
com.example.stamboot.letterformatting.format (see https://github.com/michaelgantman/MgntUtilsUsage/tree/main/src/main/java/com/example/stamboot/letterformatting/format)
com.example.stamboot.letterformatting.postformat (see https://github.com/michaelgantman/MgntUtilsUsage/tree/main/src/main/java/com/example/stamboot/letterformatting/postformat)

So, to add a new stage we just need to create another package with self-populating factory set that mimics the same structure as the 3 existing ones. Let’s demonstrate this with a concrete example by introducing a new ps-formatting stage that appends a ‘P.S.’ section after the signature. In order to create this stage, we will

Create a new package: com.example.stamboot.letterformatting.psformat In this package we will create the following structure:

2. Create a factory class com.example.stamboot.letterformatting.psformat.LetterPsFormatterFactory. The code is omitted as it is practically identical to factories in the other 3 stages.

3. Create com.example.stamboot.letterformatting.psformat.LetterPsFormatter interface:

public interface LetterPsFormatter {
      String psFormatDocument(String doc);
}

4. Create com.example.stamboot.letterformatting.psformat.BaseLetterPsFormatter abstract class

public abstract class BaseLetterPsFormatter extends BaseEntity<BaseLetterPsFormatter> implements LetterPsFormatter {

    private static final String FACTORY_TYPE =
      BaseLetterPsFormatter.class.getSimpleName();
    static {
        init(FACTORY_TYPE, LetterPsFormatterFactory.getFactoryInstance());
    }

    public BaseLetterPsFormatter() {
        super(FACTORY_TYPE);
    }

    public BaseLetterPsFormatter(String customName) {
        super(FACTORY_TYPE, customName);
    }
}

5. Create a new package com.example.stamboot.letterformatting.psformat. implementations

In this package create 4 concrete implementation classes — one per each letter type.
Important note: just like in “Type Extensibility” section Each new implementation MUST use appropriate Letter type value as a custom key for registration in its stage factory via the superclass constructor invocation. For example for FINANCE implementation use this invocation.

super(DocumentType.FINANCE.toString());

We will show just one class and leave the rest of the implementations for readers as they are very similar as you can see in previous stages implementations. We will show the implementation for FINANCE

package com.example.stamboot.letterformatting.psformat.implementations;
//import statements are omitted
@Component
@Lazy(false)
public class FinancialDocumentPsFormatter extends BaseLetterPsFormatter {

    public FinancialDocumentPsFormatter() {
        super(DocumentType.FINANCE.toString());
    }

    @Override
    public String psFormatDocument (String doc) {
        return doc + “\n\nP.S. here comes P.S. content”;
    }
}

6. Now we are done with adding the ps-formatting stage and we just need to use it. So, let’s assume that we want to add this stage as the last one after post-formatting stage. So we will need to modify our Business Logic. So we go to our LetterFormattingManager class (https://github.com/michaelgantman/MgntUtilsUsage/blob/main/src/main/java/com/example/stamboot/letterformatting/bl/LetterFormattingManager.java) and modify the handleLetterFormatting method as follows

public String handleLetterFormatting(String content, DocumentType documentType) {
 String preformattedContent = preformatLetter(content, documentType);
 String formattedContent = formatLetter(preformattedContent, documentType);
 String postFormattedString = postFormatLetter(formattedContent, documentType);
 String psFormattedString = psFormatLetter(postFormattedString);
 return psFormattedString;
}

There are two simple private helper methods that need to be added but they are omitted here as they are trivial.

So, this is it. This demonstrates that stage extensibility is achieved by composition rather than modification: new stages are introduced as independent factory sets, and the workflow evolves explicitly through business logic without impacting existing stages or implementations.

Unlike type extensibility, adding a new stage necessarily requires modifying the business logic, because the workflow must explicitly decide when and where the new stage is executed.

In Conclusion

In this article, we examined a lightweight yet powerful infrastructure for building extensible multi-stage workflows across multiple data types. Using the self-populating factory mechanism provided by the MgntUtils library, we demonstrated how a system can be designed to support:

Adding new data types without modifying existing code
Adding new processing stages in an isolated and predictable manner
Reordering and conditionally executing stages based on runtime logic
Centralized workflow control that remains completely decoupled from implementation details

The key architectural insight is the combination of independent self-populating factories, a shared key convention, and a centralized workflow manager. This approach eliminates the need for switch statements, manual registries, and intrusive configuration while keeping the system easy to extend and reason about.

Although the examples in this article focus on letter formatting, the same design applies to a wide range of domains, including validation pipelines, ETL workflows, document generation systems, and other multi-step processing engines.

If you find this approach useful, consider exploring and using the MgntUtils open-source library in your own projects:

GitHub repository: https://github.com/michaelgantman/Mgnt
Maven Central: https://central.sonatype.com/artifact/com.github.michaelgantman/MgntUtils
Javadoc: https://michaelgantman.github.io/Mgnt/docs/

The complete runnable example discussed in this article is available here:

MgntUtilsUsage example project: https://github.com/michaelgantman/MgntUtilsUsage

Feedback, suggestions, and contributions are welcome — feel free to share your experience, open issues, or contribute improvements to help evolve the library further.

Java Stacktrace filtering utility.

Michael Gantman — Thu, 05 Jun 2025 20:32:32 +0000

Introduction: Problem definition and sugested solution idea

This article is a a technical article for Java developers that suggest a solution for a major pain point of analyzing very long stacktraces searching for meaningful information in a pile of frameworks related stacktrace lines. The core idea of the solution is to provide a capability to intelligently filter out irrelevant parts of the stacktrace without losing important and meaningful information. The benefits are two-fold:

Making stacktrace much easier to read and analyze, making it more clear and concise
Making stacktrace much shorter and saving space

Stacktrace is a lifesaver when debugging or trying to figure out what went wrong in your application. However, when working with logs on the server side you can come across huge stacktrace that contains the longest useless tail of various frameworks and Application Server related packages. And somewhere in this pile, there are several lines of a relevant trace and they may be in different segments separated by useless information. It becomes a nightmare to search for a relevant stuff. Here is a link that describes the same problem with real-life examples (not for the fainthearted :)) https://dzone.com/articles/filtering-stack-trace-hell

Despite the obvious value of this capability, the Java ecosystem offers very few, if any, libraries with built-in support for stacktrace filtering out of the box. Developers often resort to writing custom code or regex filters to parse and shorten stacktraces—an ad-hoc and fragile solution that’s hard to maintain and reuse. Some logging frameworks such as Log4J and Logback might provide basic filtering options based on log levels or format, but they don't typically allow for the granular control over stack trace

How the solution works and how to use it
The Utility is provided as part of Open Source Java library called MgntUtils. It is available on Maven Central as well as on Github (including source code and Javadoc). Here is a direct link to Javadoc. The solution implementation is provided in class TextUtils in method getStacktrace() with several overridden signatures. Here is the direct Javadoc link to getStacktrace() method with detailed explanation of the functionality.

So the solution is that user can set a relevant package prefix (or multiple prefixes srting with MgntUtils library version 1.7.0.0) of the packages that are relevant. The stacktrace filtering will work based on the provided prefixes in the following way:

The error message is always printed.
The first lines of the stacktrace are always printed as well until the first line matching one of the prefixes is found.
Once the first line matching one of the prefixes is found this and all the following lines that ARE matching one of the prefixes will be printed
Once the first line that is NOT matching any of the prefixes is found - this first non-matching line is printed but all the following non-matching lines are replaced with single line ". . ."
If at some point another line matching one of the prefixes is found this and all the following matching lines will be printed. and now the logic just keep looping between points 4 and 5

Stacktrace could consist of several parts such as the main section, "Caused by" section and "Supressed" Section. Each part is filtered as a separate section according to the logic described above.

Also, the same utility (starting from version 1.5.0.3) has method getStacktrace() that takes CharSequence interface instead of Throwable and thus allows to filter and shorten stacktrace stored as a string the same way as a stacktrace extracted from Throwable. So, essentially stacktraces could be filtered "on the fly" at run time or later on from any text source such as a log. (Just to clarify - the utility does not support parsing and modifying the entire log file. It supports filtering just a stacktrace that as passed as a String. So if anyone wants to filter exceptions in a log file they would have to parse the log file and extract stacktrace(s) as separate strings and then can use this utility to filter each individual stacktrace).

Here is a usage example. Note that the first parameter of getStacktrace() method in this example is Throwable. Let's say your company's code always resides in packages that start with "com.plain.*" So you set such a prefix and do this

logger.info(TextUtils.getStacktrace(e,true,"com.plain."));

this will filter out all the useless parts of the trace according to the logic described above leaving you with very concise stacktrace. Also, user can pre-set the prefix (or multiple prefixes) and then just use the convenience method

TextUtils.getStacktrace(e);

It will do the same. To preset the prefix just use the method

TextUtils.setRelevantPackage("com.plain.");

Method setRelevantPackage() supports setting multiple prefixes, so you can use it like this:

TextUtils.setRelevantPackage("com.plain.", "com.encrypted.");

If you would like to pre-set this value by configuration then starting with the library version 1.1.0.1 you can set Environment Variable "MGNT_RELEVANT_PACKAGE" or System Property "mgnt.relevant.package" to value "com.plain." and the property will be set to that value without you invoking method TextUtils.setRelevantPackage("com.plain."); explicitly in your code. Note that System property value would take precedence over the environment variable if both were set. Just a reminder that with System property you can add it in your command line using -D flag:

"-Dmgnt.relevant.package=com.plain."

Note that System property value would take precedence over environment variable if both are set. IMOPRTANT: Note that for both environment variable and system property if multiple prefixes needed to be set than list them one after another separated by semicolon (;) For Example: "com.plain.;com.encrypted."

There is also a flexibility here: If you do have pre-set prefixes but for some particular case you would wish to filter according to different set of prefixes you can use the method signature that takes prefixes as parameter and it will override the globally pre-set prefixes just for this time:

logger.info(TextUtils.getStacktrace(e,true,"org.alternative."));

Here is an example of filtered vs unfiltered stacktrace: you will get a following filtered stacktrace:

com.plain.BookListNotFoundException: Internal access error
at com.plain.BookService.listBooks()
at com.plain.BookService$$FastClassByCGLIB$$e7645040.invoke()
at net.sf.cglib.proxy.MethodProxy.invoke()
...
at com.plain.LoggingAspect.logging()
at sun.reflect.NativeMethodAccessorImpl.invoke0()
...
at com.plain.BookService$$EnhancerByCGLIB$$7cb147e4.listBooks()
at com.plain.web.BookController.listBooks()

instead of unfiltered version

com.plain.BookListNotFoundException: Internal access error
at com.plain.BookService.listBooks()
at com.plain.BookService$$FastClassByCGLIB$$e7645040.invoke()
at net.sf.cglib.proxy.MethodProxy.invoke()
at org.springframework.aop.framework.Cglib2AopProxy$CglibMethodInvocation.invokeJoinpoint()
at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed()
at org.springframework.aop.aspectj.MethodInvocationProceedingJoinPoint.proceed()
at com.plain.LoggingAspect.logging()
at sun.reflect.NativeMethodAccessorImpl.invoke0()
at sun.reflect.NativeMethodAccessorImpl.invoke()
at sun.reflect.DelegatingMethodAccessorImpl.invoke()
at java.lang.reflect.Method.invoke()
at org.springframework.aop.aspectj.AbstractAspectJAdvice.invokeAdviceMethodWithGivenArgs()
at org.springframework.aop.aspectj.AbstractAspectJAdvice.invokeAdviceMethod()
at org.springframework.aop.aspectj.AspectJAroundAdvice.invoke()
at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed()
at org.springframework.aop.interceptor.AbstractTraceInterceptor.invoke()
at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed()
at org.springframework.transaction.interceptor.TransactionInterceptor.invoke()
at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed()
at org.springframework.aop.interceptor.ExposeInvocationInterceptor.invoke()
at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed()
at org.springframework.aop.framework.Cglib2AopProxy$DynamicAdvisedInterceptor.intercept()
at com.plain.BookService$$EnhancerByCGLIB$$7cb147e4.listBooks()
at com.plain.web.BookController.listBooks()

In Conclusion
The MgntUtils library is written and maintained by me. If you require any support or have any question or would like a short demo you can contact me through LinkedIn - send me a message or request connection, or send me email directly at michael_gantman@yahoo.com. I will do my best to respond