# Javax / Faces

## Overview

The `javax.faces` package is a top-level Java EE package that provides the foundation for **JavaServer Faces (JSF)** — the component-based UI framework defined by [JSR 372 (JavaServer Faces 2.3)](https://jakarta.ee/specifications/faces/). JSF enables developers to build server-driven web user interfaces using reusable UI components, declarative view definitions, and a well-defined request-processing lifecycle.

This package is split across several sub-packages under the `javax.faces` namespace. The most prominent child module documented here is **`webapp`**, which provides the servlet front-controller (`FacesServlet`) that bridges HTTP requests from the servlet container into the JSF framework.

The `javax.faces` namespace as a whole represents a layered architecture:

- **Core API** (`javax.faces`) — the base classes and interfaces that define the JSF programming model (e.g., `FacesContext`, `Lifecycle`, `UIViewRoot`, `FacesException`).
- **Web integration** (`javax.faces.webapp`) — the `FacesServlet` and related utilities that expose the JSF lifecycle as a standard servlet, allowing JSF to run in any servlet-compliant container.
- **UI component tier** (`javax.faces.component`, `javax.faces.render`, etc.) — component classes, renderer factories, and HTML output generators (not yet indexed in this repository).
- **State management** (`javax.faces.view`, `javax.faces.application`) — view state, navigation handling, and resource resolution (not yet indexed).

> **Note:** No source files are currently indexed under `javax.faces` itself. The classes documented here are stub definitions or spec-api references. The production implementations live in JSF provider libraries such as [Mojarra](https://github.com/eclipse-ee4j/mojarra) or [MyFaces](https://myfaces.apache.org/).

## Sub-module Guide

This module currently has one documented child sub-module:

### `javax.faces.webapp` — Web Front-Controller

The `webapp` sub-package is the **entry point** between the HTTP servlet container and the JSF framework. It contains the `FacesServlet` class, which acts as the front-controller for all JSF requests. This is the only source class currently defined in this package in the repository.

**What `FacesServlet` does:**

1. Intercepts incoming HTTP requests matching a URL pattern (e.g., `*.jsf` or `/faces/*`).
2. Creates a per-request `FacesContext` instance that holds request-scoped state.
3. Invokes the JSF six-phase lifecycle: **Restore View → Apply Request Values → Process Validations → Update Model → Invoke Application → Render Response**.
4. Writes the generated HTML response back to the client.

**How `webapp` relates to the broader system:**

`FacesServlet` is the gateway. Every user interaction with a JSF application funnels through this single servlet, which then delegates into the rest of the `javax.faces` ecosystem. Without the `webapp` layer, JSF would not be deployable in a servlet container — it is the bridge that makes JSF a web framework rather than just an API.

## Key Patterns and Architecture

### Front-Controller Pattern

`FacesServlet` implements the classic **Front Controller** pattern. It is the single entry point for all JSF requests, centralizing the request-to-lifecycle dispatch logic. This keeps request handling consistent and allows the JSF framework to manage state, validation, and rendering uniformly.

### Six-Phase Lifecycle

At the heart of JSF is a request-processing lifecycle that executes exactly six phases in order:

1. **Restore View** — Reconstruct the component tree from the previous request's state.
2. **Apply Request Values** — Populate component local values from the incoming HTTP request parameters.
3. **Process Validations** — Run validators registered on each component and collect conversion errors.
4. **Update Model** — Transfer validated component values into backing bean (managed bean) properties.
5. **Invoke Application** — Execute action listeners, command handlers, and navigation logic.
6. **Render Response** — Build the HTML (or other format) output by rendering each component via its renderer.

This lifecycle is invoked by `FacesServlet` for every request that it dispatches. The same request may re-enter the lifecycle multiple times (e.g., if validation fails, the Render Response phase may be reached early from Restore View).

### Per-Request Context

Each request gets its own `FacesContext` instance, stored in a `ThreadLocal`. This context is the single source of truth for the current request — it holds the component tree, application configuration, external context (raw `HttpServletRequest`/`HttpServletResponse`), and flash scope. `FacesServlet` has no instance fields; all state is per-request, ensuring thread safety.

### Request Flow

The following diagram shows how a typical JSF request flows through the system:

```mermaid
flowchart TD
    CLIENT["HTTP Client"] --> CONTAINER["Servlet Container
(Tomcat, Jetty, WildFly)"]
    CONTAINER --> FS["FacesServlet
javax.faces.webapp"]
    FS --> FC["FacesContext
javax.faces"]
    FS --> LC["JSF Lifecycle
6 Phases"]
    LC --> MB["Managed Bean
javax.faces"]
    LC --> FL["Facelets / View
javax.faces"]
    LC --> RESP["HTML Response
via HTTP"]
```

### Stub vs. Production

In this repository, `FacesServlet` is defined as an empty class skeleton. The real implementation lives in the JSF provider library (Mojarra or MyFaces) at runtime. This means:

- The source-level code is a placeholder for build-time or packaging purposes.
- The documented behavior comes from the JSF specification and standard usage patterns.
- Developers should not expect implementation details here — production logic is in the provider JAR.

## Dependencies and Integration

### Internal Dependencies

- **`javax.faces` core API** — `FacesServlet` depends on core classes like `FacesContext`, `Lifecycle`, and `Application` (not yet indexed under `javax.faces` itself).
- **`javax.servlet` API** — `FacesServlet` extends the standard servlet API in a full implementation, inheriting the servlet lifecycle (`init`, `service`, `destroy`).

### External Dependencies

- **Servlet container** — JSF runs inside a servlet container (Tomcat, Jetty, WildFly, etc.). The container manages the servlet lifecycle and routes HTTP requests based on URL patterns configured in `web-full.xml`.
- **JSF provider library** — At runtime, the actual `FacesServlet` implementation comes from the JSF provider (Mojarra or MyFaces), not the spec API JAR. The provider JAR is typically included as a dependency in the web application.

### Configuration

`FacesServlet` is configured via `web-full.xml` (or `web.xml` with proper namespace):

```xml
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.jsf</url-pattern>
</servlet-mapping>
```

Common URL patterns include `*.jsf`, `*.faces`, `/faces/*`, or even `/faces/*` combined with `*.jsf` for flexibility.

## Notes for Developers

- **One servlet per application.** JSF requires exactly one `FacesServlet` instance per web application. Multiple URL pattern mappings to the same servlet are common and fully supported.
- **Thread-safe by design.** `FacesServlet` is stateless — no instance fields hold per-request data. All request state lives in `FacesContext`, backed by `ThreadLocal`.
- **URL pattern dictates behavior.** The URL pattern mapped to `FacesServlet` determines which requests enter the JSF lifecycle and which pass through directly to other servlets (e.g., static resources, REST endpoints).
- **Stub class in this repo.** The `FacesServlet` source is an empty class. Production behavior is provided by the JSF runtime library at deploy time.
- **No source files indexed.** The `javax.faces` package itself has no indexed source files in this repository. This is expected — `javax.faces` is the API layer; the implementation lives in the provider library.