Java 17 Recipes

9-7. Creating an Exception Class
 Problem
You want to create a new type of exception that indicates a particular event.
 Solution 1
Create a class that extends java.lang.RuntimeException to create an exception 
class that can be thrown at any time. In the following code, a class identified by 
IllegalChatServerException extends RuntimeException and accepts a string as an 
argument to the constructor. The exception is then thrown when a specified event occurs 
within the code.
class IllegalChatServerException extends RuntimeException {
IllegalChatServerException(String message) {
super(message);
}
}
private void disconnectChatServer(Object chatServer) {
if (chatServer == null) throw new IllegalChatServerException("Chat 
server is empty");
}
 Solution 2
Create a class that extends java.lang.Exception to generate a checked exception class. 
A checked exception is required to be caught or rethrown up the stack. In the following 
example, a class identified as ConnectionUnavailableException extends java.
lang.Exception and accepts a string as an argument to the constructor. The checked 
exception is then thrown by a method in the code.
class ConnectionUnavailableException extends Exception {
ConnectionUnavailableException(String message) {
super(message);
}
}
Chapter 9 exCeptions and Logging

---

344
private void sendChat(String chatMessage) throws 
ConnectionUnavailableException {
if (chatServer == null)
throw new ConnectionUnavailableException("Can't find the
chat server");
}
The main method is as follows.
Object chatServer = null;
public static void main (String[] args) {
Recipe9_7 recipe = new Recipe9_7();
recipe.start();
}
private void start() {
try {
sendChat("Hello, how are you?");
} catch (ConnectionUnavailableException e) {
System.out.println("Caught a connection unavailable Exception!");
}
disconnectChatServer(chatServer);
}
 How It Works
Sometimes there is a requirement to create a custom exception, especially when 
creating an API. The usual recommendation is to use one of the available Exception 
classes provided by the JDK. For example, use IOException for I/O-related issues or 
IllegalArgumentException for illegal parameters. If there isn’t a JDK exception that fits 
cleanly, you can always extend java.lang.Exception or java.lang.RuntimeException 
and implement its own family of exceptions.
Depending on the base class, creating an Exception class is fairly straightforward. 
Extending RuntimeException allows you to throw the resulting exception any 
time without requiring it to be caught up in the stack. This is advantageous in that 
RuntimeException is a more lax contract to work with, but throwing such an exception 
Chapter 9 exCeptions and Logging

---

345
can lead to thread termination if the exception is not caught. Extending Exception 
instead allows you to force any code that throws the exception to handle it within a catch 
clause. The checked exception is then forced by contract to implement a catch handler, 
potentially avoiding a thread termination.
In practice, we discourage extending RuntimeException because it can lead to poor 
exception handling. Our rule of thumb is that if it’s possible to recover from an exception, 
you should create the associated exception class by extending Exception. If a developer 
cannot reasonably recover from the exception (i.e., NullPointerException), extend 
RuntimeException.