MTI TEK
  • Home
  • About
  • LLMs
  • Docker
  • Kubernetes
  • Java
  • All Resources
Java Servlet | Deployment Descriptor Elements (web.xml)
  1. Understanding <servlet> Elements
    1. Defining Servlet Names with <servlet-name>
    2. Specifying Implementation Classes with <servlet-class>

  1. Understanding <servlet> Elements
    The <servlet> element is the fundamental building block for defining servlet configurations in the web.xml deployment descriptor. It serves as a container for all servlet-related metadata that the web container needs to properly instantiate, initialize, and manage servlet instances throughout their lifecycle.
    <servlet> [0 or more]
      <description> [0 or more]
      <display-name> [0 or more]
      <icon> [0 or more]
        <small-icon> [0 or 1]
        <large-icon> [0 or 1]
    
      <servlet-name> [always 1]
      <servlet-class> | <jsp-file> [always 1]
    
      <init-param> [0 or more]
        <description> [0 or 1]
        <param-name> [always 1]
        <param-value> [always 1]
    
      <load-on-startup> [0 or 1]
    
      <run-as> [0 or 1]
        <description> [0 or more]
        <role-name> [always 1]
    
      <security-role-ref> [0 or more]
        <description> [0 or more]
        <role-name> [always 1]
        <role-link> [0 or 1]
    Important: The order of elements within <servlet> is strictly defined by the servlet specification and must be followed exactly. The web container will reject deployment descriptors that do not conform to this ordering requirement. Each servlet declaration creates a logical mapping between a name and either a Java class or JSP file, which can then be referenced by servlet-mapping elements to associate URL patterns with specific servlets.
    1. Defining Servlet Names with <servlet-name>
      The <servlet-name> element establishes a logical identifier for the servlet within the web application context. This name serves as the primary reference point for the servlet throughout the deployment descriptor and is used by the web container for internal servlet management and lifecycle operations.

      The servlet name acts as an abstraction layer between the actual implementation class and the web container's servlet registry. When HTTP requests are processed, the container uses this name to locate and invoke the appropriate servlet instance. This indirection allows for flexible deployment configurations and runtime servlet management.

      Key Requirements:
      • The name must be unique within the entire web application context (web.xml file).
      • The name can be completely different from the Java class name, providing deployment flexibility.
      • The name is case-sensitive and should follow standard naming conventions.
      • Special characters and spaces should be avoided to prevent potential issues with URL mapping.
      <servlet>
        <servlet-name>MyServlet1Name1</servlet-name>
        <servlet-class>com.mtitek.servlets.test1.MyServlet1</servlet-class>
      </servlet>
      Runtime Access: The getServletName() method, defined in the ServletConfig interface and implemented in GenericServlet, returns the value of this element (MyServlet1Name1). This allows servlets to programmatically determine their configured name at runtime, which is particularly useful for logging, debugging, and conditional behavior based on servlet identity.
    2. Specifying Implementation Classes with <servlet-class>
      The <servlet-class> element specifies the fully qualified class name of the Java class that implements the servlet functionality. This element tells the web container which class to instantiate when the servlet needs to be loaded and initialized. The class must be available in the web application's classpath, typically within the WEB-INF/classes directory or packaged in JAR files within WEB-INF/lib.

      The web container uses reflection to load and instantiate the specified class during servlet initialization. This process occurs either at application startup (if load-on-startup is specified) or upon the first request to the servlet. The container maintains the servlet instance throughout the application's lifecycle, following the servlet specification's lifecycle management rules.

      Naming Requirements:
      • The package name components must be separated by dots (com.mtitek.servlets.test1.).
      • The class name must not include the .class extension.
      • The fully qualified name must match exactly with the compiled class file location.
      • The class must be accessible through the web application's classloader.
      <servlet>
        <servlet-name>MyServlet1Name1</servlet-name>
        <servlet-class>com.mtitek.servlets.test1.MyServlet1</servlet-class>
      </servlet>
      
      <servlet>
        <servlet-name>MyServlet1Name2</servlet-name>
        <servlet-class>com.mtitek.servlets.test1.MyServlet1</servlet-class>
      </servlet>
      The example demonstrates that the value of the <servlet-class> element does not need to be unique across servlet declarations. The same class "com.mtitek.servlets.test1.MyServlet1" is associated with two different logical names (MyServlet1Name1 & MyServlet1Name2). This configuration pattern enables several advanced deployment scenarios.

      Multiple Instance Benefits:
      • Instance Isolation: Forces the web container to create separate instances of the servlet, ensuring complete isolation between different configurations. This prevents shared state issues that might occur if the container reused the same instance.
      • Configuration Variants: Allows providing different initialization parameters to the same servlet class, enabling different behavioral modes or configurations for the same underlying implementation.
      • Load Distribution: Can be used in conjunction with different URL mappings to distribute load or provide specialized entry points for the same servlet functionality.

      The getServletName() method can be used within the servlet implementation to determine which configuration instance is currently executing, allowing for conditional logic based on the servlet name.

      Implementation Requirements: The specified class must extend HttpServlet (for HTTP-specific servlets) or GenericServlet (for protocol-independent servlets), and ultimately implement the jakarta.servlet.Servlet interface. Failure to meet this requirement will result in a ClassCastException during servlet loading:
      HTTP Status 500 -
      java.lang.ClassCastException: com.mtitek.servlets.test1.MyServlet1 cannot be cast to jakarta.servlet.Servlet
© 2025 mtitek