# Javax / Faces

## Overview

`javax.faces` is the root package for JavaServer Faces (JSF), the Java EE framework for building component-based user interfaces in web applications. This module represents the entire JSF API surface, providing the contracts and abstractions for a request-driven, stateful MVC framework — from component trees and managed beans to event handling and navigation.

Within this codebase, the `javax.faces` area appears as a skeleton or reference API. Source files and classes have not been indexed, which suggests the real implementation lives in external JSF runtime libraries (such as Mojarra or MyFaces) rather than in the project's own source. What does exist is the structural scaffolding — package declarations and stubs — that define how a web application wires into the JSF model.

The most concrete artifact in this area is the `javax.faces.webapp` subpackage, which provides the servlet and JSP tag handler bridge between the HTTP world and the JSF lifecycle.

## Sub-module Guide

### webapp — The Web Integration Layer

The `javax.faces.webapp` subpackage is the primary (and currently only) child module of `javax.faces` in this codebase. Its job is to connect the servlet container's request model to JSF's lifecycle model.

**What it does:** This subpackage exposes `FacesServlet`, the single entry point that a JSF application registers in `web.xml`. Every HTTP request matching the servlet mapping flows through `FacesServlet`, which then hands the request off to the JSF lifecycle — a six-phase process (RestoreView, ApplyRequestValues, ProcessValidations, UpdateModelValues, InvokeApplication, RenderResponse) that the JSF specification mandates.

**How it relates to the parent:** `javax.faces.webapp` is the web-facing edge of the `javax.faces` API. The parent package defines the contracts (Application, Lifecycle, FacesContext) while `webapp` provides the concrete servlet implementation that puts those contracts into action. If you think of `javax.faces` as the spec and `javax.faces.webapp` as the bridge, the former defines what JSF does and the latter defines how HTTP becomes JSF.

## How the Pieces Fit Together

```mermaid
flowchart TD
    WEB["web-full.xml<br/>deployment descriptor"] --> SERV["FacesServlet<br/>javax.faces.webapp"]
    SERV -->|Declared as servlet| CONTAINER["Servlet Container<br/>e.g. Tomcat, GlassFish"]
    CONTAINER -->|HTTP Request| SERV
    SERV -->|Delegates| LIFECYCLE["JSF Lifecycle<br/>(javax.faces.lifecycle)"]
    LIFECYCLE --> PHASE1["RestoreView"]
    LIFECYCLE --> PHASE2["ApplyRequestValues"]
    LIFECYCLE --> PHASE3["ProcessValidations"]
    LIFECYCLE --> PHASE4["UpdateModelValues"]
    LIFECYCLE --> PHASE5["InvokeApplication"]
    LIFECYCLE --> PHASE6["RenderResponse"]
    PHASE4 --> BEANS["Managed Beans<br/>Application Model"]
    PHASE6 --> VIEW["JSF View<br/>Facelets / JSP"]
```

1. The **deployment descriptor** (`web-full.xml`) registers `FacesServlet` as the servlet to handle JSF URL patterns.
2. The **servlet container** dispatches matching HTTP requests to `FacesServlet`.
3. `FacesServlet` **delegates** to the JSF lifecycle, which runs through its six phases.
4. During those phases, **managed beans** supply application state and **JSF view templates** produce the final HTML response.

## Key Patterns and Architecture

- **Front Controller pattern:** `FacesServlet` acts as a front controller, centralizing request handling and funneling all JSF traffic through a single entry point. This is the classic JSF architecture — one servlet per application.

- **Phase-based lifecycle:** The JSF request is processed through six distinct phases, each with a well-defined responsibility. This phased approach allows component tree restoration, user input capture, validation, model updates, business logic execution, and view rendering to be cleanly separated.

- **Stub implementation:** In this codebase, `FacesServlet` appears as a minimal class stub (`public class FacesServlet {}`). The real lifecycle implementation is expected from the JSF runtime JAR on the classpath. This codebase provides the API skeleton; the production behavior comes from the dependency.

- **Request-scoped context:** JSF uses a `FacesContext` object (defined in the parent `javax.faces` package) that is bound to each request via thread-local storage, enabling thread-safe concurrent request handling.

## Dependencies and Integration

### Inbound Dependencies

- **`web-full.xml`** — The deployment descriptor registers `FacesServlet` with the servlet container:

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

  This appears in the project's [`web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml), confirming the application is JSF-capable.

### Outbound Dependencies

- **`javax.servlet`** — `FacesServlet` integrates with the servlet API, extending `HttpServlet` to receive HTTP requests.
- **`javax.faces` core packages** — The webapp subpackage delegates to the core JSF API (`javax.faces.application.Application`, `javax.faces.lifecycle.Lifecycle`) for the actual request processing.
- **External JSF runtime** — The production implementation of `FacesServlet` and the lifecycle comes from a JSF implementation library (e.g., Mojarra or MyFaces) on the classpath.

## Notes for Developers

- **Don't look for lifecycle code here:** The `FacesServlet` stub in this repository is a placeholder. The real implementation lives in the JSF runtime dependency. Do not expect to find phase logic, view restoration, or rendering code in this source tree.

- **URL mapping drives behavior:** How `FacesServlet` is mapped in `web.xml` (e.g., `*.jsf`, `*.faces`, `/faces/*`) determines which URLs trigger the JSF lifecycle. Changes to the mapping are the primary lever for routing behavior.

- **Single instance, thread-safe:** JSF declares exactly one `FacesServlet` per application. The runtime uses thread-local storage to isolate per-request data, so the servlet must be thread-safe.

- **No indexed classes or source files:** This module currently has zero indexed source files, classes, interfaces, or methods. The API contract is defined externally; this documentation reflects the structural role the package plays rather than concrete implementation details.

- **Sub-module is minimal:** `javax.faces.webapp` is currently the only child module under `javax.faces`. Other JSF subpackages (such as `javax.faces.component`, `javax.faces.render`, `javax.faces.event`) are expected from the runtime library and are not present in this codebase's index.