# Javax / Faces / Webapp

This module (`javax.faces.webapp`) is the web-facing entry point for JavaServer Faces (JSF) applications. It provides the servlet that intercepts HTTP requests destined for JSF-managed pages and delegates them to the broader JSF lifecycle.

> **Note:** The source class `FacesServlet` in this codebase is a stub definition (an empty class within the `javax.faces.webapp` package). In a complete JSF implementation, this class contains the production logic for request dispatching. The documentation below describes the standard JSF role of this component as informed by the specification and its usage in configuration.

## Overview

The `javax.faces.webapp` package sits at the boundary between the HTTP servlet container and the JSF framework. Its primary responsibility is to expose the JSF request-processing lifecycle as a standard `javax.servlet.Servlet`, allowing JSF applications to be deployed in any servlet-compliant web container (e.g., Tomcat, Jetty, WildFly).

## Key Classes and Interfaces

### FacesServlet

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

The `FacesServlet` is the central dispatcher for all JSF requests. It is the sole class in this package.

#### Purpose

In a standard JSF deployment, `FacesServlet` serves as the front controller:

1. It intercepts incoming HTTP requests matching its URL pattern (typically `*.jsf`, `*.faces`, or `/faces/*`).
2. It parses the JSF lifecycle request parameters and identifies which view (page) is being requested.
3. It invokes the JSF lifecycle — Restore View, Apply Request Values, Process Validations, Update Model, Invoke Application, Render Response — for that view.
4. It writes the generated HTML response back to the client.

#### Current State

In this repository, `FacesServlet` is defined as an empty class skeleton:

```java
package javax.faces.webapp;
public class FacesServlet {}
```

This indicates it is either a placeholder for a real implementation that lives in another artifact (such as a JSF provider library like Mojarra or MyFaces), or a stub for build-time / packaging purposes.

## How It Works

In a complete JSF implementation, a typical request flows through `FacesServlet` as follows:

```mermaid
flowchart LR
    W["web-full.xml
(Servlet Config)"] --> FS["FacesServlet"]
    FS --> LC["JSF Lifecycle
(6 Phases)"]
    LC --> V["View
(Managed Bean + Facelets)"]
    LC --> RESP["HTTP Response
(HTML Output)"]
```

1. **Deployment:** `web-full.xml` declares `FacesServlet` with a URL pattern mapping so that the servlet container routes matching requests to it.
2. **Request Arrival:** The container receives an HTTP request whose URL matches the `FacesServlet` mapping.
3. **Lifecycle Invocation:** `FacesServlet` hands the request off to the JSF `FacesContext`, which runs through the six-phase lifecycle.
4. **Response:** After the lifecycle completes, the response is committed back to the HTTP response.

## Data Model

No entity or DTO classes are present in this package. `FacesServlet` is a stateless dispatcher — it holds no persistent data, relying instead on `FacesContext` (maintained per-request) for request-scoped state.

## Dependencies and Integration

### Configuration

- **`web-full.xml`** declares and configures `FacesServlet` as a servlet in the web application deployment descriptor. This is the standard mechanism for wiring a servlet to a URL pattern and initialization parameters.

### External Dependencies

- **Servlet API (`javax.servlet`):** `FacesServlet` extends `javax.servlet.GenericServlet` (or `HttpServlet`) in a full implementation, inheriting the standard servlet lifecycle.
- **JSF Core (`javax.faces`):** It depends on the core JSF runtime (`FacesContext`, `Lifecycle`, `UIViewRoot`, etc.) to perform the actual page processing.
- **JSF Spec (`javax.faces.webapp`):** This package is part of the JSR 372 (JavaServer Faces 2.3) specification.

## Notes for Developers

- **Stub class:** The `FacesServlet` in this codebase is an empty class. Do not expect implementation details here — the real behavior is in the JSF provider library at runtime.
- **URL pattern matters:** The behavior of `FacesServlet` is heavily dependent on how it is mapped in `web.xml` / `web-full.xml`. Common patterns include `*.jsf` for extension-based mapping or `/faces/*` for path-based mapping.
- **Thread safety:** Like all servlets, `FacesServlet` must be thread-safe. State is never stored in instance fields; per-request state is held in the `ThreadLocal`-backed `FacesContext`.
- **One servlet per application:** JSF requires exactly one `FacesServlet` instance per web application. Multiple mappings to the same servlet (e.g., both `*.jsf` and `/faces/*`) are common and supported.