Package io.github.venkateshamurthy.exceptional.exceptions

Class CommonRuntimeException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

io.github.venkateshamurthy.exceptional.exceptions.CommonRuntimeException

All Implemented Interfaces:

Serializable

public class CommonRuntimeException
extends RuntimeException
implements Serializable

CommonRuntimeException is a unified runtime exception class that can be used across the project to encapsulate error information in a structured and consistent format.

This class extends RuntimeException and adds contextual fields such as:

• code - Application or domain-specific error code
• detailedMessage - Detailed, formatted explanation of the error
• timeStamp - UTC timestamp when the error was created
• httpStatus - The HttpStatus representing the error category

The class supports message formatting with templates, placeholder substitution, and structured logging to simplify debugging and monitoring.

Example usage:

 throw ExceptionCodes.CREDENTIAL_MISSING
     .toCommonRTE(CREDENTIAL_MISSING.getDescription(),
     "Missing or invalid credential ID: {}", request.getCredentialId())
     .logInfo();
 

Another example:

 throw ExceptionCodes.CREDENTIAL_MISSING.toCommonRTE(
      new OverlappingFileLockException(), "Missing or bad credentials",
     "Missing or invalid credential ID: {credentialId}", Map.of("credentialId", request.getCredentialId()))
     .setHttpStatus(HttpStatus.BAD_REQUEST)
     .logInfo();
 

 throw ExceptionCodes.CREDENTIAL_MISSING.toCommonRTE(
      ExceptionCode.NULL_CAUSE, "Missing or bad credentials",
      "Missing or invalid credential ID: {credentialId}", request.getCredentialId())
      .setHttpStatus(HttpStatus.BAD_REQUEST)
      .logInfo();
  *

Since:

1.0

Author:

venkateshamurthy

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected static final Supplier<ZonedDateTime>	NOW	A supplier of current instant.

Constructor Summary

Constructors

Constructor	Description
CommonRuntimeException(String message)	Constructs a new CommonRuntimeException with the specified message.
CommonRuntimeException(String message, Throwable cause)	Constructs a new CommonRuntimeException with the specified message and cause.
CommonRuntimeException(String message, Throwable cause, String template, Object... args)	Constructs a new CommonRuntimeException with the specified message and cause.

Method Summary

Modifier and Type	Method	Description
CommonRuntimeException	detailedMessage(String template, Object... values)	Deprecated, for removal: This API element is subject to removal in a future version. in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...).
CommonRuntimeException	formatDetailedMessage(MessageFormat template, Object... values)	Deprecated, for removal: This API element is subject to removal in a future version. in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...).
CommonRuntimeException	logDebug()	Logs this exception at DEBUG level, including message, code, timestamp, details, and HTTP status.
CommonRuntimeException	logInfo()	Logs this exception’s summary at INFO level, including error code, timestamp, and details.
CommonRuntimeException	setDetailedMessage(String template, Map<String,Object> values)	Deprecated, for removal: This API element is subject to removal in a future version. in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...).
CommonRuntimeException	setFormatterStyle(DetailsMessageFormatters style)	Deprecated, for removal: This API element is subject to removal in a future version. and rendered effect-less in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...).

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Field Details

NOW

protected static final Supplier<ZonedDateTime> NOW

A supplier of current instant.

Constructor Details

CommonRuntimeException

public CommonRuntimeException(String message)

Constructs a new CommonRuntimeException with the specified message. Automatically sets the timestamp to current UTC time.

Parameters:

message - the exception message

CommonRuntimeException

public CommonRuntimeException(String message,
 Throwable cause)

Constructs a new CommonRuntimeException with the specified message and cause. Automatically sets the timestamp to current UTC time.

Parameters:

message - the exception message

cause - the underlying cause of this exception

CommonRuntimeException

public CommonRuntimeException(String message,
 Throwable cause,
 String template,
 Object... args)

Constructs a new CommonRuntimeException with the specified message and cause. Automatically sets the timestamp to current UTC time.

Parameters:

message - the exception message

cause - the underlying cause of this exception

template - template of details such as - SLF4J: "Error in {}" or NAMEDARGS: "Error in {phase}" or Standard JAVA:"Error in {0}"

args - var-args for details

Method Details

logInfo

public CommonRuntimeException logInfo()

Logs this exception’s summary at INFO level, including error code, timestamp, and details.

Returns:

this instance for fluent chaining

logDebug

public CommonRuntimeException logDebug()

Logs this exception at DEBUG level, including message, code, timestamp, details, and HTTP status.

Returns:

this instance for fluent chaining

setFormatterStyle

@Deprecated(since="1.5",
            forRemoval=true)
public CommonRuntimeException setFormatterStyle(DetailsMessageFormatters style)

Deprecated, for removal: This API element is subject to removal in a future version.

and rendered effect-less in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...). Sets the Message Formatting style of this instance.

Parameters:

style - an one of DetailsMessageFormatters of the message format

Returns:

this instance

detailedMessage

@Deprecated(since="1.5",
            forRemoval=true)
public CommonRuntimeException detailedMessage(String template,
 Object... values)

Deprecated, for removal: This API element is subject to removal in a future version.

in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...). Sets the detailed message by substituting values in the given template. This instance utilizes DetailsMessageFormatters.SLF4J is using as default which may be on the contrary to the desired formatter.

Parameters:

template - the message template

values - values to replace in template

Returns:

this instance with the details message updated for fluent chaining

setDetailedMessage

@Deprecated(since="1.5",
            forRemoval=true)
public CommonRuntimeException setDetailedMessage(String template,
 Map<String,Object> values)

Deprecated, for removal: This API element is subject to removal in a future version.

in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...). Sets the detailed message by replacing named placeholders in the form of {key}.

Example:

 exception.setDetailedMessage("Error in {module} at {time}", Map.of("module", "Auth", "time", "12:00 UTC"));
 

Parameters:

template - the message template with named placeholders

values - the key-value pairs for substitution

Returns:

this instance for fluent chaining

formatDetailedMessage

@Deprecated(since="1.5",
            forRemoval=true)
public CommonRuntimeException formatDetailedMessage(MessageFormat template,
 Object... values)

Deprecated, for removal: This API element is subject to removal in a future version.

in favour of using the ExceptionCode.toCommonRTE(Throwable, String, String, Object...) or with setDetailedMessage(String) method where the argument can be built by DetailsMessageFormatters.detectAndFormat(String, Object...). Sets the detailed message using a MessageFormat instance for advanced message formatting.

Parameters:

template - the MessageFormat instance

values - the argument values

Returns:

this instance for fluent chaining