Reading through that document myself, it seems that there is only one type of "throw" being discussed, however, the methods listed throw diffrent exceptions depending on the condition that causes them;

for example: If an IO error occurs, IOException is thrown. If the security manager denies write access to a file, a SecurityException is thrown.

It may be you are just asking about the documentation conventions. The first "Throws" you bolded is part of the javadoc. That is, at the top of each method, there is comment block that explains, in plain language, what the method does. A special "tag", either @throws or @exception, is used to describe any exceptions thrown by the method. The Java compiler ignores comments, but another program (javadoc) understands these tags and automatically formats documentation in the form you are reading.

The second "throws" is actually part of the Java code. It tells the compiler what to expect can go wrong when the method is run. For checked exceptions (which is many of them), if a problem can occur in the method, it must either be handled inside the method, or declared in the method's "throws".

For well-documented code, there should be descriptions under the first "Throws" of every exception listed after the second "throws".

For well-documented code I would expect descriptions for unchecked exceptions as well. For example, "Throws NullPointerException if arg1 is null."

C Law
Greenhorn

Joined: Mar 05, 2006
Posts: 21

posted Mar 22, 2006 22:18:00

0

Thanks for the feedback.

The difference that confused me is:

If I put the method with the second (type of) bold throw, like this:

The compiler will complain a checked exception (in this case IOException) is not caught or declared. This is an error and the code will not compile.

However, for methods with the first type of bold throw, it's fine not to declare/handle it, as in the following example:

So I was trying to see which "throw" means the method it is associated with MUST declare or handle exception (e.g. is it safe to say for all methods in the API doc that comes with the second type of throw, like createNewFile(), we must put it in try...catch, or declare it.

Well, sort of. The File.length() method only throws a SecurityException, which is unchecked. You're right, it is described in the Javadoc, but not declared in the Java code. Because it's unchecked, it doesn't have to be declared, but it could be. The only way to know for sure it's an unchecked exception is to look at it in the documentation and see that it descends from RuntimeException. An IOException is a checked exception, so File.createNewFile() must declare throwing it. There is no obligation for a coder to document either checked or unchecked exceptions, but I believe any exception that is declared in the code for the method (whether checked or unchecked) will be automatically inserted into the "Throws:" section by Javadoc, even if there is nothing to say about it.

The bottom line is: what's listed after "throws" is part of the Java code. What is listed after "Throws: " is just documentation.