wood burning stoves*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc NullPointerException question. Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc NullPointerException question." Watch "Javadoc NullPointerException question." New topic
Author

Javadoc NullPointerException question.

Mark O' Sullivan
Ranch Hand

Joined: Aug 17, 2009
Posts: 160
Hi,
Have read the following from guidelines to writing Javadoc comments.
A @throws tag should be included for any checked exceptions (declared in the throws clause), as illustrated below, and also for any unchecked exceptions that the caller might reasonably want to catch, with the exception of NullPointerException.

from the following web-site
http://java.sun.com/j2se/javadoc/writingdoccomments/
Does this mean, for example, if one is passing objects to methods, e.g., that if they specify in their Javadoc documentation, say in the overview.html, that they never tested for null objects passed into methods, that is the responsibility of the tester user to recognise this and accept it will raise a RuntimeException? This of course would be different to an IllegalArgumentsException, where, for example, none of the fields of the data array could be null, say regarding a business rule.
You may wonder why I'm asking this question, just wondering could I get away without testing for null objects passed into methods. or and whether it's acceptable.
Thanks.
,
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5139
    
  12

Hi Mark,

In all my javadoc comments I never documented (or even mentioned) a NullPointerException, but of course I developed my code in such a way that a NullPointerException can't occur. Never!

From my create-method for example (just a snippet):

So if the caller passes a null value an IllegalArgumentException will be thrown and so I'm also guaranteed that when the actual code of the create method is executed I don't have to clutter my code with tests to see if data is null. And of course I did also a lot of other tests to validate the parameter (length of the array, contents of the array,...).
The main advantage of this approach (in my opinion) is that these tests occur at the start of your method. If these tests are passed successfully you know you are working with a valid parameter and you don't have to provide any checks in your actual code which simplifies your code a lot. Otherwise an exception is thrown and the caller of your method gets a clear message "the array must not be null" instead of a NullPointerException or ArrayIndexOutOfBoundsException (when the array has just 4 elements when the method expects 6).

Kind regards,
Roel


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Cristian Aionesa
Greenhorn

Joined: Jan 05, 2007
Posts: 20
Hi to all,

Roel, are you saying that in your opinion is a good practice to check a parameter passed to a method for null and throw an IllegalArgumentException in case of null before start using it? Or just for this project?
Here is a situation:



I don't know how you can deal with this situation. I think that in this specific case you can't do anything then letting a NullPointerException being thrown or check for null in the calling method. How did you validate the recNo parameter?

Regards,
Cristi

Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5139
    
  12

Hi Christian,

are you saying that in your opinion is a good practice to check a parameter passed to a method for null and throw an IllegalArgumentException in case of null before start using it?

Yes, that's my point. You should validate the parameters before using them and throw an IAE with a clear message when they are not what you expected.

The example code you gave has nothing to do with parameter checking. It will throw a NullPointerException due to unboxing at line 6 of your code, so it's just a bad example (to illustrate this point).

Another example illustrating my point, could be:


Of course if null is a valid value for the parameter that you pass, you won't do the check. That should be obvious

If you expect a String-array to be not-null, to be of the same size as the number of columns in the database, contains no null-values,... these checks you should provide at the beginning of your method to check if your parameter is valid. And you don't have to add checks for null or checks for correct size in the actual code of your method. Your code will become simpler and easier to maintain. (my javadoc comments clearly tell each situation when an IAE will be thrown)

Of course that is just my opinion about this issue and it is not only for this assignment, but also when you are developing on your job (and certainly if you are developing a framework/API that will be used by other developers).

Kind regards,
Roel
Jason Then
Greenhorn

Joined: Jun 26, 2010
Posts: 17
So if the caller passes a null value an IllegalArgumentException will be thrown


I think that a NullPointerException should be thrown with a specified detailed message - instead of an IllegalArgumentException.
The API spec for NullPointerException seems to indicate that this is a better choice.

Several classes in the Java API also behave like this. For instance a List will throw a NullPointerException is null is being added to the List, and it throws IllegalArgumentException for different reasons.
(See http://java.sun.com/javase/6/docs/api/java/util/List.html#add%28E%29).

What do you guys think?

As an aside, I have also created an exception throwing utility for just this purpose, the code is :



Cheers,
Jason
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Javadoc NullPointerException question.
 
Similar Threads
passed 151/155!!!
Yes! Passed! 388/400
nullpointer exception
Passed
passed SCJD with 360/400