# Javax / Faces / Webapp

## Overview

The `javax.faces.webapp` package is a subpackage of the JavaServer Faces (JSF) reference implementation that provides the **web-facing entry point** into the JSF framework. Its primary responsibility is to expose a servlet (`FacesServlet`) that acts as the central dispatcher for all JSF HTTP requests. This servlet sits in front of the entire JSF lifecycle, intercepting incoming requests, routing them through the faces request processing cycle, and delegating to the appropriate view for rendering. In a standard JSF deployment, this servlet is mapped to a URL pattern (typically `*.jsf`, `/faces/*`, or `/faces/*`) in `web.xml` or `web-full.xml`.

> **Note:** The source file `FacesServlet.java` in this codebase is a minimal stub containing only the class declaration without body or methods. The documentation below reflects the standard contract of `FacesServlet` as defined by the JSF specification, not the local implementation.

## Key Classes and Interfaces

### FacesServlet

**Source:** [`FacesServlet.java`](full-fixture-codebase/src/java/javax/faces/webapp/FacesServlet.java:2)

The `FacesServlet` is the core servlet class for any JSF application. It implements `javax.servlet.Servlet` and serves as the single point of entry for all JSF requests.

**Purpose and role:**

- **Request dispatcher:** When an HTTP request arrives matching the servlet's URL mapping, `FacesServlet` processes it through the complete JSF request processing lifecycle (restore view, apply request values, process validations, update model values, invoke application, render response).
- **Lifecycle coordinator:** It delegates work to the JSF `FacesContext` and the `Lifecycle` object, which orchestrate each phase of the request.
- **Bridge between Servlet API and JSF:** It translates raw HTTP requests/responses into a JSF `FacesContext`, allowing the rest of the JSF framework to operate with its own abstractions.

**Key behaviors (from the JSF spec):**

- **`init()`** — Initializes the servlet, including resolving the `Lifecycle` instance (via `LifecycleFactory`) and performing any framework startup tasks.
- **`service()` / `doGet()` / `doPost()`** — Entry point for processing incoming HTTP requests. Dispatches the request into the appropriate JSF phase based on the request method (GET, POST, or AJAX/partial).
- **`destroy()`** — Cleans up resources, releases the `Lifecycle` reference.

**How it relates to other classes:**

- Uses the **`Lifecycle`** class to coordinate the phases of the JSF request processing lifecycle.
- Creates a **`FacesContext`** for each request, which holds all per-request state (component tree, view root, messages, external context, etc.).
- Interacts with the **`ViewHandler`** for view restoration and rendering.

## How It Works

### Typical Request Flow

Below is the flow of a standard JSF HTTP request through `FacesServlet`:

```mermaid
flowchart LR
    WEB["web.xml / web-full.xml"] --> FACES["FacesServlet
Servlet Entry"]
    FACES --> CONTEXT["Create FacesContext"]
    CONTEXT --> LIFECYCLE["Lookup Lifecycle"]
    LIFECYCLE --> PHASES["Execute Request Phases"]
    PHASES --> RESTORE["Restore View"]
    PHASES --> APPLY["Apply Request Values"]
    PHASES --> VALIDATE["Process Validations"]
    PHASES --> UPDATE["Update Model Values"]
    PHASES --> INVOKE["Invoke Application"]
    PHASES --> RENDER["Render Response"]
    RENDER --> WEBRESPONSE["HTTP Response"]
```

1. **Request arrives** — The servlet container routes the HTTP request to `FacesServlet` based on the URL pattern configured in `web.xml` or `web-full.xml`.
2. **FacesContext creation** — `FacesServlet` creates a `FacesContext` instance that encapsulates all per-request state.
3. **Lifecycle lookup** — It retrieves the `Lifecycle` instance from `LifecycleFactory`, which manages the execution of the JSF phases.
4. **Phase execution** — The lifecycle executes the six phases in sequence:
   - **Restore View** — Loads or creates the component tree for the requested view.
   - **Apply Request Values** — Populates component values from the request.
   - **Process Validations** — Runs validators on submitted values.
   - **Update Model Values** — Copies validated values into the backing beans.
   - **Invoke Application** — Executes application-level actions (navigation, business logic).
   - **Render Response** — Builds the HTML (or other format) response from the component tree.
5. **Response sent** — `FacesServlet` writes the rendered response back to the HTTP client.

### AJAX and Partial Processing

For AJAX requests (via JSF's `<f:ajax>` or client-side libraries like PrimeFaces), `FacesServlet` detects the AJAX indicator in the request and instructs the lifecycle to process only the relevant components and update the corresponding fragments of the response.

## Data Model

This package is primarily structural — it defines the servlet entry point but does not define its own data model. The data that flows through `FacesServlet` is managed by other JSF packages:

- **`FacesContext`** (`javax.faces.context`) — Per-request state carrier.
- **`UIComponent`** tree (`javax.faces.component`) — The component model representing the view.
- **`ViewScope`** and **`SessionScope`** beans — Backing managed beans.

`FacesServlet` itself does not hold state between requests; it is stateless and delegates all state management to the JSF lifecycle and context objects.

## Dependencies and Integration

### Inbound Dependencies (what uses this module)

| Artifact | Relationship |
|---|---|
| `web.xml` | Declares `FacesServlet` mapping — the deployment descriptor configures the servlet and its URL patterns |
| `web-full.xml` | Same as above, using the full JEE web profile descriptor |

### Outbound Dependencies

`FacesServlet` depends on several core JSF packages:

- **`javax.faces.context`** — For `FacesContext` and `ExternalContext`.
- **`javax.faces.lifecycle`** — For `Lifecycle` and `LifecycleFactory`.
- **`javax.faces.webapp`** — May use internal utility classes (e.g., `UIComponentTag`, `Constants`).
- **`javax.servlet.*`** — For the `Servlet` interface and `HttpServletRequest`/`HttpServletResponse`.

## Notes for Developers

### Extension Points

- **Custom Lifecycle** — Developers can register a custom `Lifecycle` implementation to modify phase behavior (e.g., logging, security hooks). This is done via configuration in `faces-config.xml` or programmatically.
- **Filter-based processing** — JSF 2.3+ introduced a `FacesServlet` mapping via `@FacesServletMapping` annotation, providing an alternative to `web.xml` configuration.

### Gotchas

- **URL pattern matters:** The URL pattern used to map `FacesServlet` determines which URLs trigger the JSF lifecycle. Common patterns include `*.jsf`, `/faces/*`, and `*.xhtml`. Choosing the wrong pattern can cause resources (CSS, JS) to accidentally pass through the lifecycle.
- **Static resource handling:** JSF 2.0+ includes a built-in resource handler. Ensure that static resource URLs do not collide with JSF view mappings.
- **The stub class:** The local `FacesServlet.java` is a stub (empty class body). The real implementation lives in the JSF reference implementation library (Mojarra or MyFaces), which is pulled in as a transitive dependency.

### Conventions

- One `FacesServlet` per JSF application.
- The servlet is typically named `FacesServlet` in `web.xml` for convention-based configuration.
- All non-AJAX JSF requests go through a full lifecycle; AJAX requests go through partial processing for performance.