DEV Community: Victor Rentea

Presenting Exceptions to Users

Victor Rentea — Mon, 11 Jan 2021 09:46:46 +0000

Many applications have to present the errors that happen in the application to their users in a nice human-readable form. This article covers some widely used best practices on this topic.

Before we even start, let’s make it clear:

NEVER expose stack traces in your API responses

It's not only ugly but dangerous from a security point of view. Based on the line numbers in that stack trace, an attacker might infer the libraries and versions that you're using, and attack you by exploiting their known weaknesses.

Then what to show our users?

Purpose of Exception Message

The simplest idea is to display the exception message string to the users. For simple applications, this might work, but in medium-large applications, two issues arise:

First, you might want to unit-test that a certain exception was thrown. Asserting message strings will lead to brittle tests, especially when you start adding concatenating user input to those messages:

throw new IllegalArgumentException("Invalid username: " + username);

Secondly, one might argue that you're violating Model-View-Controller, because you're mixing diverging concerns in the same code: formatting the user-visible message AND detecting the business error condition.

Best Practice: Use the exception message to report any technical details about the error that might be useful for developers investigating the exception.

You can go as far as to catch an exception in a method x() and re-throw it back wrapped in another exception with a useful message that captures the key debug information from that method x(). For example you might include method arguments, any interesting id, current row index, and any other useful debug information. That's the Catch-rethrow-with-debug-message Pattern:

throw new RuntimeException("For id: " + keyDebugId, e);

You can even instantiate and throw back the same exception type you caught previously. I'm perfectly fine as long as you keep the original exception in the chain by passing it to the new exception constructor as its cause.

Using this pattern will include in your final exception stack trace all the useful debug information you need, allowing you to avoid breakpoint-debugging. 👍 I'll explain more hints on how to avoid breakpointing in a future blog post.

At the other extreme please don't write 30+ words phrases in your exception messages. They will just distract the reader: their brain will find itself staring endlessly at that nice human-friendly phrase in the middle of that difficult code. And honestly, the exception messages are the least important things to read when browsing unknown code. Keep in mind that the first thing a developer does when debugging an exception is to click through the stack trace. So keep it simple (KISS).

Best Practice Keep your exception messages concise and meaningful. Just like comments.

To sum up, I will recommend that in most cases you keep the exception message for concise debug information for developers' eyes only. User error messages should be externalized in .properties files so you can easily adjust, correct, and use UTF-8 accents without any pain.

But then how to distinguish between different error causes? In other words, what should be the translation key in that properties file?

Different Exception Subtypes

It might be tempting to start creating multiple exception subtypes, one for each business error of our application, and then distinguish between errors based on the exception type. Although fun at first, this will rapidly lead to creating hundreds of exception classes in any typical real-world applications. Clearly, that's unreasonable.

Best Practice: Only create a new exception type E1 if you use need to catch(E1) and selectively handle that particular exception type, to work-around or recover from it.

But in most applications, you almost never work-around or recover from exceptions. Instead, you typically terminate the execution of the current use-case/request by allowing the exception to bubble up to the outer layers.

Error Code Enum

The best solution to distinguish between your non-recoverable error conditions is using an error code, not the exception message, nor the exception type.

Should that error code be an int? If it were, we would need the Exception Manual at hand every time we walk through the code. Horrible scenario! But wait!

Every time in Java the range of values is finite and pre-known, we should always consider using an enum. Let's give it a first try:

public class MyException extends RuntimeException {
    public enum ErrorCode {
        GENERAL,
        BAD_CONFIG;
    }

    private final ErrorCode code;

    public MyException(ErrorCode code, Throwable cause) {
        super(cause);
        this.code = code;
    }

    public ErrorCode getCode() {
        return code;
    }
}

And then every time we encounter an issue due to bad configuration, we could do throw new MyException(ErrorCode.BAD_CONFIG, e);.

