# Javax

## Overview

This area of the codebase serves as the **JavaServer Faces (JSF)** web framework root. JSF is a component-based server-side UI framework for Java EE and Jakarta EE applications. It provides a standardized approach to building web user interfaces in Java by abstracting the HTTP request-response cycle into a structured, phase-driven lifecycle.

At the top level, `javax.faces` represents the entry-point layer that bridges the servlet container with the rest of the JSF runtime. It exposes the full JSF request lifecycle through a standard servlet (`FacesServlet`), which acts as the single gate through which all JSF-related HTTP traffic flows. From there, requests flow through six lifecycle phases that interact with component trees, converters, validators, navigation rules, and managed beans.

This package is primarily a **structural namespace root** — the parent package itself contains no direct types. Its purpose is to house sub-packages (like `webapp`) that implement the web-tier integration, while the parent delegates all concrete work to its children.

## Sub-module Guide

This module has one active sub-module:

### `javax.faces` → `webapp` (Webapp Integration)

The `webapp` sub-package is the sole concrete module within `javax.faces` at this level. It provides **`FacesServlet`**, the servlet class that serves as the gateway between the HTTP world (servlet container, `HttpServletRequest`, `HttpServletResponse`) and the JSF world (`FacesContext`, `Lifecycle`, component tree).

`FacesServlet` is the type you configure in `web.xml` (or let the framework auto-discover via `WebApplicationInitializer` in Servlet 3.0+ environments) to intercept JSF requests. Without it, the rest of the JSF runtime has no entry point from the web container.

The relationship is fundamentally **one-directional**: the webapp layer depends on and delegates to the rest of the JSF framework. There are no sibling sub-modules that feed back into `webapp` — it is the sole inbound point from HTTP into the JSF runtime.

Other packages in the broader `javax.faces.*` namespace (such as `application`, `component`, `context`, `lifecycle`, `renderkit`) provide the infrastructure that `FacesServlet` delegates to, but they sit at a different level in the package hierarchy — they are not tracked as children of the `javax.faces` parent module here.

### How the pieces fit together

```mermaid
flowchart LR
    Client["Client Browser"] -->|"HTTP Request"| Servlet["FacesServlet
(webapp)"]
    Servlet -->|"Creates"| FC["FacesContext
(request-scoped)"]
    Servlet -->|"Delegates to"| LC["Lifecycle
(javax.faces.lifecycle)"]
    LC -->|"Phase 1"| RVP["Restore View"]
    LC -->|"Phase 2"| ARV["Apply Request Values"]
    LC -->|"Phase 3"| PV["Process Validations"]
    LC -->|"Phase 4"| UMV["Update Model Values"]
    LC -->|"Phase 5"| IA["Invoke Application"]
    LC -->|"Phase 6"| RR["Render Response"]
    RVP --> VC["View Configuration
(faces-config.xml)"]
    PV --> VLD["Validators"]
    ARV --> CV["Converters"]
    IA --> BEAN["Managed Beans"]
    RR -->|"HTML Response"| Client
    FC -->|"Wrapped by"| EC["ExternalContext"]
    EC -->|"Bridges"| SERV["Servlet API
(HttpServletRequest)"]
```

This diagram shows the end-to-end flow: an HTTP request arrives at `FacesServlet`, which creates a request-scoped `FacesContext` and delegates to a `Lifecycle` instance to run through the six phases. Each phase touches specific infrastructure — view configuration, converters, validators, and managed beans — before the final response is rendered as HTML.

## Key Patterns and Architecture

### Servlet as Lifecycle Gateway

The central architectural decision is delegating the HTTP entry point to a single servlet class. `FacesServlet` does not implement the JSF lifecycle itself — it obtains a `Lifecycle` instance from the `Application` and delegates phase execution to it. This decouples request dispatch from phase execution, allowing implementations to swap lifecycle behavior without modifying the servlet.

### Request-Scoped Context Isolation

Each HTTP request produces its own `FacesContext` instance, wrapped by an `ExternalContext` that bridges servlet types (`HttpServletRequest`, `HttpServletResponse`) to the JSF abstraction. The `FacesContext` is accessed via `FacesContext.getCurrentInstance()`, which looks it up on a `ThreadLocal`. This ensures that lifecycle data (view state, conversion results, validation messages, flash scope) is isolated per-request and does not leak across threads.

### Phase-Based Lifecycle Pipeline

The JSF request lifecycle is a six-phase pipeline that `FacesServlet` orchestrates by delegation:

1. **Restore View** — Reconstructs the component tree from the view state or creates a new one.
2. **Apply Request Values** — Populates component value holders from request parameters.
3. **Process Validations** — Runs registered validators against the submitted values.
4. **Update Model Values** — Copies validated values into the backing bean properties.
5. **Invoke Application** — Executes application logic (action methods, navigation).
6. **Render Response** — Renders the component tree as HTML (or another response format).

Each phase is independent and can be extended via phase listeners registered in `faces-config.xml`. This pipeline model ensures a deterministic, predictable flow through every JSF request.

## Dependencies and Integration

### Inbound Dependencies

| Artifact | Relationship |
|---|---|
| `web.xml` / `web-full.xml` | Declares and maps `FacesServlet` with a URL pattern |

These deployment descriptors are the primary glue connecting the servlet to the servlet container. Without them, the framework has no URL pattern to intercept. In Servlet 3.0+ environments, JSF implementations often auto-configure `FacesServlet` via a `WebApplicationInitializer`, making the `<servlet>` element optional.

### Framework Dependencies

| Dependency | Role |
|---|---|
| `servlet-api` | `FacesServlet` extends `HttpServlet` and uses `HttpServletRequest` / `HttpServletResponse` types |
| `jsf-api` | Core types (`FacesContext`, `ExternalContext`, `Application`, `Lifecycle`) live in `javax.faces.*` packages |
| `jsf-impl` | Runtime implementations (e.g., `LifecycleImpl`, `ApplicationImpl`) are provided by the JSF implementation on the classpath (Mojarra, MyFaces, etc.) |

### Extension Points

- **Filters** — To intercept requests before or after the JSF lifecycle, place a `javax.servlet.Filter` before or after `FacesServlet` in the filter chain. This is the recommended approach for logging, authentication, or response modification.
- **Phase Listeners** — Registered via `faces-config.xml`, phase listeners receive callbacks at every phase boundary, enabling cross-cutting concerns like auditing or performance monitoring.
- **WebApplicationInitializer** — In Servlet 3.0+ environments, JSF implementations provide auto-configuration that discovers and sets up `FacesServlet` if no explicit mapping is found.

## Notes for Developers

- **Do not subclass `FacesServlet` directly.** Use servlet `Filter`s for pre- and post-interception logic instead.
- **URL pattern matters.** The pattern you map to `FacesServlet` determines which requests enter the JSF lifecycle. A misconfigured pattern can result in requests being served by other servlets or returning 404s.
- **`FacesContext` is strictly request-scoped.** Do not store it as an instance field. Access it via `FacesContext.getCurrentInstance()` within the request thread.
- **Auto-configuration exists.** In Servlet 3.0+ environments, JSF implementations auto-discover and configure `FacesServlet` if the deployment descriptor omits it.
- **No indexed source files at the parent level.** The parent `javax.faces` package itself contains no direct classes — all work is delegated to sub-packages. This is by design; `javax.faces` serves as the namespace root, not a container for types.