Package com.broadleafcommerce.common.error.validation.web

Class ExceptionHandlerUtils

java.lang.Object

com.broadleafcommerce.common.error.validation.web.ExceptionHandlerUtils

public class ExceptionHandlerUtils
extends Object

Centrally manages secure exception logging and correlation ID extraction for standard ApiError responses.

Author:

BroadleafCommerce

Constructor Summary

Constructors

Constructor	Description
ExceptionHandlerUtils(BroadleafExceptionHandlerProperties properties)

Method Summary

Modifier and Type	Method	Description
org.springframework.http.ResponseEntity<ApiError>	buildResponseEntityAndLogException(String type, String title, org.springframework.http.HttpStatus status, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log)	Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs.
org.springframework.http.ResponseEntity<ApiError>	buildResponseEntityAndLogException(String type, String title, org.springframework.http.HttpStatus clientStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log, org.slf4j.event.Level logLevelOverride)	Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs.
org.springframework.http.ResponseEntity<ApiError>	buildResponseEntityAndLogException(String type, String title, org.springframework.http.HttpStatus clientStatus, org.springframework.http.HttpStatus downstreamStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log)	Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs.
org.springframework.http.ResponseEntity<ApiError>	buildResponseEntityAndLogException(String type, String title, org.springframework.http.HttpStatus clientStatus, org.springframework.http.HttpStatus downstreamStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log, org.slf4j.event.Level logLevelOverride)	Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs.
<A extends ApiError> org.springframework.http.ResponseEntity<A>	buildResponseEntityAndLogException(BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory, String title, org.springframework.http.HttpStatus clientStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log)	Integrates, sanitizes, and logs an already constructed custom ApiError subclass using a functional factory with central log correlation and tracing.
<A extends ApiError> org.springframework.http.ResponseEntity<A>	buildResponseEntityAndLogException(BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory, String title, org.springframework.http.HttpStatus clientStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log, org.slf4j.event.Level logLevelOverride)	Integrates, sanitizes, and logs an already constructed custom ApiError subclass using a functional factory with central log correlation and tracing.
protected org.slf4j.event.Level	determineLogLevel(org.springframework.http.HttpStatusCode clientStatus, org.springframework.http.HttpStatusCode downstreamStatus, org.slf4j.event.Level logLevelOverride)	Determines the final logging level based on the optional override level or dynamic downstream/client status.
protected String	extractTraceId()	Extract active tracing ID from MDC context using configured prioritised trace keys lookup.
protected String	getRequestUrl(org.springframework.web.context.request.WebRequest request)	Extract active client HTTP request URL from WebRequest context.
protected void	logAtLevel(org.slf4j.Logger logger, org.slf4j.event.Level level, String errorRef, org.springframework.http.HttpStatusCode clientStatus, org.springframework.http.HttpStatusCode downstreamStatus, String requestUrl, String title, Throwable ex)	Logs the detailed exception trace internally at the provided severity level.
protected <A extends ApiError> org.springframework.http.ResponseEntity<A>	processAndLogException(BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory, String type, String title, org.springframework.http.HttpStatus clientStatus, org.springframework.http.HttpStatus downstreamStatus, Throwable ex, org.springframework.web.context.request.WebRequest request, org.slf4j.Logger log, org.slf4j.event.Level logLevelOverride)	Core consolidated implementation of exception logging, sanitization, and correlation.
org.slf4j.event.Level	resolveLogLevelOverride(org.slf4j.event.Level legacyLevel, Throwable ex)	Resolves the legacy or dynamic operational logging severity based on backward-compatibility properties.
String	resolveTitle(String newTitle, String legacyTitle, Throwable ex)	Resolves the legacy or sanitized error message title based on backward-compatibility properties.
String	resolveType(String newType, String legacyType, Throwable ex)	Resolves the legacy or standardized error type code based on backward-compatibility properties.
protected boolean	shouldLogError(org.springframework.http.HttpStatusCode status)	Determines whether the given HTTP status warrants ERROR severity logging.
protected boolean	shouldLogWarn(org.springframework.http.HttpStatusCode status)	Determines whether the given HTTP status warrants WARN severity logging.
protected boolean	shouldUseLegacyTypeAndTitleFormat(Throwable ex)	Determines whether the legacy format (type/title override) should be applied for a specific exception class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ExceptionHandlerUtils

public ExceptionHandlerUtils(BroadleafExceptionHandlerProperties properties)

Method Details

buildResponseEntityAndLogException

public org.springframework.http.ResponseEntity<ApiError> buildResponseEntityAndLogException(String type,
 String title,
 org.springframework.http.HttpStatus status,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log)

Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs. Log level is dynamically adjusted to minimize production alert fatigue.