Unit tests are also more robust when using enum for Error Codes, compared to matching the String message:

// junit 4.13 or 5:
MyException e = assertThrows(MyException.class, () -> method(...));
assertThat(ErrorCode.BAD_CONFIG, e.getErrorCode());

Okay, we've sorted how to distinguish between errors, and we've mentioned that the user exception messages should be externalized in a .properties files. But who does and when does this translation? Let's see...

The Global Exception Handler

Let's write a GlobalExceptionHandler that catches our exception and translates it into a friendly message for our users. User are typically sending HTTP requests, so we'll assume a REST endpoint in a Spring Boot application, but all other major web frameworks today offer similar functionality.

@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    private final MessageSource messageSource;

    public GlobalExceptionHandler(MessageSource messageSource) {
        this.messageSource = messageSource;
    }

    @ExceptionHandler(MyException.class)
    @ResponseStatus // by default returns 500 error code
    public String handleMyException(MyException exception, HttpServletRequest request) {
        String userMessage = messageSource.getMessage(exception.getCode().name(), null, request.getLocale());
        log.error(userMessage, exception);
        return userMessage;
    }
}

The framework will pass to this @RestControllerAdvice every MyException that slips from any REST endpoint (@RequestMapping, @GetMapping...).

At this point there's sometimes a debate: where should we translate the error code: on server-side (in Java) or on the browser (in JavaScript)?

Although it's tempting to throw the problem on the frontend, translating the error codes on the backend tends to localize better the impact of adding a new error code. Indeed, why should the frontend code change when you add or remove a new error?

Plus, you might even write code to check at application startup that all the enum error codes have a translation in the .properties files. That's why I will translate the error on the backend and send user-friendly messages in the HTTP responses.

My Preference: translate the error codes on the backend

I used a Spring MessageSource to read the user message corresponding to the error code of the caught MyException. Based on the user Locale, the MessageSource determines what file to read from, eg: messages_RO.properties for RO, messages_FR.properties for fr, or default from messages.properties for any other language.

I extracted the user Locale from the Accept-Language header in the HTTP Request. In many applications however, the user language is read from the user profile, instead of the incoming HTTP request.

In src/main/resources/messages.properties we store the translations:

BAD_CONFIG=Incorrect application configuration

That's it! Free internationalization for our error messages.

There's a minor problem left though. What if we want to report some user input causing the error back to the UI? We need to add parameters to MyException. After adding other convenience constructors, here's the complete code of it:

public class MyException extends RuntimeException {
    public enum ErrorCode {
        GENERAL,
        BAD_CONFIG;
    }

    private final ErrorCode code;
    private final Object[] params;

    // canonical constructor
    public MyException(String message, ErrorCode code, Throwable cause, Object... params) {
        super(message, cause);
        this.code = code;
        this.params = params;
    }
    // 6 more overloaded constructors for convenience

    public ErrorCode getCode() {
        return code;
    }
    public Object[] getParams() {
        return params;
    }
}

This will allow us to use those parameters in the messages*.properties files:

BAD_CONFIG=Incorrect application configuration. User info: {0}

Oh, and we have to pass those arguments to the MessageSourcewhen we ask for the translation:

String userMessage = messageSource.getMessage(exception.getCode().name(), exception.getParams(), request.getLocale());

To see the entire app running, checkout this commit, start the SpringBoot class and navigate to http://localhost:8080.

Reporting General Errors

When should we use the GENERAL error code?

When it comes to what error messages to display to users, many good developers are tempted to distinguish between as many errors they can detect. In other words, they will consider that their users need to be notified about each and every failure cause. Although putting yourself in the shoes of your users is usually a good practice, in this case, it's a trap.

You should generally prefer displaying an opaque general-purpose error message, like "Internal Server Error, please check the logs". Consider carefully whether the ~developer~ user can do anything about that error or not. If not, do not bother to distinguish that particular error cause, because if you do, you'll have to make sure you continue to detect that error cause from then on. It may be simpler today, but who knows in 3 years... It's a good example of unnecessary and unforeseen long-term maintenance costs.

