# Javax / Faces

## Overview

The `javax.faces` package represents the top-level namespace for **JavaServer Faces (JSF)**, a component-based web framework for building server-driven user interfaces in Java EE / Jakarta EE applications. JSF follows the Model-View-Controller (MVC) pattern and provides a stack-based component model where server-side UI components are rendered to HTML (or other formats) and wired to backing beans through a declarative lifecycle.

This area of the codebase exposes the public API surface of the framework -- the classes, interfaces, and annotations that application developers and component library authors interact with. The framework's runtime behavior spans several subpackages: the core API (lifecycle, context management, component tree) and the web integration layer (`javax.faces.webapp`) that connects JSF to the servlet container.

The `javax.faces.webapp` subpackage, in particular, provides the `FacesServlet` -- the central front-controller servlet that all JSF requests flow through. It coordinates the six-phase JSF lifecycle for every intercepted HTTP request: restore view, apply request values, process validations, update model values, invoke application, and render response.

## Sub-module Guide

### `javax.faces.webapp`

The webapp subpackage is the bridge between the servlet container and the JSF runtime. It contains the `FacesServlet`, which acts as the single entry point for all JSF-related requests. When the servlet container receives a request matching the configured URL pattern (e.g., `*.jsf` or `/faces/*`), it hands control to `FacesServlet`, which then:

1. Creates a request-scoped `FacesContext` holding all per-request state.
2. Dispatches the request through the JSF lifecycle phases.
3. Renders the component tree into an HTTP response.
4. Cleans up the `FacesContext`.

**How it relates to the broader package:** The `FacesServlet` in `javax.faces.webapp` is the *entry* point into the `javax.faces` namespace. It delegates the heavy lifting -- component tree management, validation, event handling, rendering -- to core classes in other subpackages of `javax.faces` (such as `javax.faces.context`, `javax.faces.lifecycle`, and `javax.faces.component`). The webapp package has no classes of its own beyond the servlet; it exists purely as the integration layer.

## Key Patterns and Architecture

### Front Controller Pattern

The `FacesServlet` implements the front controller pattern: a single servlet receives all JSF requests and dispatches them through a canonical processing pipeline. This centralizes request handling, makes URL routing declarative (via `web.xml`), and ensures every request follows the same lifecycle.

### Six-Phase Lifecycle

JSF processes each request through a deterministic six-phase lifecycle, each phase performing a distinct responsibility:

1. **Restore View** -- Reconstructs the component tree from the saved view state, or creates a fresh tree for initial page loads.
2. **Apply Request Values** -- Populates each component's local value from request parameters.
3. **Process Validations** -- Runs registered validators against component values.
4. **Update Model Values** -- Writes validated values into backing bean properties.
5. **Invoke Application** -- Fires application-level events (e.g., button action handlers).
6. **Render Response** -- Walks the component tree and renders the response in the target format (typically HTML).

This phased approach separates concerns cleanly: input collection, validation, business logic, and output rendering happen in distinct steps, each with its own error-handling exit points.

### Per-Request Context

Each request receives its own `FacesContext` instance, which holds request-scoped state including parameter maps, view references, and locale. The `FacesServlet` is responsible for creating and releasing this context, ensuring no state leaks between requests.

### Component Tree Model

JSF uses a tree of server-side UI component objects to represent the page. The `UIViewRoot` is the root of this tree. Components are rendered through a pluggable render kit architecture -- by default HTML, but other formats (WML, XHTML, PDF) are supported. This decouples component logic from presentation.

## Dependencies and Integration

The `javax.faces` package connects to the broader ecosystem as follows:

- **Servlet API (`javax.servlet.*`)** -- The web layer depends on the servlet container for HTTP handling. `FacesServlet` extends `HttpServlet`.
- **Deployment descriptors (`web.xml`, `web-full.xml`)** -- The FacesServlet is registered and mapped in standard Java EE web descriptors, tying the framework into the application server's request routing.
- **Backing beans (application code)** -- JSF components bind to managed beans (or CDI beans in modern deployments) through EL expressions, giving the framework access to application state and business logic.
- **Render kits (application code or libraries)** -- Custom renderers and render kits can replace the default HTML output, enabling non-browser clients or alternative markup formats.

```mermaid
flowchart LR
    Browser["Browser / Client"] -->|HTTP request| WebXML["web.xml
URL mapping"]
    WebXML --> FacesServlet["FacesServlet
javax.faces.webapp"]
    FacesServlet --> FacesContext["FacesContext
per-request state"]
    FacesContext --> Lifecycle["JSF Lifecycle
6 phases"]
    Lifecycle --> ComponentTree["Component Tree
UIViewRoot + children"]
    ComponentTree --> RenderKit["Render Kit
HTML output"]
    RenderKit -->|HTTP response| Browser
```

## Notes for Developers

- The `FacesServlet` source in this codebase is a minimal stub. A production implementation would contain the full lifecycle delegation logic. If you are implementing or extending this class, refer to the [Jakarta Faces specification](https://jakarta.ee/specifications/faces/) for the complete lifecycle API.
- The `javax.faces` namespace is the **Java EE** variant. In Jakarta EE 9+ (JSF 3.x+), the package was renamed to `jakarta.faces.*`. Migration between the two requires namespace replacement across all imports and deployment descriptors.
- URL mapping is the primary configuration point for controlling which requests JSF processes. This is defined in the deployment descriptor, not in code, following standard Java EE servlet conventions.
- The `FacesServlet` registration appears in both `web.xml` and `web-full.xml`, which means the servlet is set up through the standard Java EE web deployment mechanism -- no custom bootstrap code is required beyond what the application server handles.
- Memory management is critical: the `FacesServlet` must clean up the `FacesContext` after each request to avoid leaks. This is typically done in a `finally` block within the `service()` method.