# Javax / Faces / Webapp

## Overview

The `javax.faces.webapp` package contains the web-layer entry point for JavaServer Faces (JSF) applications: the `FacesServlet`. This servlet acts as the central dispatcher for all JSF requests, bridging standard Servlet containers with the JSF request lifecycle. In this codebase it is registered as a named servlet in the `web-full.xml` deployment descriptor, making it the gateway through which all `.xhtml` or `.jsf` requests are processed.

## Key Classes and Interfaces

### FacesServlet

`[FacesServlet](full-fixture-codebase/src/java/javax/faces/webapp/FacesServlet.java:2)` — class | referenced by 1 XML configs

The `FacesServlet` class is defined in this package and serves as the primary servlet for the JSF framework. In the current source file it appears as an empty class stub — a placeholder declaration without implemented methods or fields.

```java
package javax.faces.webapp;
public class FacesServlet {}
```

**Design role.** Despite its current stub state, `FacesServlet` is the cornerstone of the JSF servlet integration layer. In a fully-implemented JSF runtime (such as Mojarra or MyFaces), this class extends `javax.servlet.http.HttpServlet` and implements the full request lifecycle:

- **`init()`** — initializes the JSF `Lifecycle` instance, typically loaded via a `LifecycleFactory` from `javax.faces.lifecycle`.
- **`service()`** (or overridden `doGet`/`doPost`) — receives every incoming HTTP request, delegates to the JSF `Lifecycle`, which then fires events through the phases (Restore View, Apply Request Values, Process Validations, Update Model, Invoke Application, Render Response).
- **`destroy()`** — cleans up resources associated with the lifecycle.

This appears to be a stub in the fixture codebase, likely generated as part of a test fixture or minimal build configuration rather than a production implementation.

## How It Works

### Request Flow (conceptual)

When a JSF-aware Servlet container receives a request matching the URL pattern mapped to `FacesServlet`, the following flow occurs:

1. The container routes the request to `FacesServlet` (as configured in the deployment descriptor).
2. `FacesServlet.service()` dispatches to the JSF `Lifecycle` instance.
3. The lifecycle iterates through the six standard JSF phases, processing the request and rendering the response.
4. The rendered view (typically XHTML) is written to the HTTP response.

### Deployment Configuration

In this codebase, `FacesServlet` is wired via `web-full.xml`:

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

This declaration is present in `[web-full.xml](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml)` alongside a separate encoding filter (`SjisFilter`), indicating the application handles Japanese Shift-JIS character encoding separately from the JSF request processing pipeline.

## Dependencies and Integration

### Inbound Dependencies

| Source | Relationship |
|--------|-------------|
| `web-full.xml` | Declares `FacesServlet` as a servlet, mapping the `javax.faces.webapp.FacesServlet` class to the web application's request routing. |

### Framework Integration

`FacesServlet` integrates with the broader JSF 2.x API:

- It depends on the Servlet API (`javax.servlet`, `javax.servlet.http`) for its HTTP handling base.
- It delegates to the JSF core API (`javax.faces.*`) for request lifecycle, view handling, and component tree management.
- It sits alongside other web infrastructure in the same `web-app` (e.g., character encoding filters) that operate before or after the JSF pipeline.

## Data Model

This module does not define any entity, DTO, or model classes. `FacesServlet` is a pure infrastructure component — its "data" is the HTTP request/response pair, which it transforms by driving the JSF lifecycle.

## Notes for Developers

- **Stub class**: The current `FacesServlet.java` is an empty class declaration. In production JSF, this class is provided by the JSF implementation library (e.g., Apache MyFaces or Eclipse Mojarra). If you are adding new servlet or filter logic in this package, ensure you are not re-implementing JSF framework code — extend or filter around it instead.
- **URL mapping**: The `web-full.xml` registers the servlet by name but does not show a `<servlet-mapping>` element. In a complete deployment, a URL pattern (typically `*.xhtml` or `/faces/*`) would be mapped to the `FacesServlet` servlet name to route requests.
- **Filter ordering**: The `SjisFilter` is declared before `FacesServlet` in the descriptor. Servlet filter execution order follows declaration order, so the encoding filter runs before JSF processes the request — this is intentional, ensuring request parameters are decoded correctly before JSF binds them.
- **No child modules**: This subpackage currently contains only `FacesServlet`. No additional classes, interfaces, or nested modules exist under `javax.faces.webapp`.