After checking the JavaDocs for a method I was thinking of using, requiredNonNull, I stumbled across the first one with the single parameter (T obj).
However what is the actual purpose of this particular method with this signature? All it simply does is throw and NPE which I'm somewhat positive (as a I may be missing something obvious here) would be thrown anyway.
Throws:
NullPointerException - if obj is null
The latter actually makes sense in terms of debugging certain code, as the doc also states, it's primarily designed for parameter validation
public static <T> T requireNonNull(T obj,String message)
Checks that the specified object reference is not null and throws a customized NullPointerException if it is.
Therefore I can print specific information along with the NPE to make debugging a hell of a lot easier.
With this in mind I highly doubt I would come across a situation where I'd rather just use the former instead. Please do enlighten me.
tl;dr - Why would you ever use the overload which doesn't take a message.
A good principle when writing software is to catch errors as early as possible. The quicker you notice, for example, a bad value such as null being passed to a method, the easier it is to find out the cause and fix the problem.
If you pass null to a method that is not supposed to receive null, a NullPointerException will probably happen somewhere, as you already noticed. However, the exception might not happen until a few methods further down, and when it happens somewhere deep down, it will be more difficult to find the exact source of the error.
So, it's better when methods check their arguments up front and throw an exception as soon as they find an invalid value such as null.
edit - About the one-parameter version: even though you won't provide an error message, checking arguments and throwing an exception early will be more useful than letting the null pass down until an exception happens somewhere deeper down. The stack trace will point to the line where you used Objects.requireNonNull(...) and it should be obvious to you as a developer that that means you're not supposed to pass null. When you let a NullPointerException happen implicitly you don't know if the original programmer had the intent that the variable should not be null.
It is a utility method. Just a shortcut! (shortcut designers have their ways of doing their shortcut style).
Why throwing in the first place?
Security and Debugging.
Security: to not allow any illegal value in a sensitive place. (makes inner algorithm more sure about what are they doing and what are they having).
Debugging: for the program to die fast when something unexpected happens.
When writing a method, say, inside one of your DAO objects, and you dont want this method to accept certain input, for discussions sake, say it does not allow null arguments. How do you go about implementing that, taking into account this method is likely to be reused in the future by new team members.
The way I do it is:
In the interface, I document inside the method javadoc that arguments a, b and c cannot be null.
Inside the method I check for null values first thing, and if any of a, b or c are null then I throw an IllegalArgumentException.
But, what if some developer in the future just reads off the method signature and decides that it what he/she needs and starts using it, without paying attention to this detail, and worse testing does not reveal it. NULL pointer exception won't occur and we are getting a useful error message, but we are still getting an error in production that could've been avoided.
Is there a way to enforce this at compile time? I doubt it, but what would be the safest and most bad-developer-proof way to go about doing this?
I don't think you can enforce this compile time, but you can certainly make the method signatures easy to understand.
If you don't mine adding a dependency on one of the validations frameworks you can use JSR 303's #NotNull or similar tools like Preconditions.
With JSR 303 you can do suff like:
#NotNull
#Size(min = 2, max = 14)
#UpperCase
private String licensePlate;
or
#NotNull
#NotEmpty
public String foo(#NotNull #Pattern(regexp="[0-9]") String param) {
...
}
Have a look at the Getting started with JSR 303 Bean Validation for more comprehensive examples.
You can use jsr305 with static code check tools like findbugs to check it before commit/release.
public String method(#NonNull String parameter ){
...
}
findbugs manual on annotation
As closest as you can get in enforcing things at compile time is by throwing checked exceptions which will force the caller to handle the exception at compile time. This might make them read the doc. The IllegalArgumentException is unchecked and can go unnoticed.
Normal practice in safeguarding on unusable values is by returning at the point we identify something unusable and add an error message for display. This will prevent the exception on production that might happen if the execution continued in that method, but might not altogether avoid it.
Given the code:
public static int sum(String a, String b) /* throws? WHAT? */ {
int x = Integer.parseInt(a); // throws NumberFormatException
int y = Integer.parseInt(b); // throws NumberFormatException
return x + y;
}
Could you tell if it's good Java or not? What I'm talking about is, NumberFormatException is an unchecked exception. You don't have to specify it as part of sum() signature. Moreover, as far as I understand, the idea of unchecked exceptions is just to signal that program's implementation is incorrect, and even more, catching unchecked exceptions is a bad idea, since it's like fixing bad program at runtime.
Would somebody please clarify whether:
I should specify NumberFormatException as a part of method's signature.
I should define my own checked exception (BadDataException), handle NumberFormatException inside the method and re-throw it as BadDataException.
I should define my own checked exception (BadDataException), validate both strings some way like regular expressions and throw my BadDataException if it doesn't match.
Your idea?
Update:
Imagine, it's not an open-source framework, that you should use for some reason. You look at method's signature and think - "OK, it never throws". Then, some day, you got an exception. Is it normal?
Update 2:
There are some comments saying my sum(String, String) is a bad design. I do absolutely agree, but for those who believe that original problem would just never appear if we had good design, here's an extra question:
The problem definition is like this: you have a data source where numbers are stored as Strings. This source may be XML file, web page, desktop window with 2 edit boxes, whatever.
Your goal is to implement the logic that takes these 2 Strings, converts them to ints and displays message box saying "the sum is xxx".
No matter what's the approach you use to design/implement this, you'll have these 2 points of inner functionality:
A place where you convert String to int
A place where you add 2 ints
The primary question of my original post is:
Integer.parseInt() expects correct string to be passed. Whenever you pass a bad string, it means that your program is incorrect (not "your user is an idiot"). You need to implement the piece of code where on one hand you have Integer.parseInt() with MUST semantics and on the other hand you need to be OK with the cases when input is incorrect - SHOULD semantics.
So, briefly: how do I implement SHOULD semantics if I only have MUST libraries.
In my opinion it would be preferable to handle exception logic as far up as possible. Hence I would prefer the signature
public static int sum(int a, int b);
With your method signature I would not change anything. Either you are
Programmatically using incorrect values, where you instead could validate your producer algorithm
or sending values from e.g., user input, in which case that module should perform the validation
Hence, exception handling in this case becomes a documentation issue.
This is a good question. I wish more people would think about such things.
IMHO, throwing unchecked exceptions is acceptable if you've been passed rubbish parameters.
Generally speaking, you shouldn't throw BadDataException because you shouldn't use Exceptions to control program flow. Exceptions are for the exceptional. Callers to your method can know before they call it if their strings are numbers or not, so passing rubbish in is avoidable and therefore can be considered a programming error, which means it's OK to throw unchecked exceptions.
Regarding declaring throws NumberFormatException - this is not that useful, because few will notice due to NumberFormatException being unchecked. However, IDE's can make use of it and offer to wrap in try/catch correctly. A good option is to use javadoc as well, eg:
/**
* Adds two string numbers
* #param a
* #param b
* #return
* #throws NumberFormatException if either of a or b is not an integer
*/
public static int sum(String a, String b) throws NumberFormatException {
int x = Integer.parseInt(a);
int y = Integer.parseInt(b);
return x + y;
}
EDITED:
The commenters have made valid points. You need to consider how this will be used and the overall design of your app.
If the method will be used all over the place, and it's important that all callers handle problems, the declare the method as throwing a checked exception (forcing callers to deal with problems), but cluttering the code with try/catch blocks.
If on the other hand we are using this method with data we trust, then declare it as above, because it is not expected to ever explode and you avoid the code clutter of essentially unnecessary try/catch blocks.
Number 4. As given, this method should not take strings as parameters it should take integers. In which case (since java wraps instead of overflowing) there's no possibility of an exception.
x = sum(Integer.parseInt(a), Integer.parseInt(b))
is a lot clearer as to what is meant than
x = sum(a, b)
You want the exception to happen as close to the source (input) as possible.
As to options 1-3, you don't define an exception because you expect your callers to assume that otherwise your code can't fail, you define an exception to define what happens under known failure conditions WHICH ARE UNIQUE TO YOUR METHOD. I.e. if you have a method that is a wrapper around another object, and it throws an exception then pass it along. Only if the exception is unique to your method should you throw a custom exception (frex, in your example, if sum was supposed to only return positive results, then checking for that and throwing an exception would be appropriate, if on the other hand java threw an overflow exception instead of wrapping, then you would pass that along, not define it in your signature, rename it, or eat it).
Update in response to update of the question:
So, briefly: how do I implement SHOULD semantics if I only have MUST libraries.
The solution to this is to to wrap the MUST library, and return a SHOULD value. In this case, a function that returns an Integer. Write a function that takes a string and returns an Integer object -- either it works, or it returns null (like guava's Ints.tryParse). Do your validation seperate from your operation, your operation should take ints. Whether your operation gets called with default values when you have invalid input, or you do something else, will depend upon your specs -- most I can say about that, is that it's really unlikely that the place to make that decision is in the operation method.
1. I should specify NumberFormatException as a part of method's signature.
I think so. It's a nice documentation.
2. I should define my own checked exception (BadDataException), handle NumberFormatException inside the method and re-throw it as BadDataException.
Sometimes yes. The checked exceptions are consider to be better in some cases, but working with them is quite a PITA. That's why many frameworks (e.g., Hibernate) use runtime exceptions only.
3. I should define my own checked exception (BadDataException), validate both strings some way like regular expressions and throw my BadDataException if it doesn't match.
Never. More work, less speed (unless you expect throwing the exception to be a rule), and no gain at all.
4. Your idea?
None at all.
Nr 4.
I think I wouldn't change the method at all.
I would put a try catch around the calling method or higher in the stack-trace where I'm in a context where I can gracefully recover with business logic from the exception.
I wouldn't certainty do #3 as I deem it overkill.
Assuming that what you are writing is going to be consumed (like as an API) by someone else, then you should go with 1, NumberFormatException is specifically for the purpose of communicating such exceptions and should be used.
First you need to ask your self, does the user of my method needs to worry about entering wrong data, or is it expected of him to enter proper data (in this case String).
This expectation is also know as design by contract.
and 3. Yes you probably should define BadDataException or even better use some of the excising ones like NumberFormatException but rather the leaving the standard message to be show. Catch NumberFormatException in the method and re-throw it with your message, not forgetting to include the original stack trace.
It depends on the situation bu I would probably go with re-throwing NumberFormatException with some additional info. And also there must be a javadoc explanation of what are the expected values for String a, String b
Depends a lot on the scenario you are in.
Case 1. Its always you who debug the code and no one else and exception wont cause a bad user experience
Throw the default NumberFormatException
Case2: Code should be extremely maintainable and understandable
Define your own exception and add lot more data for debugging while throwing it.
You dont need regex checks as, its gonna go to exception on bad input anyway.
If it was a production level code, my idea would be to define more than one custom exceptions, like
Number format exception
Overflow exception
Null exception etc...
and deal with all these seperately
You may do so, to make it clear that this can happen for incorrect input. It might help someone using your code to remember handling this situation. More specifically, you're making it clear that you don't handle it in the code yourself, or return some specific value instead. Of course, the JavaDoc should make this clear too.
Only if you want to force the caller to deal with a checked exception.
That seems like overkill. Rely on the parsing to detect bad input.
Overal, a NumberFormaException is unchecked because it is expected that correctly parseable input is provided. Input validation is something you should handle. However, actually parsing the input is the easiest way to do this. You could simply leave your method as it is and warn in the documentation that correct input is expected and anyone calling your function should validate both inputs before using it.
Any exceptional behaviour should be clarified in the documentation. Either it should state that this method returns a special value in case the of failure (like null, by changing the return type to Integer) or case 1 should be used. Having it explicit in the method's signature lets the user ignore it if he ensures correct strings by other means, but it still is obvious that the method doesn't handle this kind of failure by itself.
Answer to your updated question.
Yes it's perfectly normal to get "surprise" exceptions.
Think about all the run time errors one got when new to programming.
e.g ArrayIndexOutofBound
Also a common surprise exception from the for each loop.
ConcurrentModificationException or something like that
While I agree with the answer that the runtime exception should be allowed to be percolated, from a design and usability perspective, it would be a good idea to wrap it into a IllegalArgumentException rather than throw it as NumberFormatException. This then makes the contract of your method more clear whereby it declares an illegal argument was passed to it due to which it threw an exception.
Regarding the update to the question "Imagine, it's not an open-source framework, that you should use for some reason. You look at method's signature and think - "OK, it never throws". Then, some day, you got an exception. Is it normal?" the javadoc of your method should always spill out the behavior of your method (pre and post constraints). Think on the lines of say collection interfaces where in if a null is not allowed the javadoc says that a null pointer exception will be thrown although it is never part of the method signature.
As you are talking about good java practice ,in my opinion it is always better
To handle the unchecked exception then analyze it and through a custom unchecked exception.
Also while throwing custom unchecked exception you can add the Exception message that your client could understand and also print the stack trace of original exception
No need to declare custom exception as "throws" as it is unchecked one.
This way you are not violating the use of what unchecked exceptions are made for, at the same time client of the code would easily understand the reason and solution for the exception .
Also documenting properly in java-doc is a good practice and helps a lot.
I think it depends on your purpose, but I would document it at a minimum:
/**
* #return the sum (as an int) of the two strings
* #throws NumberFormatException if either string can't be converted to an Integer
*/
public static int sum(String a, String b)
int x = Integer.parseInt(a);
int y = Integer.parseInt(b);
return x + y;
}
Or, take a page from the Java source code for the java.lang.Integer class:
public static int parseInt(java.lang.String string) throws java.lang.NumberFormatException;
How about the input validation pattern implemented by Google's 'Guava' library or Apache's 'Validator' library (comparison)?
In my experience, it is considered good practice to validate a function's parameters at the beginning of the function and throw Exceptions where appropriate.
Also, I would consider this question to be largely language independent. The 'good practice' here would apply to all languages that have functions which can take parameters which may or may not be valid.
I think your very first sentence of "Quite a stupid question" is very relevant. Why would you ever write a method with that signature in the first place? Does it even make sense to sum two strings? If the calling method wants to sum two strings, it is the calling method's responsibility to make sure they are valid ints and to convert them before calling the method.
In this example, if the calling method cannot convert the two Strings into an int, it could do several things. It really depends at what layer this summation occurs at. I am assuming the String conversion would be very close to front-end code (if it was done properly), such that case 1. would be the most likely:
Set an error message and stop processing or redirect to an error page
Return false (ie, it would put the sum into some other object and would not be required to return it)
Throw some BadDataException as you are suggesting, but unless the summation of these two numbers is very important, this is overkill, and like mentioned above, this is probably bad design since it implies that the conversion is being done in the wrong place
There are lots of interesting answers to this question. But I still want to add this :
For string parsing, I always prefer to use "regular expressions". The java.util.regex package is there to help us. So I will end up with something like this, that never throws any exception. It's up to me to return a special value if I want to catch some error :
import java.util.regex.Pattern;
import java.util.regex.Matcher;
public static int sum(String a, String b) {
final String REGEX = "\\d"; // a single digit
Pattern pattern = Pattern.compile(REGEX);
Matcher matcher = pattern.matcher(a);
if (matcher.find()) { x = Integer.matcher.group(); }
Matcher matcher = pattern.matcher(b);
if (matcher.find()) { y = Integer.matcher.group(); }
return x + y;
}
As one can see, the code is just a bit longer, but we can handle what we want (and set default values for x and y, control what happens with else clauses, etc...)
We could even write a more general transformation routine, to which we can pass strings, defaut return values, REGEX code to compile, error messages to throw, ...
Hope It was usefull.
Warning : I was not able to test this code, so please excuse eventual syntax problems.
You face this issue because you let user errors propagate too deep into the core of the application and partly also because you abuse Java data types.
You should have a clearer separation between user input validation and business logic, use proper data typing, and this problem will disappear by itself.
The fact is the semantics of Integer.parseInt() are known - it's primary purpose it to parse valid integers. You're missing an explicit user input validation/parsing step.
I'm wondering if it is an accepted practice or not to avoid multiple calls on the same line with respect to possible NPEs, and if so in what circumstances. For example:
anObj.doThatWith(myObj.getThis());
vs
Object o = myObj.getThis();
anObj.doThatWith(o);
The latter is more verbose, but if there is an NPE, you immediately know what is null. However, it also requires creating a name for the variable and more import statements.
So my questions around this are:
Is this problem something worth
designing around? Is it better to go
for the first or second possibility?
Is the creation of a variable name something that would have an effect performance-wise?
Is there a proposal to change the exception
message to be able to determine what
object is null in future versions of
Java ?
Is this problem something worth designing around? Is it better to go for the first or second possibility?
IMO, no. Go for the version of the code that is most readable.
If you get an NPE that you cannot diagnose then modify the code as required. Alternatively, run it using the debugger and use breakpoints and single stepping to find out where the null pointer is coming from.
Is the creation of a variable name something that would have an effect performance-wise?
Adding an extra variable may increase the stack frame size, or may extend the time that some objects remain reachable. But both effects are unlikely to be significant.
Is there a proposal to change the exception message to be able to determine what object is null in future versions of Java ?
Not that I am aware of. Implementing such a feature would probably have significant performance downsides.
The Law of Demeter explicitly says not to do this at all.
If you are sure that getThis() cannot return a null value, the first variant is ok. You can use contract annotations in your code to check such conditions. For instance Parasoft JTest uses an annotation like #post $result != null and flags all methods without the annotation that use the return value without checking.
If the method can return null your code should always use the second variant, and check the return value. Only you can decide what to do if the return value is null, it might be ok, or you might want to log an error:
Object o = getThis();
if (null == o) {
log.error("mymethod: Could not retrieve this");
} else {
o.doThat();
}
Personally I dislike the one-liner code "design pattern", so I side by all those who say to keep your code readable. Although I saw much worse lines of code in existing projects similar to this:
someMap.put(
someObject.getSomeThing().getSomeOtherThing().getKey(),
someObject.getSomeThing().getSomeOtherThing())
I think that no one would argue that this is not the way to write maintainable code.
As for using annotations - unfortunately not all developers use the same IDE and Eclipse users would not benefit from the #Nullable and #NotNull annotations. And without the IDE integration these do not have much benefit (apart from some extra documentation). However I do recommend the assert ability. While it only helps during run-time, it does help to find most NPE causes and has no performance effect, and makes the assumptions your code makes clearer.
If it were me I would change the code to your latter version but I would also add logging (maybe print) statements with a framework like log4j so if something did go wrong I could check the log files to see what was null.
I’m from a .NET background and now dabbling in Java.
Currently, I’m having big problems designing an API defensively against faulty input. Let’s say I’ve got the following code (close enough):
public void setTokens(Node node, int newTokens) {
tokens.put(node, newTokens);
}
However, this code can fail for two reasons:
User passes a null node.
User passes an invalid node, i.e. one not contained in the graph.
In .NET, I would throw an ArgumentNullException (rather than a NullReferenceException!) or an ArgumentException respectively, passing the name of the offending argument (node) as a string argument.
Java doesn’t seem to have equivalent exceptions. I realize that I could be more specific and just throw whatever exception comes closest to describing the situation, or even writing my own exception class for the specific situation.
Is this the best practice? Or are there general-purpose classes similar to ArgumentException in .NET?
Does it even make sense to check against null in this case? The code will fail anyway and the exception’s stack trace will contain the above method call. Checking against null seems redundant and excessive. Granted, the stack trace will be slightly cleaner (since its target is the above method, rather than an internal check in the HashMap implementation of the JRE). But this must be offset against the cost of an additional if statement, which, furthermore, should never occur anyway – after all, passing null to the above method isn’t an expected situation, it’s a rather stupid bug. Expecting it is downright paranoid – and it will fail with the same exception even if I don’t check for it.
[As has been pointed out in the comments, HashMap.put actually allows null values for the key. So a check against null wouldn’t necessarily be redundant here.]
The standard Java exception is IllegalArgumentException. Some will throw NullPointerException if the argument is null, but for me NPE has that "someone screwed up" connotation, and you don't want clients of your API to think you don't know what you're doing.
For public APIs, check the arguments and fail early and cleanly. The time/cost barely matters.
Different groups have different standards.
Firstly, I assume you know the difference between RuntimeExceptions (unchecked) and normal Exceptions (checked), if not then see this question and the answers. If you write your own exception you can force it to be caught, whereas both NullPointerException and IllegalArgumentException are RuntimeExceptions which are frowned on in some circles.
Secondly, as with you, groups I've worked with but don't actively use asserts, but if your team (or consumer of the API) has decided it will use asserts, then assert sounds like precisely the correct mechanism.
If I was you I would use NullPointerException. The reason for this is precedent. Take an example Java API from Sun, for example java.util.TreeSet. This uses NPEs for precisely this sort of situation, and while it does look like your code just used a null, it is entirely appropriate.
As others have said IllegalArgumentException is an option, but I think NullPointerException is more communicative.
If this API is designed to be used by outside companies/teams I would stick with NullPointerException, but make sure it is declared in the javadoc. If it is for internal use then you might decide that adding your own Exception heirarchy is worthwhile, but personally I find that APIs which add huge exception heirarchies, which are only going to be printStackTrace()d or logged are just a waste of effort.
At the end of the day the main thing is that your code communicates clearly. A local exception heirarchy is like local jargon - it adds information for insiders but can baffle outsiders.
As regards checking against null I would argue it does make sense. Firstly, it allows you to add a message about what was null (ie node or tokens) when you construct the exception which would be helpful. Secondly, in future you might use a Map implementation which allows null, and then you would lose the error check. The cost is almost nothing, so unless a profiler says it is an inner loop problem I wouldn't worry about it.
In Java you would normally throw an IllegalArgumentException
If you want a guide about how to write good Java code, I can highly recommend the book Effective Java by Joshua Bloch.
It sounds like this might be an appropriate use for an assert:
public void setTokens(Node node, int newTokens) {
assert node != null;
tokens.put(node, newTokens);
}
Your approach depends entirely on what contract your function offers to callers - is it a precondition that node is not null?
If it is then you should throw an exception if node is null, since it is a contract violation. If it isnt then your function should silently handle the null Node and respond appropriately.
I think a lot depends on the contract of the method and how well the caller is known.
At some point in the process the caller could take action to validate the node before calling your method. If you know the caller and know that these nodes are always validated then i think it is ok to assume you'll get good data. Essentially responsibility is on the caller.
However if you are, for example, providing a third party library that is distributed then you need to validate the node for nulls, etcs...
An illegalArugementException is the java standard but is also a RunTimeException. So if you want to force the caller to handle the exception then you need to provided a check exception, probably a custom one you create.
Personally I'd like NullPointerExceptions to ONLY happen by accident, so something else must be used to indicate that an illegal argument value was passed. IllegalArgumentException is fine for this.
if (arg1 == null) {
throw new IllegalArgumentException("arg1 == null");
}
This should be sufficient to both those reading the code, but also the poor soul who gets a support call at 3 in the morning.
(and, ALWAYS provide an explanatory text for your exceptions, you will appreciate them some sad day)
like the other : java.lang.IllegalArgumentException.
About checking null Node, what about checking bad input at the Node creation ?
I don't have to please anybody, so what I do now as canonical code is
void method(String s)
if((s != null) && (s instanceof String) && (s.length() > 0x0000))
{
which gets me a lot of sleep.
Others will disagree.