In-depth Analysis and Resolution of org.glassfish.jersey.servlet.ServletContainer ClassNotFoundException in Tomcat

Problem Phenomenon and Background Analysis

In Java web development, ClassNotFoundException is one of the common runtime errors. Recent developer reports indicate sudden occurrences of missing class exceptions for org.glassfish.jersey.servlet.ServletContainer when using Tomcat 7 server with Eclipse Juno. Notably, this issue emerged unexpectedly after periods of normal operation, suggesting potential changes in environment configuration or dependency versions.

Deep Analysis of Error Stack Trace

The provided error stack trace reveals the exception occurs during Tomcat's class loading process:

java.lang.ClassNotFoundException: org.glassfish.jersey.servlet.ServletContainer
at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1671)
at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1516)
...

This indicates WebappClassLoader cannot locate the specified ServletContainer class in the classpath. The key insight lies in understanding Jersey framework's version evolution: Jersey 1.x uses com.sun.jersey.spi.container.servlet.ServletContainer, while Jersey 2.x adopts org.glassfish.jersey.servlet.ServletContainer.

Root Cause of Version Compatibility

The core issue stems from version mismatch: developers attempt to use Jersey 2.x Servlet configuration while actually deploying Jersey 1.x library files. This version confusion is particularly common during Jersey's migration from 1.x to 2.x.

Correct Configuration for Jersey 1.x

For Jersey 1.x environments, proper web.xml configuration should use the legacy package path:

<servlet>
  <servlet-name>Jersey REST Service</servlet-name>
  <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  <init-param>
    <param-name>com.sun.jersey.config.property.packages</param-name>
    <param-value>sample.hello.resources</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>Jersey REST Service</servlet-name>
  <url-pattern>/rest/*</url-pattern>
</servlet-mapping>

Modern Configuration for Jersey 2.x

If upgrading to Jersey 2.x, first ensure correct Maven dependencies:

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet</artifactId>
    <version>2.42</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.core</groupId>
    <artifactId>jersey-client</artifactId>
    <version>2.42</version>
</dependency>

Jersey 2.x supports annotation-based simplified configuration, eliminating the need for Servlet definitions in web.xml:

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("rest")
public class ApplicationConfig extends Application {
    // Automatically scans and registers JAX-RS components
}

Development Environment Integration Considerations

In IDE environments like Eclipse, ensure consistency between build path and deployment configuration. Particularly when using Gradle or Maven, verify:

• Deployment assembly settings in project properties
• Correct inclusion of dependency libraries in build path entries
• Server runtime environment configuration

Troubleshooting and Verification Steps

Recommended systematic troubleshooting approach:

1. Check JAR file versions in WEB-INF/lib directory
2. Verify dependency declarations in pom.xml or build.gradle
3. Confirm Servlet container doesn't provide conflicting JAX-RS implementations
4. Clean project and rebuild deployment

Conclusion and Best Practices

Resolving ClassNotFoundException fundamentally requires precise version management and environment configuration. It's recommended to clearly define Jersey versions during project initialization and establish unified dependency management strategies. For production environments, using Maven or Gradle for dependency management is advised to avoid version conflict risks associated with manual JAR file management.