Page History

It is mandatory to handle checked exceptions in Java. The compiler enforces this rule by making sure that every possible checked exception is either declared using the throws clause or handled within a try-catch block. Unfortunately, this guarantee does not carry over to the JVM runtime environment, depriving preventing the caller from gleaning critical information about the which exceptions that the callee is capable of throwingcan throw.

Checked exceptions can be thought of as provide a checklist of unusual events that can be handled during program execution whereas unchecked exceptions involve programming mistakes that should be caught early, without expecting the Java runtime to stage a recovery. Undeclared checked exceptions resemble the latter in behavior as the compiler does not force the programmer to handle them.

A common argument favoring undeclared checked exceptions (even unchecked exceptions) is that the caller does not have to define innumerable exception handlers{{catch}} blocks for each specific checked exception that the callee can throw. Likewise, handling each exception within the callee is believed to clutter-up the code. One way to deal with this issue is to wrap the specific exceptions into a new exception, appropriate for the abstraction level. For example, a method may throw an {{IOException}} instead of specific exceptions such as {{FileNotFoundException}}. While exception handling should be as specific as possible, a compromise can be struck to increase the code readability in complex systems \[[Venners 03|AA. Java References#Venners 03]\]. WrappingHowever. wrapping checked exceptions into a broader exception class may not provide enough context for a recovery at the top level. On Unchecked exceptions and undeclared checked exceptions, on the other hand, help bringingreduce clutter uncheckedin exceptionscode intobut theare pictureunsuitable maywhen nota beclient theis roadexpected to success.  recover from an exceptional condition.

Clients or callers are expected to know the exceptions that the underlying code can throw. For this reason, developers must sufficiently document all possible checked exceptions. Undeclared checked exceptions are a special class of exceptions that need diligent documentation. Security critical software must almost always make this contract explicit. Yet another difficulty in dealing with them is that sensitive exceptions cannot be sanitized before delivery, in the absence of a dedicated exception reporter. Ideally, undeclared checked exceptions should be avoided.

Noncompliant Code Example

This noncompliant code example uses the sun.misc.Unsafe class. All sun.* classes are not documented on purpose undocumented because using them can cause portability and backward compatibility issues. This noncompliant code example proves is risky not only from this standpoint ; its malevolence is aggravated and by its capacity to throw undeclared checked exceptions.

...

import java.io.IOException;
import java.lang.reflect.Field;
import sun.misc.Unsafe;

public class UnsafeCode {
  public static void main( String[] args ) throws SecurityException, NoSuchFieldException,
  IllegalArgumentException, IllegalAccessException {
    Field f = Unsafe.class.getDeclaredField("theUnsafe");
    field.setAccessible(true);
    Unsafe u =  (Unsafe) field.get(null);
    u.throwException(new IOException("No need to declare this checked exception"));
  }
}

Noncompliant Code Example

Any checked exception that is thrown by the default constructor of Class.NewInstance() gets is propagated even if it is not declared explicitly. On the contrary, the java.lang.reflect.Constructor.NewInstance() method wraps any exceptions thrown from within the constructor into a checked exception called InvocationTargetException.

public class BadNewInstance {
  private static Throwable throwable;

  private BadNewInstance() throws Throwable {
    throw throwable;
  }

  public static synchronized void undeclaredThrow(Throwable throwable) {
    // these two should not be passed
    if (throwable instanceof IllegalAccessException || throwable instanceof InstantiationException)
        throw new IllegalArgumentException(); // unchecked, no declaration required
       
    BadNewInstance.throwable = throwable;
    try {
      BadNewInstance.class.newInstance();
    } catch (InstantiationException e) { /* dead code */ } 
      catch (IllegalAccessException e) { /* dead code */ } 
      finally { BadNewInstance.throwable = null; }  // avoid memory leak
  }
}

public class UndeclaredException {
  public static void main(String[] args) {   // no declared checked exceptions
    BadNewInstance.undeclaredThrow(new Exception("Any checked exception"));
  }
}

Even if the programmer now wishes to catch and handle the possible checked exceptions, the compiler refuses to believe that any can be thrown in the particular context. One way to deal with this difficulty is to catch Exception and check whether the possible checked exception is an instance of it else re-throw the exception. This is shown below. The most obvious pitfall is that this technique is easy to bypass whenever an unanticipated checked exception gets is thrown.

  public static void main(String[] args) {
    try {	
      BadNewInstance.undeclaredThrow(new IOException("Any checked exception"));
    }catch(Exception e) { 
    if (e instanceof IOException) {
      System.out.println("IOException occurred");
    } else if (e instanceof RuntimeException) {
      throw (RuntimeException) e;
    } else {
      //some other unknown checked exception
    }
  }  

Compliant Solution

Prefer the method {{Constructor.newInstance()}} over {{Class.newInstance()}}. An alternative is to use the builder interface recommended by \[[Bloch 08|AA. Java References#Bloch 08]\]. 

...

For further details on implementing the builder pattern, refer to OBJ32-J. Do not allow partially initialized objects to be accessed. In the example described in that rule, the Currency.Builder class must implement the Builder interface highlighted in this recommendation.

Noncompliant Code Example

An unchecked cast of a generic type with parameterized exception declaration can also result in unexpected checked exceptions. The compiler complains unless the warnings are suppressed.

interface Thr<EXC extends Exception> {
    void fn() throws EXC;
}

public class UndeclaredGen {
  static void undeclaredThrow() throws RuntimeException {
    @SuppressWarnings("unchecked")  // suppresses warnings  
    Thr<RuntimeException> thr = (Thr<RuntimeException>)(Thr)
      new Thr<IOException>() {
        public void fn() throws IOException {
          throw new IOException();
	}
      };
      thr.fn();
    }

  public static void main(String[] args) {
    undeclaredThrow();
  }
}

Noncompliant Code Example

According to the Java \[[API 06|AA. Java References#API 06]\], class {{Thread}} documentation, 

...

It is also possible to disassemble a class, remove any declared checked exceptions and reassemble the class so that checked exceptions are thrown at runtime when this class is used \[[Roubtsov 03|AA. Java References#Roubtsov 03]\]. Simply, compiling against a class that declares the checked exception and supplying one at runtime that doesn't, also suffices. Similarly, a different compiler than {{javac}} might handle checked exceptions differently. Yet another way is to furtively use the {{sun.corba.Bridge}} class. All these methods are strongly discouraged.  

Compliant Solution

Refrain from employing code that is capable of throwing undeclared checked exceptions (legitimate or hostile). If the source code can throw them, explicitly document the behavior. Finally, do not use deprecated methods such as Thread.stop().

Risk Assessment

Failure to document undeclared checked exceptions can result in checked exceptions that the caller is unprepared to handle.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

\[[JLS 05|AA. Java References#JLS 05]\] Chapter 11: Exceptions
\[[Venners 03|AA. Java References#Venners 03]\] "Scalability of Checked Exceptions"
\[[Roubtsov 03|AA. Java References#Roubtsov 03]\]
\[[Schwarz 04|AA. Java References#Schwarz 04]\]
\[[Goetz 04b|AA. Java References#Goetz 04b]\]
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 2: "Consider a builder when faced with many constructor parameters"
\[[MITRE 09|AA. Java References#MITRE 09]\] [CWE ID 703|http://cwe.mitre.org/data/definitions/703.html] "Failure to Handle Exceptional Conditions", [CWE ID 248|http://cwe.mitre.org/data/definitions/248.html] "Uncaught Exception"

...