# Javax / Faces / Webapp

## Overview

This subpackage provides the Servlet-based entry point into JavaServer Faces (JSF) — the MVC framework defined by the Java EE / Jakarta EE specification. Its sole class, `FacesServlet`, acts as the central dispatcher that routes incoming HTTP requests through the JSF lifecycle, ensuring that request/response processing follows the standardized seven-phase flow.

## Key Classes and Interfaces

### FacesServlet

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

`FacesServlet` is the front-controller servlet for every JSF application. It is the class declared in `web.xml` or `web-full.xml` to handle requests mapped to JSF URL patterns (e.g. `*.faces` or `/faces/*`). It implements the `javax.servlet.Servlet` interface.

Its primary responsibility is to translate HTTP requests into a sequence of JSF lifecycle phases:

1. **Restore View** — Reconstructs the component tree from the previous state or creates a fresh one.
2. **Apply Request Values** — Populates UI component values from the HTTP request parameters.
3. **Process Validations** — Runs converter and validator logic on each component.
4. **Update Model Values** — Syncs validated UI component values into the backend JavaBeans / CDI backing beans.
5. **Invoke Application** — Executes application-level action listeners, navigation rules, and business logic.
6. **Render Response** — Builds and writes the HTML (or other format) response back to the client.

In this codebase the class body is minimal — the actual lifecycle orchestration logic is inherited from the JSF reference implementation (Apache MyFaces or Mojarra) or provided as an abstract superclass. The empty class declaration in this fixture serves as the deployment descriptor target: it is what application developers reference in their `web.xml` to register JSF with their container.

## How It Works

A typical JSF request flows through `FacesServlet` as follows:

```mermaid
flowchart TD
    A["HTTP Request"] --> B["FacesServlet.service"]
    B --> C["Restore View"]
    C --> D["Apply Request Values"]
    D --> E["Process Validations"]
    E --> F["Update Model Values"]
    F --> G["Invoke Application"]
    G --> H["Render Response"]
    H --> I["HTTP Response"]
```

1. The Servlet container receives an HTTP request that matches the URL pattern configured in the web descriptor.
2. `FacesServlet.service()` delegates the request into the `FacesContext`, creating the per-request JSF lifecycle context.
3. The JSF lifecycle engine walks through each phase. If any phase throws a `FacesException` or a validator fails, the flow short-circuits and control transfers to the render phase with an error state.
4. On success, the render phase generates the response markup.

## Data Model

This module does not define its own entity or DTO types. Instead, it operates on the JSF lifecycle abstractions — primarily `FacesContext` and `Lifecycle` — provided by the `javax.faces` and `javax.faces.lifecycle` packages.

## Dependencies and Integration

### External Dependencies

- **`javax.servlet`** — `FacesServlet` implements the Servlet interface and operates within the standard servlet container lifecycle.
- **`javax.faces`** — The broader JSF API (not present in this subpackage) provides the core lifecycle, context, and component model that `FacesServlet` orchestrates.

### Configuration

`FacesServlet` is wired into the application through the standard servlet configuration files:

- **`web.xml`** — The deployment descriptor declares `FacesServlet` and maps it to a URL pattern.
- **`web-full.xml`** — An alternative full-profile web descriptor that may be used to enable additional servlet features (e.g. async support, filters).

These XML configs are used by other modules in the codebase to register the servlet.

## Notes for Developers

- **Empty class in this fixture.** The source file contains only a class declaration with an empty body (`public class FacesServlet {}`). In production JSF implementations, the class extends the JSF reference implementation's internal `FacesServlet` base (e.g. `javax.faces.webapp.FacesServlet` from the Mojarra or MyFaces JAR). This fixture likely represents the minimal interface stub.
- **URL mapping is critical.** If the `*.faces` or `/faces/*` mapping is missing or misconfigured in `web.xml`, no JSF page will render — the request will result in a 404.
- **One servlet per application.** You should declare exactly one `FacesServlet` instance per WAR. JSF does not support multiple dispatcher servlets for the same application.
- **Thread safety.** `FacesServlet` is instantiated once by the container and handles all requests through its `service()` method. The per-request state is kept in `FacesContext`, which is stored in a `ThreadLocal` to avoid concurrency issues.