Parameters:

type - the error type string

title - the error message title

status - the HttpStatusCode of the response

ex - the caught exception

request - the active WebRequest of the handler

log - the SLF4J logger of the calling ExceptionAdvisor class

Returns:

a ResponseEntity wrapping the sanitized ApiError

buildResponseEntityAndLogException

public org.springframework.http.ResponseEntity<ApiError> buildResponseEntityAndLogException(String type,
 String title,
 org.springframework.http.HttpStatus clientStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log,
 @Nullable
 org.slf4j.event.Level logLevelOverride)

Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs. Log level can be overridden explicitly by passing logLevelOverride, or dynamically resolved if null.

Parameters:

type - the error type string

title - the error message title

clientStatus - the HttpStatusCode of the response returned to the client

ex - the caught exception

request - the active WebRequest of the handler

log - the SLF4J logger of the calling ExceptionAdvisor class

logLevelOverride - the optional explicit log level override

Returns:

a ResponseEntity wrapping the sanitized ApiError

buildResponseEntityAndLogException

public org.springframework.http.ResponseEntity<ApiError> buildResponseEntityAndLogException(String type,
 String title,
 org.springframework.http.HttpStatus clientStatus,
 @Nullable
 org.springframework.http.HttpStatus downstreamStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log)

Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs. Log level is dynamically adjusted to minimize production alert fatigue based on the DOWNSTREAM originating status, while returning the CLIENT status code to the consumer.

Parameters:

type - the error type string

title - the error message title

clientStatus - the HttpStatusCode of the response returned to the client

downstreamStatus - the originating HttpStatusCode of the error

ex - the caught exception

request - the active WebRequest of the handler

log - the SLF4J logger of the calling ExceptionAdvisor class

Returns:

a ResponseEntity wrapping the sanitized ApiError

buildResponseEntityAndLogException

public org.springframework.http.ResponseEntity<ApiError> buildResponseEntityAndLogException(String type,
 String title,
 org.springframework.http.HttpStatus clientStatus,
 @Nullable
 org.springframework.http.HttpStatus downstreamStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log,
 @Nullable
 org.slf4j.event.Level logLevelOverride)

Builds a sanitized ApiError and logs the detailed exception internally with log correlation IDs. Log level can be overridden explicitly by passing logLevelOverride, or dynamically resolved if null.

Parameters:

type - the error type string

title - the error message title

clientStatus - the HttpStatusCode of the response returned to the client

downstreamStatus - the originating HttpStatusCode of the error

ex - the caught exception

request - the active WebRequest of the handler

log - the SLF4J logger of the calling ExceptionAdvisor class

logLevelOverride - the optional explicit log level override

Returns:

a ResponseEntity wrapping the sanitized ApiError

buildResponseEntityAndLogException

public <A extends ApiError>
org.springframework.http.ResponseEntity<A> buildResponseEntityAndLogException(BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory,
 @Nullable
 String title,
 org.springframework.http.HttpStatus clientStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log)

Integrates, sanitizes, and logs an already constructed custom ApiError subclass using a functional factory with central log correlation and tracing.

Parameters:

errorFactory - the functional factory to construct the custom ApiError with the safe title

title - the unescaped title for raw internal logging and sanitization

clientStatus - the HttpStatusCode of the response returned to the client

ex - the caught exception

request - the active WebRequest

log - the SLF4J logger of the calling exception advisor

Returns:

a ResponseEntity wrapping the populated ApiError

buildResponseEntityAndLogException

public <A extends ApiError>
org.springframework.http.ResponseEntity<A> buildResponseEntityAndLogException(BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory,
 @Nullable
 String title,
 org.springframework.http.HttpStatus clientStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log,
 @Nullable
 org.slf4j.event.Level logLevelOverride)

Integrates, sanitizes, and logs an already constructed custom ApiError subclass using a functional factory with central log correlation and tracing.

Parameters:

errorFactory - the functional factory to construct the custom ApiError with the safe title

title - the unescaped title for raw internal logging and sanitization

clientStatus - the HttpStatusCode of the response returned to the client

ex - the caught exception

request - the active WebRequest

log - the SLF4J logger of the calling exception advisor

logLevelOverride - the optional explicit log level override

Returns:

a ResponseEntity wrapping the populated ApiError

processAndLogException

protected <A extends ApiError>
org.springframework.http.ResponseEntity<A> processAndLogException(@Nullable
 BiFunction<String,org.springframework.http.HttpStatus,A> errorFactory,
 @Nullable
 String type,
 @Nullable
 String title,
 org.springframework.http.HttpStatus clientStatus,
 @Nullable
 org.springframework.http.HttpStatus downstreamStatus,
 Throwable ex,
 org.springframework.web.context.request.WebRequest request,
 org.slf4j.Logger log,
 @Nullable
 org.slf4j.event.Level logLevelOverride)

