adrgit / classloader-leak-prevention

ClassLoader leak prevention / protection

Classloader leak prevention library

If you want to avoid the dreaded java.lang.OutOfMemoryError: PermGen space, just include this library into your Java EE application, and add this context listener in your web.xml:

<listener>
  <listener-class>se.jiderhamn.classloader.leak.prevention.ClassLoaderLeakPreventor</listener-class>
</listener>

It makes sense to keep this listener "outermost" (initializing first, destroying last), so you should normally declare it before any other listeners in web.xml.

To learn more about classloader leaks, their causes, types, ways to find them and known offenders, see blog series here: http://java.jiderhamn.se/category/classloader-leaks/

Maven

The library is available in Maven Central with the following details:

<dependency>
  <groupId>se.jiderhamn</groupId>
  <artifactId>classloader-leak-prevention</artifactId>
  <version>1.10.0</version>
</dependency>

Configuration

The context listener has a number of settings that can be configured with context parameters in web.xml:

<context-param>
  <param-name>ClassLoaderLeakPreventor.stopThreads</param-name>
  <param-value>false</param-value>
</context-param>

The available settings are

Parameter name	Default value	Description
ClassLoaderLeakPreventor.stopThreads	true	Should threads tied to the web app classloader be forced to stop at application shutdown?
ClassLoaderLeakPreventor.stopTimerThreads	true	Should Timer threads tied to the web app classloader be forced to stop at application shutdown?
ClassLoaderLeakPreventor.executeShutdownHooks	true	Should shutdown hooks registered from the application be executed at application shutdown?
ClassLoaderLeakPreventor.threadWaitMs	5000 (5 seconds)	No of milliseconds to wait for threads to finish execution, before stopping them.
ClassLoaderLeakPreventor.shutdownHookWaitMs	10000 (10 seconds)	No of milliseconds to wait for shutdown hooks to finish execution, before stopping them. If set to -1 there will be no waiting at all, but Thread is allowed to run until finished.

Classloader leak detection / test framework

Another part of the project, is a framework that allows the creation of JUnit tests, that confirms classloader leaks in third party APIs. It is also possible to test leak prevention mechanisms to confirm that the leak really is avoided.

For this purpose, I have create a JUnit runner, se.jiderhamn.JUnitClassloaderRunner, which is used to run each test in a separate classloader, that is then attempted to be garbage collected. The default assumption is that the test case will create a leak. A basic example would look like this

package se.jiderhamn.tests;

import org.junit.Test;
import org.junit.runner.RunWith;
import se.jiderhamn.JUnitClassloaderRunner;

@RunWith(JUnitClassloaderRunner.class)
public class LeakConfirmingTest {
  
  @Test
  public void triggerLeak() {
    // Do something that triggers the suspected leak
  }
}

In case the test passes, it means the code inside the tested method does in fact cause classloader leaks.

In order to confirm that a piece of code does not cause leaks, add the se.jiderhamn.Leaks annotation, with a value of false.

  @Test
  @Leaks(false) // Should not leak
  public void doesNotTriggerLeak() {
    // Do something that should not trigger any leaks
  }

In this case, the test passes only in case a leak isn't triggered.

You can also confirm that a leak workaround has the expected effect, by annotating the class with se.jiderhamn.LeakPreventor, and set its value to a Runnable that fixes the leak.

@RunWith(JUnitClassloaderRunner.class)
@LeakPreventor(LeakThatCanBeFixedText.Preventor.class)
public class LeakThatCanBeFixedText {
  
  @Test
  public void triggerLeak() {
    // Do something that triggers the suspected leak
  }
  
  public static class Preventor implements Runnable {
    public void run() {
      // Run cleanup code, that fixed the leak and allows the classloader to be GC:ed
    }
  }
}

In this case, a successfull test means two things: 1) the @Test method does cause a leak and 2) the leak is prevented by the code in the Preventor. That is, the test will fail if either there is no leak to begin with, or the leak is still present after executing the Preventor.

NOTE: It is not yet determined whether multiple test cases in the same class works, so you should stick to one single @Test method per class for now.

NOTE: The test framework is not included in the runtime JAR - you need to grab it from GitHub.

License

This project is licensed under the Apache 2 license, which allows you to include modified versions of the code in your distributed software, without having to release your source code.