# Javax / Faces

## Overview

The `javax.faces` package is the root of the **JavaServer Faces (JSF)** integration within this codebase. JSF is the standard Java EE component-based UI framework that provides a event-driven model for building web applications with server-side components.

This area of the codebase does not contain a hand-written JSF implementation. Instead, it provides the **servlet wiring** that connects the web container to the JSF runtime (such as Mojarra or MyFaces, supplied by the application server or classpath). The single sub-module under this package — `javax.faces.webapp` — defines the `FacesServlet` front controller, which is the entry point for all JSF-bound HTTP requests.

## Sub-module Guide

### `javax.faces.webapp`

The `webapp` sub-module provides the servlet integration layer. Its primary class, `FacesServlet`, extends `HttpServlet` and is the front controller that receives JSF-bound HTTP requests.

**How it fits**: `FacesServlet` is the bridge between the standard Servlet API and the JSF component lifecycle. When a browser sends a request to a JSF-managed URL, the web container routes it to `FacesServlet` (as configured in `web.xml`), which then delegates to the JSF runtime's lifecycle engine.

The actual lifecycle logic — phase management, component tree restoration, validation, and rendering — lives in the JSF reference implementation (Mojarra/MyFaces), not in the source code here. The `FacesServlet` class in the source tree is a declaration-only stub; it serves as a deployable servlet descriptor that applications register in `web.xml`.

**Relationship between child modules**: Since `webapp` is the only child under `javax.faces`, the entire package's purpose centers on this single front controller servlet. The `webapp` module's responsibility is purely infrastructural — it exposes the JSF lifecycle as a servlet that the container can dispatch requests to. There are no other sub-modules to coordinate with; `FacesServlet` is the sole public API surface that external components interact with.

## Key Patterns and Architecture

### The JSF Request Lifecycle

The defining architectural pattern in this package is the **front controller pattern** implemented by `FacesServlet`. Every JSF-bound request follows a rigid six-phase lifecycle:

1. **Restore View** — Rebuild the component tree from the saved view state, or create a new one on first visit.
2. **Apply Request Values** — Populate UI component properties from the incoming request parameters.
3. **Process Validations** — Run validators registered on each component and collect conversion/validation errors.
4. **Update Model Values** — Transfer validated data from UI components to the backing Java beans.
5. **Invoke Application** — Fire action events, execute business logic, and determine the next navigation outcome.
6. **Render Response** — Build the HTML (or other format) response from the component tree.

If any phase detects an error (e.g., validation fails), `FacesServlet` handles the transition gracefully — for instance, skipping ahead directly to the Render Response phase with error messages displayed rather than proceeding further.

```mermaid
flowchart TD
    A["HTTP Request"] --> B{"URL matches
FacesServlet mapping?"}
    B -->|No| C["Pass through to
other servlets"]
    B -->|Yes| D["Phase 1: Restore View"]
    D --> E{"View exists?"}
    E -->|No| F["Create new
component tree"]
    E -->|Yes| G["Restore from
view state"]
    F --> H["Phase 2: Apply Request Values"]
    G --> H
    H --> I["Phase 3: Process Validations"]
    I --> J{"Validation errors?"}
    J -->|Yes| K["Phase 6: Render Response"]
    J -->|No| L["Phase 4: Update Model Values"]
    L --> M["Phase 5: Invoke Application"]
    M --> N["Determine navigation outcome"]
    N --> K
```

### Filter Chain Architecture

Requests enter `FacesServlet` through a servlet filter chain that sits in front of it. In this codebase, encoding filters such as `X33JVRequestEncodingSjisFilter` are positioned in this chain, ensuring character encoding is set before any JSF processing begins. The filter chain is registered in `web.xml` and `web-full.xml`, which also define the `FacesServlet` mapping itself.

### Component Tree and View State

While the component tree management code is not present in this package, `javax.faces.webapp` is responsible for orchestrating its lifecycle. The view state — a serialized representation of the component tree — is stored per session and referenced in the HTML page (typically as a hidden field such as `_idJsnAll`). `FacesServlet` coordinates the serialization and deserialization of this state across the Restore View and Render Response phases.

```mermaid
flowchart LR
    A["HTTP Client"] --> B["Web Container"]
    B --> C["EncodingFilter"]
    C --> D["FacesServlet"]
    D --> E["JSF Lifecycle Phase Manager"]
    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"]
    D --> L["Managed Beans"]
    L --> M["Business Logic"]
```

## Dependencies and Integration

### Inbound Dependencies

| Consumer | Purpose |
|---|---|
| `web.xml` | Registers `FacesServlet` with the servlet container and defines URL mappings |
| `web-full.xml` | Full Jakarta EE deployment descriptor registering `FacesServlet`, along with supporting filters like `SjisFilter` |

### Outbound Dependencies

`FacesServlet` integrates with:

- **JSF API** (`javax.faces.*`) — the core JSF framework classes for component tree management, phase listeners, and lifecycle execution. The full implementation comes from the JSF reference implementation at runtime.
- **Servlet API** (`javax.servlet.*`, `javax.servlet.http.*`) — standard web container interfaces for HTTP request and response handling.
- **Application-specific listeners and filters** — in this project, encoding filters (`X33JVRequestEncodingSjisFilter`) and context listeners (`X33AppContextListener`) are wired into the servlet filter chain around `FacesServlet`.

### Deployment Configuration

`FacesServlet` is mapped to URL patterns in the application's deployment descriptors. The choice of mapping has significant implications:

| URL Pattern | Implication |
|---|---|
| `*.jsf` | Safe and conventional; only JSF pages are processed through the lifecycle |
| `/faces/*` | All paths under `/faces/` are handled; less common in modern JSF |
| `/*` | Intercepts all requests, which can cause issues with static resources unless a resource handler is configured |

## Notes for Developers

### Empty Class Body is Expected

The `FacesServlet` class in the source code contains only a package declaration and class header with no methods or fields. This is expected — the full servlet implementation is provided by the JSF reference implementation at runtime. Do not be alarmed by the empty body; the behavioral logic comes from the servlet container's deployment of the JSF library on the classpath.

### Servlet Mapping Has Consequences

The URL pattern used to map `FacesServlet` significantly affects behavior. Using `/*` will intercept every request, including static assets, which may cause unexpected errors if no resource handler is configured. When in doubt, prefer `*.jsf` or `/faces/*` to avoid unintentionally processing static content.

### Filter Chain Best Practices

If you add filters around `FacesServlet`, keep these constraints in mind:

- Filters run **before** `FacesServlet` processes the request, so they can inspect or modify request parameters but must forward the request properly.
- Filters must not prematurely commit the response buffer, as this would cause `IllegalStateException` during the JSF render phase.
- Encoding filters should set the character encoding **before** any JSF processing, typically by calling `request.setCharacterEncoding()`.

### Extending FacesServlet

If you need custom lifecycle behavior — such as per-request audit logging or custom view restoration — the recommended approach is to extend `FacesServlet` and override lifecycle methods such as `initFacesContext()` or `createFacesContext()`. Alternatively, implement a `PhaseListener` to inject behavior at specific lifecycle phases without modifying the servlet itself.