# Javax / Faces / Webapp

The `javax.faces.webapp` package provides the web-layer components of the JavaServer Faces (JSF) framework. Its primary responsibility is to expose the JSF lifecycle as a standard `Servlet`, allowing JSF applications to integrate with the Java Servlet specification's request-handling model.

## Overview

This package serves as the entry point for every JSF web request. At its center is the `FacesServlet` class, which implements the `Servlet` interface and acts as the front controller for the JSF framework. When a request arrives, the `FacesServlet` bootstraps the JSF lifecycle — restoring component state, applying request values, processing validations, updating model values, rendering the response, and finally saving state.

The package is a subpackage of `javax.faces` and contains a single indexed class: `FacesServlet`.

## Key Classes and Interfaces

### FacesServlet

The `FacesServlet` is the front controller servlet that handles all JSF requests. It is the component that ties the Java Servlet API to the JSF component lifecycle.

**Purpose and Role**

Every JSF application must register `FacesServlet` in its deployment descriptor (`web.xml`). The servlet is typically mapped to a URL pattern such as `/faces/*` or `*.jsf` or even `/faces/*` to intercept all JSF-related requests. When the container receives an incoming HTTP request that matches the servlet's mapping, it delegates to this class.

**Implementation**

In this codebase, `FacesServlet` is defined as:

```java
public class FacesServlet {}
```

The class declaration exists as a structural placeholder in the codebase. In a full JSF implementation, the `FacesServlet` would implement the standard servlet methods (`init`, `service`, `destroy`) and would internally:

1. Create or look up a `FacesContext` instance bound to the current HTTP request and response.
2. Invoke the JSF lifecycle through a `Lifecycle` manager obtained from the `FactoryFinder`.
3. Phase listeners registered during application startup receive callbacks at each lifecycle phase.
4. Render the response by delegating to the JSF `ViewHandler`.

**Deployment Descriptor Integration**

`FacesServlet` is referenced by two XML configuration files in the codebase:

- `web.xml` — the standard Java EE web application deployment descriptor. This is where the servlet is declared with its `<servlet-name>`, mapped to a `<url-pattern>`, and optionally initialized with `<init-param>` values (e.g., `javax.faces.PROJECT_STAGE`, `javax.faces.STATE_SAVING_METHOD`, `javax.faces.FACELETS_REFRESH_PERIOD`).
- `web-full.xml` — a full profile web descriptor variant. The full profile includes the Java EE web profile features; the presence of `FacesServlet` here confirms the application targets the full web profile.

**Typical web.xml Registration**

A typical registration in `web.xml` looks like:

```xml
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
</servlet-mapping>
```

## How It Works

### Request Lifecycle Flow

When a browser requests a JSF page, the following flow occurs:

1. The servlet container matches the request URL to `FacesServlet`'s `<url-pattern>`.
2. `FacesServlet.service()` is called with the `HttpServletRequest` and `HttpServletResponse`.
3. A `FacesContext` is created, encapsulating the request, response, session, and application scope data.
4. The JSF `Lifecycle` is invoked, which executes six phases in order:
   - **Restore View** — Reconstruct the component tree for the requested page.
   - **Apply Request Values** — Populate component fields with submitted request parameters.
   - **Process Validations** — Run all registered validators on component values.
   - **Update Model Values** — Sync component values into backing beans.
   - **Invoke Application** — Execute application logic (action methods, navigation rules).
   - **Render Response** — Generate HTML (or other format) to send back to the client.
5. The rendered output is written to the `HttpServletResponse` output stream.
6. On postbacks, the response includes a hidden `<form>` field carrying the JSF state (if `server` state-saving is enabled).

### Design Decisions

- **Front Controller Pattern**: `FacesServlet` implements the well-known front controller pattern, providing a single entry point that centralizes request handling and enforces the lifecycle consistently across all JSF pages.
- **Request/Response Decoupling**: The servlet bridges the `HttpServletRequest`/`HttpServletResponse` objects with JSF's `FacesContext`, insulating the JSF API from direct servlet API coupling.
- **Lifecycle as a Service**: The `FacesServlet` delegates lifecycle execution to the `Lifecycle` abstraction, allowing different lifecycle implementations to be swapped at runtime through the JSF factory mechanism.

```mermaid
flowchart TD
    A["web.xml"] --> B["FacesServlet"]
    C["web-full.xml"] --> B
    B --> D["FacesContext"]
    B --> E["Lifecycle"]
    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"]
```

## Data Model

This package does not define its own data model classes. It operates on the `FacesContext` and related API objects defined in the parent `javax.faces` and `javax.faces.context` packages. The `FacesServlet` is a thin adapter layer — its responsibility is routing, not data management.

## Dependencies and Integration

### Deployment Descriptors

The `FacesServlet` is wired into the application through two XML configuration files:

| File | Purpose |
|------|---------|
| `web.xml` | Standard deployment descriptor declaring the servlet and its URL mappings |
| `web-full.xml` | Full web profile descriptor, confirming the application targets the full Java EE web profile |

### Related JSF Packages

While `web.xml` and `web-full.xml` are the only documented dependencies, the `FacesServlet` interacts with:

- `javax.faces.context` — for `FacesContext` creation and management
- `javax.faces.lifecycle` — for `Lifecycle` execution
- `javax.faces.render` — for `RenderKit` selection during response rendering
- `javax.faces.component` — for component tree operations
- `javax.faces.el` — for expression language evaluation and data binding

### Servlet Container

As a `Servlet` implementation, `FacesServlet` runs inside any Java EE-compatible servlet container (Tomcat, Jetty, WildFly, WebLogic, etc.) and relies on the container's request dispatching, session management, and threading model.

## Notes for Developers

- **Registration is required**: Without a `<servlet>` declaration and `<servlet-mapping>` in `web.xml`, no JSF requests will be processed. This is the most common misconfiguration.
- **URL pattern matters**: The `url-pattern` determines which requests the `FacesServlet` intercepts. Using `*.jsf` or `/faces/*` are the two most common patterns. Using `/faces/*` is preferred for clarity.
- **One servlet instance**: JSF follows the singleton servlet pattern — only one `FacesServlet` instance is created per web application. The container calls `init()` once at startup and `destroy()` once at shutdown.
- **Thread safety**: The `FacesServlet` is thread-safe by design. Per-request state lives in the `ThreadLocal`-backed `FacesContext`, not in instance variables.
- **Empty stub in this codebase**: The `FacesServlet.java` source file in this repository is a minimal stub (a class declaration with no body). This indicates the codebase is focused on structural definition rather than implementation. The actual JSF lifecycle implementation would be provided by the JSF runtime library (e.g., Mojarra, MyFaces).