# Javax / Faces / Webapp

## Overview

This package provides the web component layer for JavaServer Faces (JSF) — a Java EE framework for building component-based user interfaces for web applications. The `javax.faces.webapp` package exposes servlet-based entry points that bridge the HTTP request/response cycle with the JSF component lifecycle. The primary entry point, `FacesServlet`, is the front controller servlet that dispatches every JSF-managed request through the standardized JSF request processing lifecycle.

## Key Classes

### FacesServlet

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

`FacesServlet` is the central servlet that bootstraps and drives the JSF request processing lifecycle. Every incoming HTTP request that maps to a JSF URL pattern (typically `*.jsf`, `*.faces`, or `/faces/*`) is handled by this servlet.

**Role in the architecture:** This servlet acts as the front controller. When a request arrives, it creates a `FacesContext` instance representing the current request and passes control to the JSF lifecycle, which proceeds through six phases:

1. **Restore View** — Rebuilds or creates the component tree for the requested page.
2. **Apply Request Values** — Reads submitted values from UI components.
3. **Process Validation** — Validates converted values against configured validators.
4. **Update Model Values** — Copies validated data into application backing beans.
5. **Invoke Application** — Handles application logic (e.g., button actions, navigation).
6. **Render Response** — Renders the component tree to HTML output.

After the lifecycle completes, the `FacesContext` is released and the response is written to the client.

## How It Works

### Typical Request Flow

A request entering the JSF web layer follows this sequence:

```mermaid
flowchart TD
    A["web.xml / web-full.xml"] --> B["FacesServlet"]
    B --> C["Create FacesContext"]
    C --> D["JSF Lifecycle"]
    D --> E["Restore View"]
    D --> F["Apply Request Values"]
    D --> G["Process Validation"]
    D --> H["Update Model Values"]
    D --> I["Invoke Application"]
    D --> J["Render Response"]
    J --> K["HTTP Response to Client"]
```

1. The deployment descriptor (`web.xml` or `web-full.xml`) maps URL patterns to `FacesServlet`, declaring it as the target servlet class.
2. On each matching request, `FacesServlet` constructs a `FacesContext` containing request-specific state (view, parameters, locale, messages).
3. The context is passed through the lifecycle phases, where JSF UI components, converters, validators, and action listeners participate.
4. The final render phase writes HTML (or another configured response format) back to the HTTP response.

### Configuration Entry Point

The servlet is registered in the web deployment descriptor. In this codebase, it appears in [`web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml):

```xml
<servlet>
  <servlet-name>FacesServlet</servlet-name>
  <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>
```

A corresponding `<servlet-mapping>` (not shown in this file) would typically map the servlet to a URL pattern such as `*.jsf` or `*.faces`.

## Data Model

`FacesServlet` itself is stateless from the servlet container's perspective — it does not maintain persistent state between requests. Request-scoped state flows through the `FacesContext` object created per-request. Key context data includes:

- **View** — The component tree representing the current page.
- **External Context** — Wraps the `HttpServletRequest` and `HttpServletResponse`.
- **Messages** — FacesMessage objects for validation and application feedback.
- **View Root** — The `UIViewRoot` component representing the page's top-level UI container.

## Dependencies and Integration

- **JSF Implementation:** `FacesServlet` delegates to the runtime JSF implementation (e.g., Mojarra, MyFaces) to execute the lifecycle phases. The servlet class itself is part of the Java EE specification (`javax.faces` API), while the actual lifecycle execution logic lives in the implementation.
- **Web Container:** This package depends on the standard Servlet API (`javax.servlet`, `javax.servlet.http`) for HTTP handling.
- **Deployment Descriptors:** Configuration in `web.xml` or `web-full.xml` (as seen in this codebase) controls servlet initialization parameters and URL mappings.

## Notes for Developers

- **No source body available:** The indexed `FacesServlet.java` file contains only the class declaration without method bodies. The actual lifecycle logic, init parameters, and lifecycle hooks are inherited from the JSF reference implementation and are not present in this source fixture. When working with the full JSF library, key methods to look for include `service()`, `init()`, and lifecycle phase delegates.
- **URL mapping matters:** The behavior of `FacesServlet` is heavily determined by how it is mapped in the deployment descriptor. Common patterns include `*.jsf`, `*.faces`, or prefix mappings like `/faces/*`.
- **Filter chain:** As a standard servlet, `FacesServlet` participates in the Servlet Filter chain. Pre-filters (e.g., encoding filters, security filters) can modify the request before JSF processing begins.