# Javax / Faces / Webapp

## Overview

The `javax.faces.webapp` package is a subpackage of the JavaServer Faces (JSF) reference implementation. It is responsible for exposing the JSF lifecycle as a standard Java EE web component — specifically, the `FacesServlet`, which acts as the Faces request controller (the central servlet that receives all incoming JSF HTTP requests, initiates the JSF lifecycle, and dispatches to the appropriate view).

The module also appears to be referenced by the web application descriptor `web-full.xml`, which registers `FacesServlet` as a servlet mapping in the application's web configuration.

## Key Classes and Interfaces

### FacesServlet

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

- **Type:** class
- **Visibility:** public
- **Referenced by:** 1 XML config (`web-full.xml`)

`FacesServlet` is the core Faces request controller. In a fully implemented JSF application, this servlet:

1. Intercepts all incoming HTTP requests matching its servlet mapping (commonly `*.faces`, `*.jsf`, or `/faces/*`).
2. Decodes the request parameters and restores the JSF component tree from the view state.
3. Executes the six-phase JSF lifecycle: Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, and Render Response.
4. Sends the rendered HTML response back to the client.

In the current codebase, this is a **stub** — the class body is empty and contains no methods, fields, or constructor logic. A production implementation of `FacesServlet` would implement `javax.servlet.Servlet` and extend (or delegate to) the JSF lifecycle infrastructure provided by `javax.faces` (typically `Lifecycle` and `Application` implementations from the reference implementation, such as those in `com.sun.faces` or `org.glassfish`).

#### Key Method: `service(ServletRequest, ServletResponse)`

Not yet implemented in this stub. In a standard JSF RI, this method:

- Checks if the request method is `GET` or `POST`.
- Determines whether to call `handleBeginRequest` for `GET` or `handleBeginRequest` / `handleEndRequest` for `POST` (POST requests are more fully processed because they carry form data and validation).
- Invokes the JSF `Lifecycle` to process the request through all six phases.
- Handles `ViewExpiredException` and other JSF-specific exceptions by dispatching to an error view.

## How It Works

The FacesServlet operates as the entry point for all JSF requests in a Java EE web application. A typical request flow looks like this:

```mermaid
flowchart TD
    A["HTTP Request
(GET or POST)"] --> B["FacesServlet.service()"]
    B --> C{"Request method?"}
    C -->|POST| D["handleBeginRequest
handleEndRequest"]
    C -->|GET| E["handleBeginRequest
only"]
    D --> F["Lifecycle.execute()"]
    E --> F
    F --> G["JSF Lifecycle Phases"]
    G --> H["Restore View"]
    H --> I["Apply Request Values"]
    I --> J["Process Validations"]
    J --> K["Update Model Values"]
    K --> L["Invoke Application"]
    L --> M["Render Response"]
    M --> N["HTML Response to Client"]
```

In the current stub, however, there is no active flow — `FacesServlet` is declared but does not contain any implementation.

## Data Model

This module does not define any data model classes, DTOs, or entity structures. `FacesServlet` is a pure web controller and delegates all state management to the broader JSF runtime (`UIViewRoot`, `UIViewRoot.State`, etc.).

## Dependencies and Integration

### Inbound Dependencies

| Dependent | Type | Description |
|-----------|------|-------------|
| `web-full.xml` | XML Config | Registers `FacesServlet` as a servlet in the web application descriptor, defining its servlet name, class, init parameters, and URL mapping. |

### Outbound Dependencies

No outbound package dependencies are captured for this stub module. In a fully implemented JSF application, `FacesServlet` would depend on:

- `javax.servlet.*` — the Servlet API (`Servlet`, `ServletRequest`, `ServletResponse`, etc.)
- `javax.faces.context.*` — JSF lifecycle and lifecycle-related interfaces
- `javax.faces.application.*` — `Application` and `FactoryFinder`
- `javax.faces.lifecycle.*` — `Lifecycle`, `LifecycleFactory`

## Notes for Developers

- **This is a stub.** The `FacesServlet` class body is empty. If you are building a functional JSF application, you should not implement this class from scratch — the reference implementation (Mojarra or MyFaces) provides a complete production-ready `FacesServlet`.
- **Servlet registration is configuration-driven.** The servlet is registered via `web.xml` / `web-full.xml`. Ensure the `<servlet-class>` and `<url-pattern>` entries are correct when wiring this into your application.
- **One instance per application.** Per the Servlet specification, `FacesServlet` is instantiated once per web application and shared across all requests. Any mutable state should be avoided.
- **Extension point.** If you need custom pre- or post-processing of JSF requests, consider using a `Filter` in front of `FacesServlet` rather than subclassing the servlet itself.