Javadoc, " exception not thrown" in Eclipse

Question

When creating a javaodc, you describe the exceptions your methods can throw, right?

Take a look at the examlple:

public  void createLogFile() {
    try {
        file.createNewFile();
        fileWriter = new FileWriter(file);
        bufferedWriter = new BufferedWriter(fileWriter);

    } catch (IOException e) {
        MainScene.ausgabeText.setText("Fehler bei dem Erstellen des Log Files.");

    }
}

That is my javadoc for this method.

/**
 * A logfile will be created
 * @exception IOException
 *                When the log file coulndt be created ( just a test :-))
 */

When exporting to a javadoc, Eclipse tells me:

error: exception not thrown: java.io.IOException
 * @exception IOException

But Eclipse wants me to catch that Exception.

Why is my Eclipse giving me the error message above?

Answer 1

When you write a method, the implementation is hidden from the caller (ignore the fact that you can see the method implementation if you yourself wrote it). Sometimes in your implementation of a method, you will encounter exceptions (or you might even throw custom exceptions). There are two things you can do:

Catch

You can catch an exception when you want to handle it. That means that you know something could go wrong and you know what to do so that the program can continue in a predictable manner if that happens.

Since the caller cannot see your implementation, it is totally hidden from them.

Throws

When you do not want to handle the exception, because it is more suitable for the caller to be aware of this problem and handle it. In this case, you do not catch it and adds that Exception to the method via throws keyword. When you do this, you may add a @throws or @exception annotation in the method Javadoc to tell the caller exactly when they would expect to receive the particular exception.

Since that annotation only serves to tell the caller when to expect and how to properly handle the exception thrown by the method, then it is pointless to add any exception that is not thrown by the method.

Note that you are only required to throws checked exceptions. Methods do not need to list the unchecked exceptions via throws, as they are usually caused by poorly written codes.

Answer 2

There is 2 way to deal with Exception:

1. Catch it inside the method, outside the method no-one will know that an Exception occurs, and so you can't write in the Javadoc that this metho will throw an Exception (implicitly throws outside)

   /**
   */
   public void createLogFile() {
       try {
           //...
       } catch (IOException e) {
           //...   
       }
   }
   

2. You let the Exception propagates outside your method, and in that case you can writ in the Javadoc that this method can throws an Exception (implicitly throws outside)

   /**
   * @throws IOException When the log file coulndt be created
   */
   public void createLogFile() throws IOException  {
      //...
   }
   

---

_{As a note : the tags @throws and @exception are synonyms. Ref}