Page History

Tasks that run for extended periods of time should provide a notification mechanism to alert upper layers when they terminate abnormally. Failure to do this does not cause any resource leaks because the threads in the pool are still recycled, however, it makes failure diagnosis extremely difficult. 

The best way to handle exceptions at a global level is to use an exception handler. The handler can perform diagnostic actions, clean-up and shutdown the Java Virtual Machine (JVM) or simply log the details of the failure. This guideline may be violated if the code for all runnable and callable tasks has been audited to ensure that no exceptional conditions are possible. Nonetheless, it is usually a good practice to install a task specific or global exception handler to initiate recovery. 

h2. Noncompliant Code Example

This noncompliant code example consists of class {{PoolService}} that encapsulates a thread pool and a runnable class, {{Task}}. The {{run()}} method of the task can throw runtime exceptions such as {{NullPointerException}}. 

{code:bgColor=#FFCCCC}
final class PoolService {
  private final ExecutorService pool = Executors.newFixedThreadPool(10);
		  
  public void doSomething() {	   
    pool.execute(new Task());
  }	
}

final class Task implements Runnable {
  @Override public void run() {
    // ...
    throw new NullPointerException();
    // ...	
  }
}
{code}

 task does not notify upper layers when it terminates unexpectedly as a result of the runtime exception. Moreover, it does not use any recovery mechanism.

{dynamictasklist:thingsToDo}

h2. Compliant Solution (Custom exception reporter)

This compliant solution refactors the task so that it catches {{Throwable}} and forwards it to a custom exception reporter (see [EXC01-J. Use a class dedicated to reporting exceptions] for details on class {{MyExceptionReporter}}).

{code:bgColor=#ccccff}
// ...

final class Task implements Runnable {
  @Override public void run() {
    try {
      // ...
      throw new NullPointerException();
      // ...
    } catch(Throwable t) {
      // Execute any recovery code
      MyExceptionReporter.report(t);	 
    } finally {
      // Perform clean-up actions
    }   	
  }
}
{code}

A {{finally}} block can be used to perform clean-up actions. If the task cannot be refactored, it may be wrapped within a {{Runnable}} or {{Callable}} that catches {{Throwable}}, and submitted to the thread pool.


h2. Compliant Solution ({{ThreadPoolExecutor}} hooks)

Task specific recovery or clean-up actions can also be performed by overriding the class {{java.util.concurrent.ThreadPoolExecutor}}'s {{afterExecute()}} hook. This hook is called when a task completes successfully by executing all statements in its {{run()}} method, or halts because of an exception (A {{java.lang.Error}} might not be captured on specific implementations, see [Bug ID 6450211|http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6450211] \[[SDN 08|AA. Java References#SDN 08]\]). When using this approach, substitute the executor service with a custom {{ThreadPoolExecutor}} that overrides the {{afterExecute()}} hook as shown below:

{code:bgColor=#ccccff}
final class PoolService {
  // The values have been hardcodedhard-coded for brevity
  ExecutorService pool = new CustomThreadPoolExecutor(
      10, 10, 10, TimeUnit.SECONDS, 
                         new ArrayBlockingQueue<Runnable>(10));
  // ...
}

class CustomThreadPoolExecutor extends ThreadPoolExecutor {
  // ... Constructor ...
  public CustomThreadPoolExecutor(
      int corePoolSize, int maximumPoolSize, long keepAliveTime, 
      TimeUnit unit, BlockingQueue<Runnable> workQueue) { 
    super(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue);
  }


  @Override
  public void afterExecute(Runnable r, Throwable t) {
    super.afterExecute(r, t);
    if (t != null) {
      // Exception occurred, forward to handler
    }
    // ... Perform task-specific recovery and clean-upcleanup actions
  }

  @Override
  public void terminated() {
     super.terminated();
     // ... Perform final clean-up actions
  }
}
{code}

Similarly, the {{

 

h2. Compliant Solution (Uncaught exception handler)

This compliant solution sets an uncaught exception handler on behalf of the thread pool. During its construction, an argument of type {{ThreadFactory}} is passed to the thread pool. The factory is responsible for creating new threads and setting the uncaught exception handler on their behalf. The class {{Task}} remains the same as the noncompliant code example.

{code:bgColor=#ccccff}
final class PoolService {
  private static final ThreadFactory factory =
 new
     new ExceptionThreadFactory(new MyExceptionHandler());
  private static final ExecutorService pool =
      Executors.newFixedThreadPool(10, factory);

  public void doSomething() {	   
    pool.execute(new Task()); // Task is a runnable class	      	    	      
  }
 
  public static class ExceptionThreadFactory implements ThreadFactory  {			
    private static final ThreadFactory defaultFactory =
        Executors.defaultThreadFactory();
    private final Thread.UncaughtExceptionHandler handler;

    public ExceptionThreadFactory(
        Thread.UncaughtExceptionHandler handler)
    {
      this.handler = handler;
    }

    @Override public Thread newThread(Runnable run) {
      Thread thread = defaultFactory.newThread(run);
      thread.setUncaughtExceptionHandler(handler);
      return thread;
    }
  }
	  
  public static class MyExceptionHandler extends ExceptionReporter
  
    implements Thread.UncaughtExceptionHandler {

    private final Logger logger = Logger.getLogger("com.organization.Log");
    // ... 

    @Override public void uncaughtException(Thread thread, Throwable t) {
      logger.log(Level.SEVERE, "Thread exited with exception: " + thread.getName(), t);			      // Recovery or logging code
    }
  }	  
}
{code}

Note that the uncaught exception handler is not called if the method {{ExecutorService.submit()}} is invoked. This is because the thrown exception is considered to be part of the return status and is consequently, re-thrown by {{Future.get()}}, wrapped in an {{ExecutionException}} \[[Goetz 06|AA. Java References#Goetz 06]\]. 

h2. Risk Assessment

Failing to provide a mechanism to report that tasks in a thread pool failed as a result of an exceptional condition, can make it harder to find the source of the issue.

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| CON37- J | low | probable | medium | {color:green}{*}P4{*}{color} | {color:green}{*}L3{*}{color} |



h3. Automated Detection

TODO



h3. Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the [CERT website|https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON35-J].

h2. References

\[[API 06|AA. Java References#API 06]\] interfaces {{ExecutorService}}, {{ThreadFactory}} and class {{Thread}}
\[[Goetz 06|AA. Java References#Goetz 06]\] Chapter 7.3: Handling abnormal thread termination

----
[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!|CON12-J. Avoid deadlock by requesting and releasing locks in the same order]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!|11. Concurrency (CON)]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!|VOID CON14-J. Ensure atomicity of 64-bit operations]
}

final class PoolService {
  private final ExecutorService pool = Executors.newFixedThreadPool(10);

  public void doSomething() {
    Future<?> future = pool.submit(new Task());

    // ...

    try {
      future.get();
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } catch (ExecutionException e) {
      Throwable exception = e.getCause();
      // Forward to exception reporter
    }
  }
}

 
||Completed||Priority||Locked||CreatedDate||CompletedDate||Assignee||Name||