I would recommend you never throw NullPointerException by yourself.
The main reason not to do this, as Thorbjørn Ravn Andersen says in a comment below, is that you don't wan't to mix 'real, bad NPEs' with NPEs thrown intentionally.
So, until you're confident that you're able to recognize 'valid' NPE, I'd recommend to use IllegalArgumentException when you want to tell to your API user that null is not a valid argument value. Your method's behavior when illegal null-parameter passed should be documented.
Another (more modern imho) option is to use @NotNull annotation near the argument.
Here is an article about using @NotNull annotation.
As I mentioned earlier, there can also be cases, when throwing NPE will not be confusing either to you or to your teammates: NPE cause should be clear and recognizable.
For instance, if you use some library with preconditions module, like Guava, then I find using checkNotNull()-like methods is a preferable way to deal with illegally-passed nulls.
checkNotNull(arg, msg) throws NPE, but from the stacktrace it's quite clear, that it was produced by Preconditions.checkNotNull() and thus it's not an unknown bug but rather expected behavior.
I would recommend you never throw NullPointerException by yourself.
The main reason not to do this, as Thorbjørn Ravn Andersen says in a comment below, is that you don't wan't to mix 'real, bad NPEs' with NPEs thrown intentionally.
So, until you're confident that you're able to recognize 'valid' NPE, I'd recommend to use IllegalArgumentException when you want to tell to your API user that null is not a valid argument value. Your method's behavior when illegal null-parameter passed should be documented.
Another (more modern imho) option is to use @NotNull annotation near the argument.
Here is an article about using @NotNull annotation.
As I mentioned earlier, there can also be cases, when throwing NPE will not be confusing either to you or to your teammates: NPE cause should be clear and recognizable.
For instance, if you use some library with preconditions module, like Guava, then I find using checkNotNull()-like methods is a preferable way to deal with illegally-passed nulls.
checkNotNull(arg, msg) throws NPE, but from the stacktrace it's quite clear, that it was produced by Preconditions.checkNotNull() and thus it's not an unknown bug but rather expected behavior.
I see no problem with throwing a NPE as early as possible before the JVM does it for you - in particular for null arguments. There seems to be some debate about this, but there are many examples in the Java SE libraries that does exactly this. I cannot see why NPE should be holy in the aspect that you are not able to throw it yourself.
However, I digress. This question is about something different. You are talking about a post-condition stating that the return value mustn't be null. Surely null in this case would mean you have a bug inside the very method?
How would you even document this? "This method throws a NullPointerException if the return value unexpectedly is null"? Without explaining how this could happen? No, I would use an assertion here. Exceptions should be used for errors that can conceivably happen - not to cover things that can happen if there's something wrong inside the method, because that does not help anybody.
SonarQube claims that context may be null here. If you know this is incorrect, you could just suppress this warning as a false positive. Otherwise, you should explicitly check if context is not null:
if (result instanceof AsyncResult && context != null) {
// Here -------------------------^
// Make sure handle async has been called
context.handleAsync();
Result newResult = context.controllerReturned();
if (newResult != null) {
result = newResult;
}
}
Try this:
if (result instanceof AsyncResult) {
if (context == null) {
//appropriate error handling
} else {
// Make sure handle async has been called
context.handleAsync();
Result newResult = context.controllerReturned();
if (newResult != null) {
result = newResult;
}
}
}
Alternatively you could ensure that when context is initialised it can never get value null. You could also look into the @NotNull annotation from JSR303 if context is a method parameter.