Core consolidated implementation of exception logging, sanitization, and correlation.

resolveType

public String resolveType(String newType,
 String legacyType,
 Throwable ex)

Resolves the legacy or standardized error type code based on backward-compatibility properties.

Parameters:

newType - the new standardized error type

legacyType - the old legacy error type

ex - the caught exception

Returns:

the resolved error type string

resolveTitle

public String resolveTitle(String newTitle,
 String legacyTitle,
 Throwable ex)

Resolves the legacy or sanitized error message title based on backward-compatibility properties.

Parameters:

newTitle - the new sanitized error message title

legacyTitle - the old legacy error message title

ex - the caught exception

Returns:

the resolved error message title string

shouldUseLegacyTypeAndTitleFormat

protected boolean shouldUseLegacyTypeAndTitleFormat(Throwable ex)

Determines whether the legacy format (type/title override) should be applied for a specific exception class.

Parameters:

ex - the exception to evaluate

Returns:

true if the legacy format should be applied

resolveLogLevelOverride

@Nullable
public org.slf4j.event.Level resolveLogLevelOverride(org.slf4j.event.Level legacyLevel,
 Throwable ex)

Resolves the legacy or dynamic operational logging severity based on backward-compatibility properties.

Parameters:

legacyLevel - the old legacy Level severity to override with

ex - the caught exception

Returns:

the resolved Level severity, or null if dynamic mapping should apply

determineLogLevel

protected org.slf4j.event.Level determineLogLevel(org.springframework.http.HttpStatusCode clientStatus,
 @Nullable
 org.springframework.http.HttpStatusCode downstreamStatus,
 @Nullable
 org.slf4j.event.Level logLevelOverride)

Determines the final logging level based on the optional override level or dynamic downstream/client status.

Parameters:

clientStatus - the client response HttpStatusCode

downstreamStatus - the downstream originating HttpStatusCode, if present

logLevelOverride - the explicit Level override, if provided

Returns:

the final Level severity to log at

shouldLogError

protected boolean shouldLogError(org.springframework.http.HttpStatusCode status)

Determines whether the given HTTP status warrants ERROR severity logging.

This behavior is driven by the following property:

• broadleaf.error.exception-handler.logging.error-statuses: Custom HTTP status integers configured via BroadleafExceptionHandlerProperties.Logging.getErrorStatuses() to trigger ERROR logging in addition to all default 5xx Server Errors.

Parameters:

status - the HttpStatusCode to evaluate

Returns:

true if the status warrants ERROR severity logging

shouldLogWarn

protected boolean shouldLogWarn(org.springframework.http.HttpStatusCode status)

Determines whether the given HTTP status warrants WARN severity logging.

This behavior is driven by the following property:

• broadleaf.error.exception-handler.logging.warn-statuses: Custom HTTP status integers configured via BroadleafExceptionHandlerProperties.Logging.getWarnStatuses() to trigger WARN logging instead of the default DEBUG level. Default contains: 401, 403, 409, and 429.

Parameters:

status - the HttpStatusCode to evaluate

Returns:

true if the status warrants WARN severity logging

logAtLevel

protected void logAtLevel(org.slf4j.Logger logger,
 org.slf4j.event.Level level,
 String errorRef,
 org.springframework.http.HttpStatusCode clientStatus,
 @Nullable
 org.springframework.http.HttpStatusCode downstreamStatus,
 String requestUrl,
 @Nullable
 String title,
 Throwable ex)

Logs the detailed exception trace internally at the provided severity level.

Parameters:

logger - the active class Logger to write with

level - the determined Level severity to log at

errorRef - the unique errorRef UUID of the log correlation

clientStatus - the client response HttpStatusCode

downstreamStatus - the downstream originating HttpStatusCode, if present

requestUrl - the request Url extracted from the context

title - the escaped error message title summary

ex - the caught exception to log the trace for

extractTraceId

@Nullable
protected String extractTraceId()

Extract active tracing ID from MDC context using configured prioritised trace keys lookup.

This behavior is driven by the following property:

• broadleaf.error.exception-handler.logging.trace-id-mdc-keys: An ordered list of MDC trace keys configured via BroadleafExceptionHandlerProperties.Logging.getTraceIdMdcKeys() (such as traceId, trace_id, dd.trace_id, etc.).

Returns:

the active APM Trace ID, or null if none is bound

getRequestUrl

protected String getRequestUrl(org.springframework.web.context.request.WebRequest request)

Extract active client HTTP request URL from WebRequest context.

Parameters:

request - the active WebRequest

Returns:

the request URL string