1 package com.acumenvelocity.ath.common.exception;
2
3 import org.slf4j.helpers.MessageFormatter;
4
5 import com.acumenvelocity.ath.common.Log;
6
7 /**
8 * Runtime exception variant of {@link AthException} for unchecked exceptions
9 * in the ATH framework.
10 *
11 * <p>
12 * This class should be used for exceptions that don't need to be declared
13 * in method signatures but still require the same structured handling and
14 * logging as checked exceptions.
15 * </p>
16 *
17 * <p>
18 * <b>Usage Guidelines:</b>
19 * </p>
20 * <ul>
21 * <li>Use for programming errors that shouldn't be caught</li>
22 * <li>Use for exceptions that indicate system configuration issues</li>
23 * <li>Use when exception handling would clutter the code unnecessarily</li>
24 * </ul>
25 *
26 * @author Acumen Velocity
27 * @version 1.0
28 * @since 1.0
29 */
30 public class AthRuntimeException extends RuntimeException {
31
32 private static final long serialVersionUID = 8132618370851732660L;
33
34 /**
35 * Creates a new AthRuntimeException with a formatted message.
36 *
37 * @param format the message format string with {} placeholders
38 * @param args the arguments to substitute into the format string
39 */
40 public AthRuntimeException(String format, Object... args) {
41 super(MessageFormatter.arrayFormat(format, args).getMessage());
42 }
43
44 /**
45 * Creates a new AthRuntimeException with a given parent exception cause.
46 *
47 * @param cause the underlying exception that caused this exception
48 */
49 public AthRuntimeException(Throwable cause) {
50 super(cause);
51 }
52
53 /**
54 * Creates a new AthRuntimeException with a given message and parent exception cause.
55 *
56 * @param cause the underlying exception that caused this exception
57 * @param message the descriptive text of the exception message
58 */
59 public AthRuntimeException(Throwable cause, String message) {
60 super(message, cause);
61 }
62
63 /**
64 * Creates a new AthRuntimeException with a formatted message and cause.
65 *
66 * @param cause the underlying exception that caused this exception
67 * @param format the message format string with {} placeholders
68 * @param args the arguments to substitute into the format string
69 */
70 public AthRuntimeException(Throwable cause, String format, Object... args) {
71 super(MessageFormatter.arrayFormat(format, args).getMessage(), cause);
72 }
73
74 /**
75 * Logs an error message with cause and throws an AthRuntimeException.
76 *
77 * @param loggingClass the class where the error occurred (for logging context)
78 * @param cause the underlying exception that caused this error
79 * @param format the error message format string with {} placeholders
80 * @param args the arguments to substitute into the format string
81 * @throws AthRuntimeException always throws an AthRuntimeException after logging
82 */
83 public static void logAndThrow(Class<?> loggingClass,
84 Throwable cause, String format, Object... args) {
85 // Log the error with cause and context
86 Log.error(loggingClass, cause, format, args);
87 // Throw the runtime exception with formatted message and cause
88 throw new AthRuntimeException(cause,
89 MessageFormatter.arrayFormat(format, args).getMessage());
90 }
91
92 /**
93 * Logs an error with just the cause and throws an AthRuntimeException.
94 *
95 * @param loggingClass the class where the error occurred (for logging context)
96 * @param cause the underlying exception that caused this error
97 * @throws AthRuntimeException always throws an AthRuntimeException after logging
98 */
99 public static void logAndThrow(Class<?> loggingClass, Throwable cause) {
100 // Log the error with the cause's string representation
101 Log.error(loggingClass, cause, cause.toString());
102 // Throw the runtime exception with the cause included
103 throw new AthRuntimeException(cause, cause.toString());
104 }
105
106 /**
107 * Logs an error message and throws an AthRuntimeException.
108 *
109 * @param loggingClass the class where the error occurred (for logging context)
110 * @param format the error message format string with {} placeholders
111 * @param args the arguments to substitute into the format string
112 * @throws AthRuntimeException always throws an AthRuntimeException after logging
113 */
114 public static void logAndThrow(Class<?> loggingClass,
115 String format, Object... args) {
116 // Log the error with appropriate context
117 Log.error(loggingClass, format, args);
118 // Throw the runtime exception with a generic Exception as cause
119 throw new AthRuntimeException(new Exception(),
120 MessageFormatter.arrayFormat(format, args).getMessage());
121 }
122 }