# Javax / Faces

## Overview

The `javax.faces` package is the root namespace for the [JavaServer Faces (JSF)](https://jakarta.ee/specifications/faces/) web framework. JSF is a component-based server-side UI framework for Java EE / Jakarta EE applications. At the top level, this area of the codebase represents the entry-point layer that bridges the servlet container with the rest of the JSF runtime — specifically, it exposes the full JSF request lifecycle as a standard `javax.servlet.Servlet`.

In practice, this package exists to give web containers a single, well-known entry class (`FacesServlet`) through which all JSF-related HTTP traffic flows. From there, the request is processed through six lifecycle phases (Restore View through Render Response), interacting with the core JSF APIs, converters, validators, navigation rules, and managed beans defined elsewhere in the framework.

This appears to be primarily a structural grouping — the parent package itself contains no direct types. Its purpose is to house the `webapp` sub-module (and any future sub-packages) that implement the web-tier integration.

## Sub-module Guide

This area contains one active sub-module:

### `javax.faces.webapp` — Webapp Integration

The `webapp` package provides the sole public type: **`FacesServlet`**. This servlet is the gateway between the HTTP world (servlet container, `HttpServletRequest`, `HttpServletResponse`) and the JSF world (`FacesContext`, `Lifecycle`, component tree).

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

Within `javax.faces`, `webapp` is the only concrete web-facing module. Other packages in the broader `javax.faces.*` namespace (such as `application`, `component`, `context`, `lifecycle`, `renderkit`) provide the infrastructure that `FacesServlet` delegates to, but they are not tracked as children of this parent module.

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.

## Key Patterns and Architecture

### Servlet as Lifecycle Gateway

The central architectural decision in this package 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 touching the servlet.

### Request-Scoped Context Isolation

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

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

### Phase-based Lifecycle

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 the 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`.

## Dependencies and Integration

### Inbound Dependencies

| Artifact | Relationship |
|---|---|
| `web.xml` | Declares and maps `FacesServlet` |
| `web-full.xml` | Declares and maps `FacesServlet` (full profile) |

These deployment descriptors are the primary glue connecting the servlet to the servlet container. Without them, the framework has no URL pattern to intercept.

### 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** — If you need 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.
- **WebApplicationInitializer** — In Servlet 3.0+ environments, JSF implementations often provide a `WebApplicationInitializer` that auto-configures `FacesServlet` if no explicit mapping is found, allowing projects to omit the `<servlet>` declaration entirely.

## Notes for Developers

- **Do not subclass `FacesServlet` directly.** Use servlet `Filter`s for pre/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. This means the `<servlet>` element in `web.xml` is optional in modern deployments.
- **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.