Best Practice: Avoid displaying the exact error cause to your users unless they can do something to fix it.

Honestly, if the application configuration is corrupted, can the user really fix that? Probably not. Therefore we should use new MyException(ErrorCode.GENERAL) or another convenience constructor overload new MyException() which does the exact same thing.

We can simplify it even more, and directly throw new RuntimeException("debug message?"...). Sonar may not be very happy about it, but it's the simplest possible form.

But what if there's no additional debug message to add to the new exception? Then your code might look like this:

} catch (SomeException e)
    throw new RuntimeException(e);
}

Note that I didn't log the exception before re-throwing. Doing that is actually an anti-pattern, as I will explain in a future blog post.

But look again at the code snippet above. Why in the world would do you catch that SomeException? If it were a runtime exception, why don't you let it fly-through? So SomeException must be a checked exception and you're doing that to convert it into a runtime, invisible one. If that's the case, then you have another widely used option: throw a @SneakyThrows annotation from Lombok on that method to effectively let the checked exception propagate invisibly down the call stack. You can read more about this technique in my other blog post.

One last thing: we need to enhance our Global Exception Handler to also catch any other Exception that slips from a RestController method, like the infamous NullPointerException. We need to add another method:

@ExceptionHandler(Exception.class)
@ResponseStatus
public String handleAnyOtherException(Exception exception, HttpServletRequest request) {
    String userMessage = messageSource.getMessage(ErrorCode.GENERAL.name(), null, request.getLocale());
    log.error(userMessage, exception);
    return userMessage;
}

Note that we used a similar code to the previous @ExceptionHandler method to read the user error messages from the same .properties file(s). You can do a bit more polishing around, but these are the main points.

Conclusions

Use concise exception messages to convey debugging information for developers
Catch-rethrow-with-debug-message to display more data in the stack trace
Only define new exception types in case you selectively catch them
Use an error code enum to translate errors to users
If needed, add the incorrect user input in the exception parameters and template your error messages
We implemented a Global Exception Handler in Spring to catch, log and translate all exceptions slipped from HTTP requests (+internationalized)

Exceptions and Streams

Victor Rentea — Tue, 05 Jan 2021 08:45:11 +0000

About the Author: Victor is a Java Champion and an experienced Independent Trainer, Speaker, and founder of a huge developer community. More on victorrentea.ro

This article was first published at Victor's blog

Java 8 gave us Optional, a mighty weapon against the most frequent Exception in Java: NullPointerException. Unfortunately, Java 8 also brought new headaches regarding exceptions, as the default functional interfaces in Java 8 don’t declare throwing any checked exceptions. So every time you get a checked exception within a lambda, you have to fix that somehow.

Converting Checked into Runtime Exceptions

The default suggestion offered by most IDEs to auto-fix this issue will produce code like this:

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
List<String> dateList = asList("2020-10-11", "2020-nov-12", "2020-12-01");
List<Date> dates = dateList.stream().map(s -> {
   try {
      return format.parse(s);
   } catch (ParseException e) {
      throw new RuntimeException(e);
   }
}).collect(toList());

Horrible code.

We could create a dedicated function doing just .parse and then cast a spell on it with @SneakyThrows, as we've discussed in a previous article:

   List<Date> dates = dateList.stream()
        .map(s -> uglyParse(format, s))
        .collect(toList());
   ...
}

@SneakyThrows
private static Date uglyParse(SimpleDateFormat format, String s) {
   return format.parse(s);
}

But creating this new method just to hack it with Lombok feels wrong. Indeed, we created it for a purely technical reason: to hide the annoying checked exception which doesn't fit with the java.util.Function interface, which doesn't declare to throw anything.

Let's play a bit and create a ThrowingFunction interface declaring to throw any checked exception:

