# Javax / Faces

## Overview

The `javax.faces` package sits at the top of the JavaServer Faces (JSF) reference implementation hierarchy. It represents the core entry point into a component-based, event-driven web framework for building Java web applications. JSF follows the **Page Controller** pattern, centering around a request processing lifecycle that maps HTTP requests to UI component trees, processes form submissions, and renders responses.

At the package level, `javax.faces` does not index any source files or classes directly — it exists as a parent namespace that organizes a set of subpackages, each responsible for a distinct layer of the JSF architecture (servlet dispatch, lifecycle execution, component model, context management, etc.). The most prominently documented sub-package is `javax.faces.webapp`, which provides the servlet-based entry point.

This package hierarchy appears to be a structural/namespace grouping within a larger JSF reference implementation (such as Mojarra). The local codebase contains only stub or placeholder content, suggesting this documentation area is meant to describe the standard JSF specification rather than custom local implementation.

## Sub-module Guide

### `javax.faces.webapp` — Servlet Entry Point

The `webapp` sub-package is the **bridge between the Java Servlet API and the JSF framework**. It exposes `FacesServlet`, which acts as the central dispatcher for all JSF HTTP requests.

**What it does:**

- Intercepts incoming HTTP requests based on URL patterns configured in `web.xml` (e.g., `*.jsf`, `/faces/*`).
- Creates a per-request `FacesContext` that carries all state through the processing pipeline.
- Delegates to the JSF `Lifecycle` object, which executes the six-phase request processing lifecycle.
- Handles both standard full-page requests and AJAX/partial requests.

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

`FacesServlet` is the gateway — everything in JSF flows through it. It does not implement the lifecycle itself but coordinates with classes from `javax.faces.lifecycle` (for phase execution) and `javax.faces.context` (for per-request state). This means the webapp package is **thin and delegating** by design; it is responsible for HTTP protocol concerns while the heavy lifting (component tree management, validation, model binding, rendering) lives in other sub-packages.

## Key Patterns and Architecture

### The Request Processing Lifecycle

The dominant architectural pattern in `javax.faces` is the **template method pattern** realized through the JSF request processing lifecycle. Each incoming request progresses through six ordered phases:

1. **Restore View** — Loads the existing component tree or creates a new one.
2. **Apply Request Values** — Populates UI component values from HTTP request parameters.
3. **Process Validations** — Runs registered validators against submitted values.
4. **Update Model Values** — Copies validated data into backing beans (managed beans/CDI beans).
5. **Invoke Application** — Executes action listeners, navigation rules, and business logic.
6. **Render Response** — Builds the HTML (or other format) response from the component tree.

This lifecycle ensures a consistent, structured processing model. `FacesServlet` is responsible for invoking the lifecycle; the individual phases are handled by collaborators in other sub-packages.

### Servlet-to-Faces Context Bridge

`FacesServlet` implements a **bridge pattern** between two incompatible APIs: the raw `HttpServletRequest`/`HttpServletResponse` from the Servlet API, and the rich `FacesContext`/`ExternalContext` abstractions used by the rest of JSF. This separation allows the framework to remain agnostic of the underlying HTTP transport while providing a unified programming model for developers.

```mermaid
flowchart LR
    REQ["HTTP Request"] --> FACES["FacesServlet"]
    FACES --> CTX["FacesContext
Per-request state"]
    CTX --> LIFECYCLE["Lifecycle
Phase coordinator"]
    LIFECYCLE --> RVIEW["Restore View"]
    LIFECYCLE --> ARVAL["Apply Request Values"]
    LIFECYCLE --> PVALIDATE["Process Validations"]
    LIFECYCLE --> UMODEL["Update Model Values"]
    LIFECYCLE --> INVOKE["Invoke Application"]
    LIFECYCLE --> RENDER["Render Response"]
    RENDER --> RESP["HTTP Response"]
```

## Dependencies and Integration

### Outbound Dependencies

The `javax.faces` hierarchy depends on a set of sibling sub-packages that form the core JSF runtime:

| Dependency | Purpose |
|---|---|
| `javax.faces.context` | Provides `FacesContext` and `ExternalContext` — the per-request state carrier |
| `javax.faces.lifecycle` | Provides `Lifecycle` and `LifecycleFactory` — the phase execution engine |
| `javax.faces.component` | Provides the `UIComponent` tree — the component model for views |
| `javax.servlet.*` | Provides the `Servlet` interface and HTTP request/response types |

### Inbound Dependencies

| Artifact | Relationship |
|---|---|
| `web.xml` / `web-full.xml` | Declares and maps `FacesServlet` to URL patterns |

The `javax.faces` package has no indexed source files of its own, which means all functionality is distributed across its sub-packages. It functions as a **namespace root** rather than a package with its own implementations.

## Notes for Developers

### Stub Implementations

The local codebase contains stub classes (e.g., `FacesServlet` with an empty class body). The real JSF implementation is expected to come from a transitive dependency such as Mojarra (the Oracle reference implementation) or MyFaces (the Apache implementation). Documentation in this area describes the **standard JSF specification contract**, not local code.

### Configuration Conventions

- A single `FacesServlet` is typical per JSF application.
- URL pattern selection matters — patterns like `*.jsf` or `/faces/*` determine which requests trigger the lifecycle. Static resources (CSS, JS, images) should not match these patterns, or JSF 2.0+ resource handling must be configured to exclude them.

### Extension Points

- **Custom `Lifecycle`**: Developers can register custom lifecycle implementations to inject behavior (logging, security checks, performance monitoring) around the standard phases.
- **`@FacesServletMapping`**: JSF 2.3+ supports annotation-based servlet mapping as an alternative to `web.xml` configuration.
- **Phase listeners**: Implement `PhaseListener` to intercept specific lifecycle phases.

### AJAX Handling

AJAX requests (via `<f:ajax>` or third-party libraries) are routed through the same `FacesServlet` but trigger partial processing — only the relevant components and view fragments are re-rendered, rather than the entire page.