# Javax / Faces / Webapp

## Overview

This package is part of the [JavaServer Faces (JSF)](https://jakarta.ee/specifications/faces/) web layer. It sits between the servlet container and the core JSF framework, exposing the JSF lifecycle as a standard `javax.servlet.Servlet`. In practice, this module provides the entry point through which all HTTP requests are routed into the JSF request-processing pipeline.

The `FacesServlet` class is the sole public type in this package. It is configured in `web.xml` (or `web-full.xml`) via `<servlet>` and `<servlet-mapping>` elements so that it intercepts all JSF-related requests (typically URLs matching `*.jsf` or `/faces/*`).

## Key Classes

### `FacesServlet`

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

`FacesServlet` is the primary JSF servlet. When configured in a web application, it serves as the central dispatcher for all JSF HTTP requests. It bootstraps the JSF runtime (via `ExternalContext` and `FacesContext`), invokes the JSF lifecycle phases (Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, Render Response), and writes the resulting response back to the client.

At this time the class body is empty in the fixture, which indicates it is a framework-provided type that is used via configuration rather than extended. Applications typically do not subclass it; instead they:

- Map `FacesServlet` to URL patterns in `web.xml` / `web-full.xml`.
- Provide a `faces-config.xml` to configure navigation rules, managed beans, converters, validators, and lifecycle phase listeners.
- Optionally register a `ServletListener` (e.g. `javax.servlet.ServletContextListener`) that calls `FacesInitializer.onStartup()` during deployment.

#### Configuration

`FacesServlet` is referenced from two deployment descriptors:

- `web-full.xml`
- `web.xml`

Both declare the servlet and map it to a URL pattern so that matching HTTP requests are dispatched to JSF for processing.

#### Lifecycle Integration

`FacesServlet` is the gateway into the JSF request lifecycle. When a request arrives:

1. The servlet container routes the request to `FacesServlet` based on the URL pattern.
2. `FacesServlet` creates a `FacesContext` for the request and an `ExternalContext` wrapping the `HttpServletRequest` / `HttpServletResponse`.
3. The `Application` (from `javax.faces.application.Application`) retrieves the configured `Lifecycle` implementation.
4. The `Lifecycle` executes the six JSF phases against the `FacesContext`.
5. After the Render Response phase, `FacesContext` is released and the response is committed.

```mermaid
flowchart TD
    A["Client HTTP Request"] --> B["FacesServlet"]
    B --> C["Create FacesContext
and ExternalContext"]
    C --> D["Retrieve Lifecycle"]
    D --> E["Phase 1: Restore View"]
    E --> F["Phase 2: Apply Request Values"]
    F --> G["Phase 3: Process Validations"]
    G --> H["Phase 4: Update Model Values"]
    H --> I["Phase 5: Invoke Application"]
    I --> J["Phase 6: Render Response"]
    J --> K["Commit HTTP Response"]
    K --> L["Client"]
```

## How It Works

### Request Routing

`FacesServlet` is configured as the default handler for a URL pattern. Any incoming request matching that pattern passes through this servlet, which then:

1. Initializes or restores the `FacesContext` for the current request.
2. Determines whether this is a regular request or a Postback by checking the `javax.faces.ViewRoot` state.
3. Delegates to the `Lifecycle` to execute the appropriate phases.
4. Writes the generated HTML (or other response) back to the `HttpServletResponse`.

### Lifecycle Delegation

The servlet does not implement the JSF lifecycle itself — it delegates to a `Lifecycle` object obtained from the `Application` instance. This decouples request handling from phase execution and allows alternative `Lifecycle` implementations to be swapped via `faces-config.xml` configuration.

## Dependencies and Integration

### Inbound Dependencies

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

These descriptors are the glue that connects the servlet to the servlet container. Without them, `FacesServlet` is not discovered or invoked.

### Framework Dependencies

- **servlet-api** — `FacesServlet` extends `HttpServlet` and uses `HttpServletRequest`, `HttpServletResponse`, and related types.
- **jsf-api** — The core `FacesContext`, `ExternalContext`, `Application`, and `Lifecycle` types live in `javax.faces.*` packages.
- **jsf-impl** — The runtime implementations (e.g., `LifecycleImpl`, `ApplicationImpl`) are provided by the JSF implementation on the classpath (e.g., Mojarra, MyFaces).

## Notes for Developers

- **Do not subclass `FacesServlet` directly.** If you need to intercept requests before or after the JSF lifecycle, use a `Filter` placed before or after the servlet in the filter chain. This is the recommended approach for logging, authentication, or response modification.
- **URL pattern matters.** The URL 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 request-scoped.** Each HTTP request gets its own `FacesContext`. Do not store it as an instance field. Access it via `FacesContext.getCurrentInstance()` within the request thread.
- **Initializer hook.** In a full profile (Servlet 3.0+), JSF implementations often provide a `javax.faces.WebApplicationInitializer` that auto-configures `FacesServlet` if no explicit mapping is found. This is why some projects omit the `<servlet>` declaration entirely.