# Javax / Faces / Webapp

## Overview

The `javax.faces.webapp` subpackage is part of JavaServer Faces (JSF), the Java EE framework for building component-based user interfaces for web applications. This package provides servlet and JSP tag handler classes that act as the bridge between the web container (HTTP requests) and the JSF lifecycle. It is the entry point that allows a JSF application to be deployed as a standard Java EE web application — the `FacesServlet` is declared in `web.xml` and receives all incoming HTTP requests, dispatching them through the JSF request processing lifecycle.

This module is foundational: without it, a web application cannot participate in the JSF model.

## Key Classes

### FacesServlet

**Source:** [`FacesServlet.java`](full-fixture-codebase/src/java/javax/faces/webapp/FacesServlet.java)

`FacesServlet` is the core servlet for any JSF application. It is declared as a servlet mapping (typically for `*.jsf` or `/faces/*` paths) in `web.xml` and serves as the single entry point for all JSF requests. When a request arrives, `FacesServlet` bootstraps the JSF runtime and delegates the request to the JSF lifecycle, which processes the request, updates model data, renders the appropriate view, and sends back a response.

In this codebase, `FacesServlet` appears as a minimal class stub. In a full JSF runtime implementation (e.g., Mojarra or MyFaces), the class would extend `HttpServlet` and implement the `init(FacesConfig)` and `service()` methods that orchestrate the entire request lifecycle. The JSF specification defines exactly how this servlet integrates with the container: it reads `faces-config.xml`, manages `Application` instances, and manages view restoration.

#### Key responsibilities

- **Request reception** — Acts as the servlet mapped to JSF URL patterns, intercepting all matching HTTP requests.
- **Lifecycle delegation** — Passes each request to the JSF lifecycle (`RestoreView`, `ApplyRequestValues`, `ProcessValidations`, `UpdateModelValues`, `InvokeApplication`, `RenderResponse`), which coordinates the six phases defined by the JSF spec.
- **Resource management** — Manages the `Application` instance and view states that are shared across requests within the same application context.

## How It Works

A typical request flows through this package as follows:

```mermaid
flowchart TD
    WEB["web-full.xml<br/>(web config)"] --> SERV["FacesServlet<br/>(javax.faces.webapp)"]
    SERV -->|Registers as servlet| CONTAINER["Web Container<br/>(Servlet Container)"]
    CONTAINER -->|HTTP Request| BRIDGE["javax.faces.webapp<br/>Servlet Layer"]
    BRIDGE --> LIFECYCLE["JSF Lifecycle<br/>(6 phases)"]
    LIFECYCLE --> MANAGED["Managed Beans<br/>(Application Model)"]
    LIFECYCLE --> VIEW["JSF View<br/>(Facelets / JSP)"]
```

1. The web container (e.g., Tomcat, GlassFish) receives an HTTP request matching the FacesServlet mapping.
2. `FacesServlet.service()` dispatches the request to the JSF lifecycle.
3. The JSF lifecycle processes the request through its phases, interacting with managed beans and view templates.
4. The response (usually HTML) is written back to the client.

## Data Model

This subpackage does not define any data model classes. Its role is purely infrastructural — it provides the servlet integration layer that connects the web container to the JSF framework's internal data model (managed beans, view states, application configuration).

## Dependencies and Integration

### Inbound Dependencies

- **`web-full.xml`** — The deployment descriptor registers this servlet:

  ```xml
  <servlet>
    <servlet-name>FacesServlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
  </servlet>
  ```

  This snippet appears in [`web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml), showing that the application is configured as a JSF-capable web application.

### Outbound Dependencies

- **`javax.servlet`** — `FacesServlet` extends the servlet API to integrate with the web container.
- **`javax.faces`** — The servlet delegates to the core JSF API (`javax.faces.application.Application`, `javax.faces.lifecycle.Lifecycle`) for request processing.

## Notes for Developers

- **Stub class in this codebase:** The source file for `FacesServlet` in this repository is a minimal stub (`public class FacesServlet {}`). In a production JSF implementation, this class would be provided by the JSF runtime library (e.g., Mojarra or MyFaces shipped as a JAR dependency). Do not expect to find lifecycle implementation code in this file — the real implementation comes from the classpath dependency.
- **URL mapping matters:** The behavior of `FacesServlet` is driven by how it is mapped in `web.xml`. Common mappings include `*.jsf`, `*.faces`, or `/faces/*`. Each mapping affects which URLs trigger the JSF lifecycle.
- **One servlet per application:** A JSF web application typically declares exactly one instance of `FacesServlet`. Multiple mappings can point to the same servlet instance.
- **Thread-safe by design:** The `FacesServlet` implementation must be thread-safe since a single instance handles concurrent requests. The JSF runtime manages thread-local storage for request-scoped data to achieve this.