interface ThrowingFunction<T,R> {
    R apply(T t) throws Exception;
}

Then, our s->format.parse(s) expression could be target-typed to this new interface, so the following line compiles:

ThrowingFunction<String, Date> p = s -> format.parse(s);
// or
ThrowingFunction<String, Date> p = format::parse;

Unfortunately, the Stream.map() operation takes a java.util.Function, you can't change that. But let's imagine we had a function that would take a ThrowingFunction and return back a 'classic' Function that doesn't throw any checked exception anymore.

Function<String, Date> f = wrapAsRuntime(p);
List<Date> dates = dateList.stream().map(f).collect(toList());

And here's the strange wrapAsRuntime function:

private static <T,R> Function<T, R> wrapAsRuntime(ThrowingFunction<T, R> p) {
    return t -> {
        try {
            return p.apply(t);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    };
}

If that's complete nonsense for your, then I would advice that you try to type it yourself. It helps a lot!

Notice that we’ve used generics to make it highly reusable. That's quite a good idea, isnt'it? It's so good that of course others had it it many years ago... :)

Introducing the Unchecked.function() from the jool library that does EXACTLY what we did above. Using it, the final code looks like:

List<Date> dates = dateList.stream().map(Unchecked.function(format::parse)).collect(toList());

If you've been using Java 8 for many years, then this library is a must-have.

Best-practice: Whenever checked exceptions are annoying you in lambdas -> or method references ::, use Unchecked.* to rethrow it as a RuntimeException

This doesn't involve any hack in the bytecode (as @SneakyThrows does), but only plain java code. Passing a function as a parameter to another function is a very useful practice that I will be blogging about soon, but functions that both take and return functions - those I don't like. It's one of the most complex, hard to read, and especially hard to debug in Java. But since it's a library doing it, and the purpose is obvious, I never hesitated to use it many of my projects.

Now let's shift a bit the perspective. No matter how you twist it, the processing of the entire stream stops when the first exception is thrown. But what if we don't want to crash but instead collect all the errors.

The Try Monad

Let’s change the requirements a bit: we now want to parse all the valid dates and return them IF at least half of them are parseable, otherwise we should throw an exception. This time we can’t let an exception terminate the execution of our stream. Instead, we want to go through all of the items and collect both parsed dates and exceptions. For example, if we are given 3 correctly-formatted dates and 2 invalid ones, we should return the 3 ones that we were able to parse correctly.

Whenever you want to collect the exceptions happening in items, consider using the vavr Try monad.

The Try<> class from the vavr library is a specialization of the Either<> concept present in many functional programming languages. An instance can store either the result or the occurred exception (if any).

List<Try<Date>> tries = dateList.stream()
    .map(s -> Try.of(
        () -> format.parse(s) // throwing code
    ))
    .collect(toList());

If the throwing code crashes with an exception, the surrounding Try.of function will catch that exception and return a failed Try. Therefore, in the tries list above, there can be items with isSuccess() either true or false. To count the success ratio, the shortest (geekest) form is:

double successRatio = tries.stream()
    .mapToInt(t -> t.isSuccess() ? 1 : 0)
    .average()
    .orElse(0);

Then,

if (successRatio > .5) {
    return tries.stream()
        .filter(Try::isSuccess)
        .map(Try::get)
        .collect(toList());
} else {
    throw new IllegalArgumentException("Too many invalid dates");
}

Problem solved.

To better understand the code, we can extract a function from it, that returns a Try<>:

private static Try<Date> tryParse(SimpleDateFormat format, String s) {
    return Try.of(() -> format.parse(s));
}

This resembles the style of handling exceptions in other languages like Go and Haskell, which return the exception to their callers.

By the way, if you think a bit, you could solve the problem without the Try, by sweeping the data twice: first to count the parseable dates, and then to actually parse them. Or even a single pass using a combination of a .map returning a null/Optional.empty for errors, followed by a .filter. That could work too, but the Try approach might be more readable.

Tip: Consider *vavr.Try<> when you want to collect both results and exceptions in a single pass through data.

By the way, if you keep thinking at the "Monad" word, here’s a nice article to get you past that: Monads for Java developers

Disclaimer: avoid streaming a large number of items in batch processing. Instead, stick with the industry default: process the data in chunks, and consider introducing Spring Batch for state-of-the-art batches.

Conclusions

Checked exceptions don't play nice with the Java Stream API.
Use @SneakyThrows (Lombok) or Unchecked (jOOL) to get rid of checked exceptions with Streams
Consider Try (vavr) whenever you want to collect the errors occurring for an element instead of terminating the Stream.

Hide Checked Exceptions with SneakyThrows

Victor Rentea — Fri, 25 Dec 2020 05:33:28 +0000

Victor Rentea is a Java Champion and an Independent Trainer with a huge experience on topics like Clean Code, Design Patterns, Unit Testing. Find out more on victorrentea.ro.

Java is the only programming language in the world that has checked exceptions, which forces the caller to know about the individual exception types thrown by the called function.

What do you do when you face a checked exception? Propagating checked exceptions through your code is both leaking implementation details, annoying, and even dangerous. That's why in the vast majority of cases you should catch-rethrow it as a runtime exception, and let it "silently" terminate your current use-case.

This article introduces a "magic" way to generate that code that we wrote dozens/hundreds of times in our career. Here's a reminder:

public static Date parseDate(String dateStr) {
    try {
        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
        return format.parse(dateStr);
    } catch (ParseException e) {
        throw new RuntimeException(e); // this :(
    }
}

If you are sick to do this catch-rethrow manually, here's the @SneakyThrows annotation coming from the magic realm of the Project Lombok.

Let's just annotate our method with it and simply remove the catch clause:

@SneakyThrows
public static Date parseDate(String dateStr) {
    SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
    return format.parse(dateStr);
}

Doing so will instruct the Lombok annotation processor to hack the bytecode generated by the javac compiler, allowing the code above to compile, although there's no catch, nor throws clause for the ParseException.

Warning: the Java IDE you use must be hacked (see here how).

Knowing that Lombok is able to change your code as it’s compiled, one might expect that the current body of our function will be surrounded by

try { ... } catch (Exception e) { throw new RuntimeException(e); }

That’s a fair expectation. Indeed, the checked exception is not swallowed but thrown back out of the function.

However, since Java8, Lombok does it in a bit unexpected way. To see what it really does, let's decompile the .class file:

public static Date parseDate(String dateStr) {
    try {
        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
        return format.parse(dateStr);
    } catch (Throwable var6) {
        throw var6;
    }
}

Indeed, Lombok did add a try-catch block around the body of my function, but it caught a Throwable and rethrew it without wrapping it at all!

Something is wrong!

That Throwable must have been declared in a throws clause on the function!

If you copy-paste the code in a .java file, you’ll quickly see that this code doesn’t compile!! But how was it compiled in the first place?!

To understand how's that even possible, you have to learn that the distinction between checked and runtime exceptions is only enforced by the Java compiler (javac). The Java Runtime (JVM) does NOT care what kind of exception you throw - it propagates any exception down the call stack the same way. So the Lombok processor tricked javac into producing bytecode that represents code that wouldn’t actually be compilable.

Panic!

But a minute after you calm down, you get this strange thought: if the checked exception is invisibly thrown, how would you then be able to catch it later? Let's try:

try { 
    parseDate("2020-01-01"); 
} catch (ParseException e) {...}

But this doesn't compile because nothing in the try block throws a ParseException. And javac will reject that. See for yourself: commit

So what does this mean? It means that the exceptions hidden using @SneakyThrows aren’t supposed to be caught again individually. Instead, a general catch (Exception) not ~catch (RuntimeException)~ should be in place somewhere down the call stack to catch the invisible checked exception. For example, if you are handling Spring REST endpoint exceptions using @RestControllerAdvice, make sure you declare to handle Exception.class. More details in an upcoming article.

Some of you might be disgusted at this point. Others might be super-excited. I’m not here to judge but only to report the techniques that have become wide-spread in the hundreds of projects I trained or consulted for. I agree that this can be misused if careless, so judge whether to use this feature responsibly.

Okay, okay... But why?!

Because Java is an old language. 25 years is a long time to carry some baggage. So today Lombok is effectively hacking the language to make us write less and more focused code.

Conclusion

Use Lombok's @SneakyThrows for fatal exceptions that you don't intend to selectively catch.
Otherwise wrap the checked exceptions in runtime exceptions that you throw instead.

Disclaimer: I chose on purpose parsing a date to point out a typically unrecoverable exception. You should definitely use the new Java 8 LocalDate/LocalDateTime API that (surprise!) doesn't throw any more checked exceptions, but runtime ones.

Avoiding NullPointerException

Victor Rentea — Tue, 15 Dec 2020 20:35:41 +0000

The terrible NullPointerException (NPE in short) is the most frequent Java exception occurring in production, according to a 2016 study. In this article, we’ll explore the main techniques to fight it: the self-validating model and the Optional wrapper.

Self-Validating Model

Imagine a business rule: every Customer has to have a birth date set. There are a number of ways to implement this constraint: validating the user data on the create and update use-cases, enforcing it via NOT NULL database constraint and/or implementing the null-check right in the constructor of the Customer entity. In this article, we'll explore the last one.

Here are the 3 most used forms to null-check in constructor today:

public Customer(@NonNull Date birthDate) { // 3
  if (birthDate == null) { // 1
     throw new IllegalArgumentException();
  }
  this.birthDate = Objects.requireNonNull(birthDate); // 2
}

The code above contains 3 alternative ways to do the same thing, any single one is of course enough:

Classic if check
One-liner check using Java 8 java.util.Objects - most widely used in projects under development today
Lombok @NonNull causing an if check to be added to the generated bytecode.

If there is a setter for the birth date, the check will move there, leaving the constructor to call that setter.

Enforcing the null-check in the constructor of your data objects has obvious advantages: no one could ever forget to do it. However, frameworks writing directly to the fields of the instance via reflection may bypass this check. Hibernate does this by default, so my advice is to also mark the corresponding required columns as NOT NULL in the database to make sure the data comes back consistent. Unfortunately, the problem can get more complicated in legacy systems that have to tolerate 'incorrect historical data’.

Trick: Hibernate requires a no-arg constructor on every persistent entity, but that constructor can be marked as protected to hide it from developers.

The moment all your data objects enforce the validity of their state internally, you do get a better night's sleep, but there's also a price to pay: creating dummy incomplete instances in tests becomes impossible. The typical tradeoff is relying more on Object Mothers for building valid test objects.

So, in general, whenever a null represents a data inconsistency case, throw an exception as early as possible.

But what if that null is indeed a valid value? For example, imagine our Customer might not have a Member Card because she didn't yet create one or maybe she didn't want to sign up for a member card. We'll discuss this case in the following section.

Getters returning Optional

Best-practice: Since Java 8, whenever a function needs to return null, it should declare to return Optional instead

Developers rapidly adopted this practice for functions computing a value or fetching remote data. Unfortunately, that didn't help with the main source of NPEs: our entity model.

A getter for a field which may be null should return Optional.

Assuming we're talking about an Entity mapped to a relational database, then if you didn't enforce NOT NULL on the corresponding column, the getter for that field should return Optional. For non-persistent data objects or NoSQL datastores that don't offer null protection, the previous section provides ideas on how to enforce null-checks programmatically in the entity code.

This change might seem frightening at first because we’re touching the 'sacred' getter we are all so familiar with. Indeed, changing a getter in a large codebase may impact up to dozens of places, but to ease the transition you could use the following sequence of safe steps:

Create a second getter returning Optional:

public Optional getMemberCardOpt() {
  return Optional.ofNullable(memberCard);
}

Change the original getter to delegate to the new one:

public String getMemberCard() {
  return getMemberCardOpt().orElse(null);
}

Make sure all the Java projects using the owner class are loaded in your workspace.
Inline the original getter everywhere. Everyone will end up calling getMemberCardOpt().
Rename the getter to the default name (removing the Opt suffix)

You're done, with zero compilation failures. After you do this, everyone previously calling the getter will now do getMemberCard().orElse(null);. In some cases, this might be the right thing to do, as in: dto.phone=customer.getPhone().orElse(null);

But let's suppose you wanted to use a property of the MemberCard, and you were careful to check for null:

if (customer.getMemeberCard() != null) { // Line X
    applyDiscount(order, customer.getMemeberCard().getPoints());
}

After applying the refactoring steps above, the code gets refactored to

if (customer.getMemeberCard().orElse(null) != null) { // Line X
    applyDiscount(order, customer.getMemeberCard().orElse(null).getPoints());
}

The if condition can be simplified by using .isPresent() and the second line by using .get(). Then one could even shorten the code to a single line:

customer.getMemberCard().ifPresent(card -> applyDiscount(order, card.getPoints()));

This means that you still need to go through all the places the getter is called to improve the code as we saw above. Furthermore, I bet that in large codebases you'll also discover places where the null-check (// Line X) was forgotten because the developer was tired/careless/rushing back then:

applyDiscount(order, customer.getMemeberCard().orElse(null).getPoints());

Tip: IntelliJ will hint you at the possible NPE in this case, so make sure the inspection 'Constant conditions and exceptions' is turned on.

Signaling the caller at compile-time that there might be nothing returned to her is an extremely powerful technique that can defeat the most frequent bug in Java applications. Most NPEs occur in large projects mainly because developers aren’t fully aware some parts of the data might be null. It happened on our project: we discovered dozens of NullPointerExceptons just waiting to happen when we moved to Optional getters.

Frameworks and Optional getters

Would frameworks allow getters to return Optional?

First of all, to make it clear, we only changed the return type of the getter. The setter and the field type kept using the raw type (not Optional).

All modern object-mapper frameworks (eg Hibernate, Mongo, Cassandra, Jackson, JAXB ...) can be instructed to read from private fields via reflection (Hibernated does it by default). So really, the frameworks don’t care about your getters.

When is Optional overkill?

You should consider making null-safe the objects you write logic on: Entities and Value Objects. As I explained in my Clean Architecture talk, you should avoid writing logic on API data objects (aka Data Transfer Objects). Since no logic uses them, null-protection is overkill.

Use Optional in your Domain Model not in your DTO/API Model.

Pre-instantiate sub-structures

Never do this:

private List<String> labels;

Always initialize the collection fields with an empty one!

private List<String> labels = new ArrayList<>();

Those few bytes allocated beforehand almost never matter. On the other hand, the risk of doing .add on a null list is just too dangerous. In some other cases, you might want to make the field final and take it via the constructor. Never leave collections references to have a null value.

Many teams choose to decompose larger entities into smaller parts. When those parts are mutable, make sure you instantiate the parts in the parent entity:

private BillingInfo billingInfo = new BillingInfo();

This would allow the users of your model to do e.getBillingInfo().setCity(city); without worrying about nulls.

Conclusion

You should consider upgrading your entity model to either reject a null via self-validation or present the nullable field via a getter that returns Optional. The effort of changing the getters of the core entities in your app is considerable, but along the way, you may find many dormant NPEs.

Lastly, always instantiate embedded collections or composite structures.

More from me

In case you liked this article, follow me on social media or check out my website for more.