# Javax / Faces / Webapp

## Overview

The `javax.faces.webapp` package provides the core servlet integration for JavaServer Faces (JSF), the standard Java EE component-based UI framework. At the center of this package is `FacesServlet`, the front controller servlet that receives all JSF-bound HTTP requests and orchestrates the JSF request lifecycle — from restoring the component tree, through processing events and validation, to rendering the response.

## Key Classes and Interfaces

### `FacesServlet`

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

`FacesServlet` is the central servlet for a JSF application. It acts as the **front controller** for all JSF requests.

#### Role in the Request Lifecycle

`FacesServlet` extends the standard `HttpServlet` and is responsible for dispatching each incoming request through the JSF lifecycle phases:

1. **Restore View** — Rebuild the component tree from the saved view state, or create a new one on first visit.
2. **Apply Request Values** — Populate UI component properties from the incoming request parameters.
3. **Process Validations** — Run validators registered on each component and collect conversion/validation errors.
4. **Update Model Values** — Transfer validated data from UI components to the backing Java beans (managed beans).
5. **Invoke Application** — Fire action events, execute business logic, and determine the next navigation outcome.
6. **Render Response** — Build the HTML (or other format) response from the component tree.

If any phase needs to skip ahead (e.g., an error during validation means rendering should be skipped), `FacesServlet` handles phase transitions and early exits gracefully.

#### Implementation Notes

In this codebase, the `FacesServlet` class body is a declaration-only stub. The actual lifecycle implementation lives in the JSF reference implementation runtime (e.g., Mojarra or MyFaces), which provides the concrete `service()` method and phase manager logic. The class exists here as a deployable servlet descriptor that applications register in `web.xml`.

## How It Works

### Request Flow

The typical request flow through `FacesServlet` follows this pattern:

```mermaid
flowchart TD
    A["HTTP Request"] --> B{"URL matches
FacesServlet mapping?"}
    B -->|No| C["Pass through to
other servlets"]
    B -->|Yes| D["JSF Lifecycle Phase 1: Restore View"]
    D --> E{"View already exists?"}
    E -->|No| F["Create new component tree"]
    E -->|Yes| G["Restore from view state"]
    F --> H["Phase 2: Apply Request Values"]
    G --> H
    H --> I["Phase 3: Process Validations"]
    I --> J{"Validation errors?"}
    J -->|Yes| K["Phase 6: Render Response
(skipts ahead)"]
    J -->|No| L["Phase 4: Update Model Values"]
    L --> M["Phase 5: Invoke Application"]
    M --> N["Determine navigation outcome"]
    N --> K
```

### Servlet Registration

`FacesServlet` is typically mapped to a URL pattern in the application's `web.xml` or `web-full.xml`. Common mappings include:

| URL Pattern | Description |
|---|---|
| `*.jsf` | Map only requests ending in `.jsf` |
| `/faces/*` | Map all paths under `/faces/` |
| `/*` | Map all requests (intercepts everything) |

In this codebase, `FacesServlet` is registered in two deployment descriptors:

- [`web.xml`](xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml) — maps the servlet with name `FacesServlet` to class `javax.faces.webapp.FacesServlet`. The application also configures a custom `EncodingFilter` and an `X33AppContextListener`.
- [`web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml) — a full Jakarta EE web app descriptor that registers the same servlet, along with a `SjisFilter` for Shift-JIS encoding support.

### Context Initialization

When the application deploys, the JSF lifecycle is bootstrapped. `FacesServlet` typically depends on a `ServletContextListener` (such as `com.fujitsu.futurity.web.x33.listener.X33AppContextListener` in this project) to initialize the JSF application configuration during servlet container startup.

## Data Model

This module does not define any standalone entity or DTO classes. JSF manages its own internal data model through:

- **UIComponent tree** — the hierarchical component tree that represents the page's UI structure.
- **View state** — a serialized representation of the component tree stored per session (hidden in the page as `_idJsnAll` or similar).
- **Managed beans** — Java beans registered in JSF configuration scopes (`request`, `view`, `session`, `application`).

## Dependencies and Integration

### Inbound Dependencies

| Consumer | Purpose |
|---|---|
| [`web.xml`](xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml) | Registers `FacesServlet` as the servlet-class handler for JSF requests |
| [`web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml) | Full deployment descriptor registering `FacesServlet` |

### Outbound Dependencies

`FacesServlet` integrates with:

- **JSF API** (`javax.faces.*`) — the core JSF framework classes for component tree management, phase listeners, and lifecycle execution.
- **Servlet API** (`javax.servlet.*`, `javax.servlet.http.*`) — standard web container interfaces for HTTP request/response handling.
- **Application-specific listeners and filters** — in this project, encoding filters (`X33JVRequestEncodingSjisFilter`) and context listeners are wired around `FacesServlet` in the servlet filter chain.

### Architecture Diagram

```mermaid
flowchart LR
    A["HTTP Client"] --> B["Web Container"]
    B --> C["EncodingFilter"]
    C --> D["FacesServlet"]
    D --> E["JSF Lifecycle
Phase Manager"]
    E --> F["Restore View"]
    E --> G["Apply Request Values"]
    E --> H["Process Validations"]
    E --> I["Update Model Values"]
    E --> J["Invoke Application"]
    E --> K["Render Response"]
    D --> L["Managed Beans"]
    L --> M["Business Logic"]
```

## Notes for Developers

### Empty Class Body
The `FacesServlet` class in the source code contains only a package declaration and class header with no methods or fields. This is expected — the full servlet implementation is provided by the JSF reference implementation at runtime. Do not be alarmed by the empty body; the behavioral logic comes from the servlet container's deployment of the JSF library on the classpath.

### Servlet Mapping Matters
The URL pattern used to map `FacesServlet` has significant implications:
- `*.jsf` — safe and conventional; only JSF pages are processed through the lifecycle.
- `/*` — intercepts all requests, which can cause issues with static resources (images, CSS, JS) unless a resource handler is configured.
- `/faces/*` — less common in modern JSF applications; the `@FacesApplication` annotation and resource handler reduce the need for this pattern.

### Filter Chain Integration
If you add filters around `FacesServlet`, be aware of the following:
- Filters run **before** `FacesServlet` processes the request, so they can inspect/modify request parameters but must forward the request properly.
- The response from a filter affects the JSF render phase output. Ensure filters do not prematurely commit the response buffer, as this would cause `IllegalStateException` during JSF rendering.
- Encoding filters (like `X33JVRequestEncodingSjisFilter` in this project) should set the character encoding **before** any JSF processing, typically by calling `request.setCharacterEncoding()`.

### Extending FacesServlet
If you need custom lifecycle behavior (e.g., per-request audit logging, custom view restoration), the recommended approach is to extend `FacesServlet` and override specific lifecycle methods such as `initFacesContext()` or `createFacesContext()`. Alternatively, implement a `PhaseListener` to inject behavior at specific lifecycle phases without modifying the servlet itself.