# Javax / Faces

## Overview

The `javax.faces` package is the root of the **JavaServer Faces (JSF)** API — a server-side MVC (Model-View-Controller) framework defined by the Java EE / Jakarta EE specification for building component-based user interfaces in Java web applications. JSF manages the entire request lifecycle, from parsing incoming HTTP requests to rendering HTML responses, providing a structured, phase-driven model that decouples UI components from business logic.

This package serves as the entry point for all JSF-powered web applications. It does not contain a rich internal sub-module hierarchy itself; instead, its primary sub-packages (such as `javax.faces.webapp`) plug the framework into the Servlet container, while related packages (`javax.faces.component`, `javax.faces.lifecycle`, `javax.faces.el`, etc.) handle component trees, the seven-phase lifecycle, and expression language evaluation respectively.

## Sub-module Guide

### webapp

The `javax.faces.webapp` sub-package provides the bridge between the JSF lifecycle and the Java Servlet specification. Its sole class, `FacesServlet`, acts as the **front-controller** for every JSF application — the single servlet declared in `web.xml` that receives all requests mapped to JSF URL patterns (e.g. `*.faces` or `/faces/*`).

`FacesServlet` translates incoming HTTP requests into the standardized JSF seven-phase lifecycle:

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

Within this fixture, `FacesServlet` is declared as an empty class body — a deployment descriptor target rather than a full implementation. The actual lifecycle orchestration logic is provided by the JSF reference implementation (e.g. Apache MyFaces or Mojarra). This makes `FacesServlet` the registration point: developers declare it in their web descriptor, and the container hands incoming requests to it for lifecycle processing.

## Key Patterns and Architecture

### Front-Controller Pattern

`FacesServlet` implements the **front-controller** design pattern — a single servlet entry point that normalizes request handling. Every JSF request funnels through one `FacesServlet` instance, ensuring consistent lifecycle execution regardless of the page being requested.

### Phase-Driven Lifecycle

The core architectural decision of JSF is the **seven-phase request lifecycle**. Each phase is a discrete step that the container walks through sequentially. If any phase throws a `FacesException` or encounters a validation failure, the flow short-circuits and control transfers to the render phase with an error state. This deterministic flow gives framework developers a predictable hook points for interception and customization.

### Request-scoped Context

Per-request state is held in `FacesContext`, stored in a `ThreadLocal` to avoid concurrency issues. This means `FacesServlet` is thread-safe by design — a single instance serves all requests while thread-local state keeps each request isolated.

```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"]
```

## Dependencies and Integration

### Internal Dependencies

- **`javax.faces` core packages** — The broader JSF API provides the core abstractions (`FacesContext`, `Lifecycle`, component model, expression language) that `FacesServlet` orchestrates. While `javax.faces.webapp` is the only sub-package indexed under `javax.faces` in this fixture, production JSF deployments include additional sub-packages like `javax.faces.component`, `javax.faces.lifecycle`, and `javax.faces.el` for component trees, lifecycle execution, and EL evaluation respectively.

### External Dependencies

- **`javax.servlet`** — `FacesServlet` implements the `javax.servlet.Servlet` interface and operates entirely within the standard servlet container lifecycle. It depends on the container for thread management, URL mapping, and request/response object creation.

### Configuration Integration

`FacesServlet` is wired into the application through standard servlet deployment descriptors:

- **`web.xml`** — Declares `FacesServlet` and maps it to a URL pattern. This is the most common configuration approach.
- **`web-full.xml`** — An alternative full-profile web descriptor that may enable additional servlet features such as async support or custom filters.

Both files are used by the application server to register the servlet and are referenced by other modules in the codebase when setting up JSF-enabled web applications.

## Notes for Developers

- **Empty class in this fixture.** The source file (`FacesServlet.java`) contains only a class declaration with an empty body. In production JSF implementations, the class extends the reference implementation's internal `FacesServlet` base (from the Mojarra or MyFaces JAR). This fixture represents the minimal interface stub needed for deployment descriptor registration.
- **One servlet per application.** Declare exactly one `FacesServlet` instance per WAR file. JSF does not support multiple dispatcher servlets for the same application.
- **URL mapping is critical.** If the `*.faces` or `/faces/*` mapping is missing or misconfigured in `web.xml`, no JSF pages will render — requests will result in 404 errors.
- **Thread safety is guaranteed by design.** `FacesServlet` is instantiated once by the container and handles all requests through its `service()` method. Per-request state lives in `FacesContext` (a `ThreadLocal`), so there is no shared mutable state between requests.
- **Short-circuit behavior.** If any lifecycle phase fails, control skips remaining phases and jumps to render with an error state. This is intentional — the framework handles error rendering automatically when `FacesException` is thrown.