Current state: Under Discussion
Discussion thread: TODO
JIRA: TODO
Java has a convention where classes extending Throwable accept the cause of the Throwable as a second argument to the constructor. org.apache.kafka.common.config.ConfigException however does not follow that convention as it has a constructor ConfigException(String name, Object value), which delegates to ConfigException(String name, Object value, String message) that in turn delegates to KafkaException(String message) . This API is brittle as developers often misuse the constructor with the intention of passing a cause as the second argument which never makes it to the stacktrace [1][2][3][4]. The cause and the throwable chain often proves useful in debugging the misconfiguration. For instance, when debugging incorrectly configured TLS in [1], it can help identify the cause of misconfiguration.
This KIP proposes the introduction of another constructor ConfigException(String message, Throwable cause) to adhere to the convention.
// Deprecate existing constructor
@Deprecated
public ConfigException(String name, Object value) {
this(name, value, null);
}
// New Constructor
public ConfigException(String message, Throwable cause) {
super(message, cause);
} |
We deprecate the existing constructor which takes an Object as the second argument and introduce a new one which accepts a Throwable as the cause instead. We also update existing usages of the former constructor as it will be marked deprecated.
JLS §15.12.2.5 [5] ensures the more specific constructor is chosen. Caution must be taken when passing null as the value of the second argument as the constructor with Throwable as the second argument would be invoked since it's more specific [6].
The compiler should help us ensure the change is safe. Existing unit tests that assert on exception message shouldn't break.
Throwable#initCause before throwing the exception at the point of instantiation. This may work for existing usages of the constructor but doesn't save future developers from running into the pitfall.