This week's book giveaway is in the Jobs Discussion forum.
We're giving away four copies of Java Interview Guide and have Anthony DePalma on-line!
See this thread for details.
The moose likes Beginning Java and the fly likes Reading about exception in Java API Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Java Interview Guide this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Reading about exception in Java API" Watch "Reading about exception in Java API" New topic

Reading about exception in Java API

C Law

Joined: Mar 05, 2006
Posts: 21
Hello, can anybody tell me the difference between the
two types of "throws" in the Java 5 API text:

In the File class:

public long length()

Returns the length of the file denoted by this abstract pathname. The return value is unspecified if this pathname denotes a directory.

The length, in bytes, of the file denoted by this abstract pathname, or 0L if the file does not exist

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

public boolean createNewFile() throws IOException
Shaun Williams

Joined: Mar 22, 2006
Posts: 16
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.

Excuse me if im missing the point of your question completly.
Greg Charles

Joined: Oct 01, 2001
Posts: 2969

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".
Ken Blair
Ranch Hand

Joined: Jul 15, 2003
Posts: 1078
For well-documented code I would expect descriptions for unchecked exceptions as well. For example, "Throws NullPointerException if arg1 is null."
C Law

Joined: Mar 05, 2006
Posts: 21
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.

[ March 22, 2006: Message edited by: C Law ]
Greg Charles

Joined: Oct 01, 2001
Posts: 2969

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.
I agree. Here's the link:
subject: Reading about exception in Java API
It's not a secret anymore!