No AtmosphereHandler found when using hierarchical classloaders

If you see this exception on IBM WebSphere when using annotations:

org.atmosphere.cpr.AtmosphereMappingException: No AtmosphereHandler found. Make sure you define it inside WEB-INF/atmosphere.xml or annotate using @___Service

If you're sure that your class is correct, you might be having issues with Java EE hierarchical classloaders.

Scenario:

EAR
 |- lib
 |   |- atmosphere-runtime-x.x.x.jar
 |   \- atmosphere-annotations-x.x.x.jar
 \- WAR
     \- ManagedServiceImpl.java

The problem here is that the default behavior is to find classes from the top down (WebSphere calls this parent-first). The problem with this, when the WAR fails to find the Atmosphere servlet while starting, it will jump to the parent, where it finds the the servlet. Atmosphere then tries to scan for annotated classes, but find none because it can't go back down in the classloader chain to find your code in the WAR classloader.

There are a few solutions to this.

1. Change the server to use a single classloader. This can cause problems because now, the application server's JARs are mixed in with your JARs (and any other application deployed), which can cause problems. Which version of the XML parser gets loaded? WebSphere's version will win.
2. Change the classloading strategy to parent-last. This is the best solution, but can cause compatibility problems for you application. This will cause the classloader to move upward, and then when the WAR find the Atmosphere servlet in the parent classloader, it will already have your annotated class in the list, which will then be found when scanning for annotated classes.

For IBM WebSphere, see the IBM WebSphere Knowledge Center for more info.