# Javax / Faces

## Overview

The `javax.faces` package is the top-level namespace for the **JavaServer Faces (JSF)** framework within this codebase. JSF is a component-based web framework for Java EE that provides a model-view-controller (MVC) architecture, automatic state management, server-side component lifecycle, and data binding to backing beans.

This package itself is structural — it serves as the parent namespace that groups related sub-packages. The actual runtime implementation lives in its sub-modules, most notably `javax.faces.webapp`. The package's purpose is to organize the framework's concern into logical layers: the web-facing front controller (webapp) and, by extension, the context, lifecycle, rendering, and component packages that the web layer depends on but are not directly indexed in this module.

In this codebase, no source files are indexed at the `javax.faces` package level itself. The real work is delegated to child modules, with the webapp package being the primary documented sub-module.

## Sub-module Guide

### javax.faces.webapp

The `javax.faces.webapp` package is the web-layer entry point for JSF applications. It provides the `FacesServlet`, which implements the front controller pattern and bridges Java Servlet requests into the JSF component lifecycle.

**What it does:**

- Acts as the single entry point for all JSF requests, intercepting them based on URL pattern mappings defined in `web.xml`.
- Creates a `FacesContext` for each request, which encapsulates request/response/session/application scope data throughout the lifecycle.
- Delegates lifecycle execution to the JSF `Lifecycle` abstraction, which coordinates the six-phase request processing model:
  1. Restore View
  2. Apply Request Values
  3. Process Validations
  4. Update Model Values
  5. Invoke Application
  6. Render Response

**How it relates to the broader system:**

The `webapp` package is the bridge between the servlet container (Tomcat, Jetty, WildFly, etc.) and the rest of the JSF framework. It depends on — and orchestrates — several other JSF sub-packages that work together as follows:

- `javax.faces.context` provides the `FacesContext` object that `FacesServlet` creates per-request.
- `javax.faces.lifecycle` defines the `Lifecycle` abstraction that executes the six processing phases.
- `javax.faces.component` manages the server-side component tree, which is built and restored during the Restore View phase.
- `javax.faces.render` controls how components are converted to HTML (or other formats) during the Render Response phase.
- `javax.faces.el` handles expression language evaluation and data binding to backing beans.

The `FacesServlet` itself does not implement the lifecycle logic — it delegates to the `Lifecycle` manager obtained via the `FactoryFinder`. This separation allows different lifecycle implementations to be swapped at runtime and keeps the servlet a thin adapter layer.

## Key Patterns and Architecture

### Front Controller Pattern

`FacesServlet` is a canonical implementation of the front controller pattern. All JSF requests flow through this single servlet, which enforces a consistent lifecycle regardless of the target page. This centralization ensures that every request goes through the same phases: state restoration, value binding, validation, action execution, and response rendering.

### Six-Phase Lifecycle

The JSF request lifecycle is a well-defined six-phase sequence:

1. **Restore View** — The component tree for the requested page is reconstructed from saved state or created anew for initial requests.
2. **Apply Request Values** — Submitted form parameters are populated into the corresponding UI components.
3. **Process Validations** — All registered validators run against component values.
4. **Update Model Values** — Validated component values are synced into backing beans (managed beans).
5. **Invoke Application** — Application logic executes, including action methods and navigation rule evaluation.
6. **Render Response** — The component tree is traversed and rendered as HTML (or another output format).

This lifecycle is managed by the `Lifecycle` abstraction, which notifies `PhaseListener` implementations at each phase boundary, enabling cross-cutting concerns like logging, security checks, or custom state management.

### Request/Response Decoupling

The `FacesServlet` insulates the JSF API from direct coupling to the Servlet API. It translates `HttpServletRequest`/`HttpServletResponse` objects into a `FacesContext`, which the rest of the JSF framework operates on. This design allows JSF to remain portable across different container implementations.

```mermaid
flowchart TD
    A["web.xml"] --> B["FacesServlet"]
    C["web-full.xml"] --> B
    B --> D["FacesContext"]
    B --> E["Lifecycle"]
    E --> F["Phase 1: Restore View"]
    E --> G["Phase 2: Apply Request Values"]
    E --> H["Phase 3: Process Validations"]
    E --> I["Phase 4: Update Model Values"]
    E --> J["Phase 5: Invoke Application"]
    E --> K["Phase 6: Render Response"]
```

## Dependencies and Integration

### Internal JSF Dependencies

While `javax.faces` has no indexed source files at its own level, it depends on several sub-packages that are not directly present in this module's index:

| Package | Role |
|---------|------|
| `javax.faces.webapp` | Web-layer front controller (FacesServlet) |
| `javax.faces.context` | FacesContext and context factories |
| `javax.faces.lifecycle` | Lifecycle and PhaseListener abstractions |
| `javax.faces.component` | UI component hierarchy and state |
| `javax.faces.render` | RenderKit and component rendering |
| `javax.faces.el` | Expression language and data binding |

### External Dependencies

- **Servlet Container** — `FacesServlet` runs inside any Java EE-compatible container and depends on the container's request dispatching, session management, and threading model.
- **Deployment Descriptors** — `web.xml` declares the servlet mapping; `web-full.xml` confirms full web profile targeting.

### Cross-module Relationships

No cross-module relationships were detected in the index for this module. The module appears to be a structural namespace with the substantive implementation deferred to sub-packages and the JSF runtime library (e.g., Mojarra, MyFaces).

## Notes for Developers

- **No indexed source at this level**: The `javax.faces` package itself contains no indexed source files. All actual code lives in sub-packages and sub-modules. This package is primarily a namespace grouping.
- **FacesServlet registration is required**: Without a `<servlet>` declaration and `<servlet-mapping>` in `web.xml`, no JSF requests will be processed. This is the most common misconfiguration.
- **URL pattern determines request interception**: The `url-pattern` (e.g., `/faces/*` or `*.jsf`) determines which requests reach the `FacesServlet`. Using `/faces/*` is preferred for clarity.
- **Singleton servlet model**: Only one `FacesServlet` instance is created per web application. The container calls `init()` once at startup and `destroy()` once at shutdown. Per-request state lives in `ThreadLocal`-backed `FacesContext`.
- **Thread-safe by design**: The `FacesServlet` relies on thread-local context storage, not instance variables, for request-scoped data.
- **Stub implementation**: The `FacesServlet.java` source file in this repository is a minimal stub (a class declaration with no body). This indicates the codebase is focused on structural definition rather than runtime implementation. The actual JSF lifecycle implementation would be provided by the JSF runtime library.
- **State saving strategy**: On postbacks, the rendered response includes a hidden form field carrying the JSF component state when server-side state saving is enabled. This affects page size and session storage considerations.