# Javax / Faces

## Overview

The `javax.faces` package is the root package of the JavaServer Faces (JSF) reference implementation within this codebase. JSF is the component-based web framework standardized under Java EE (Jakarta EE), and this package serves as the foundational entry point for the entire JSF runtime.

The root `javax.faces` package itself contains no indexed source files in the current codebase — it functions as a namespace grouping that is inherited by its child subpackages. The primary subpackage in scope is `javax.faces.webapp`, which exposes the JSF lifecycle through the servlet API. A fully featured JSF application would also include additional subpackages such as `javax.faces.component`, `javax.faces.context`, `javax.faces.lifecycle`, and `javax.faces.application`, but these appear in other areas of the larger JSF reference implementation rather than in this module's scope.

This package represents the technical capability of building server-rendered, component-driven web applications within the Java EE ecosystem.

## Sub-module Guide

### javax.faces.webapp

The `webapp` subpackage is the sole child module of `javax.faces`. It bridges the JSF component lifecycle with the standard Servlet API, making JSF applications deployable as WAR files in any Java EE web container (Tomcat, Jetty, GlassFish, etc.).

The key artifact is `FacesServlet`, which acts as the central request controller for all JSF requests. When configured with a URL pattern (commonly `*.faces`, `*.jsf`, or `/faces/*`), it intercepts incoming HTTP requests and routes them through the JSF lifecycle.

#### How the sub-modules relate

Although `javax.faces` itself has no source files, it serves as the parent namespace under which `javax.faces.webapp` is defined. The `webapp` subpackage is the only module in scope here, so the relationship is straightforward:

```mermaid
flowchart TD
    A["javax.faces
Root JSF Package
(namespace group)"] --> B["javax.faces.webapp
Web Integration"]
    B --> C["FacesServlet
Request Controller
(stub)"]
    C --> D["web-full.xml
Servlet Registration"]
```

In a complete JSF implementation, `FacesServlet` delegates its work to infrastructure provided by sibling packages — `javax.faces.lifecycle` (the six-phase request lifecycle), `javax.faces.context` (request/view/response contexts), and `javax.faces.application` (application-scoped resources and factories). Within this codebase, those dependencies are documented as expected outbound relationships rather than as local sub-modules.

## Key Patterns and Architecture

### Servlet-as-Facade Pattern

`FacesServlet` follows the servlet-as-facade pattern: it is the single entry point that sits between the HTTP transport layer (Servlet API) and the JSF application layer (component tree, lifecycle, rendering). This decouples the transport mechanism from the JSF semantics, allowing the same JSF components to work across different HTTP methods and deployment scenarios.

### Six-Phase Lifecycle Model

The JSF request lifecycle is the central architectural concept that `FacesServlet` orchestrates. Every JSF request passes through a fixed sequence of phases:

1. **Restore View** — Reconstructs the component tree from the view state (or creates a new one for first-time visits).
2. **Apply Request Values** — Populates component local values from incoming request parameters.
3. **Process Validations** — Runs converter and validator logic on each component.
4. **Update Model Values** — Transfers validated values from components to backing beans.
5. **Invoke Application** — Executes the application action associated with the request (e.g., button click handlers).
6. **Render Response** — Builds the HTML (or other format) response from the component tree.

```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"]
```

This phase-based architecture ensures that input validation, model updates, and business logic execution all happen in a well-defined, predictable order — a significant advantage over raw servlet-based approaches where developers must manually coordinate these steps.

### Stub Implementation

A critical detail: in this codebase, `FacesServlet` is a **stub**. The class body is declared but empty — no methods, fields, or constructor logic. This is not a production implementation. If you are building a functional JSF application, you should rely on the reference implementation (Mojarra from Oracle/GlassFish, or MyFaces from Apache) which provides a fully implemented `FacesServlet`. The stub here likely exists for schema validation, IDE support, or as a placeholder in a larger project skeleton.

## 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

The current stub has no outbound package dependencies. A production `FacesServlet` implementation depends on:

| Package | Type | Role |
|---------|------|------|
| `javax.servlet.*` | Servlet API | Core servlet interfaces (`Servlet`, `ServletRequest`, `ServletResponse`) |
| `javax.faces.lifecycle.*` | JSF Lifecycle | `Lifecycle`, `LifecycleFactory` — orchestrates the six-phase request flow |
| `javax.faces.context.*` | JSF Context | `FacesContext`, `ResponseWriter` — request-scoped state holder |
| `javax.faces.application.*` | JSF Application | `Application`, `FactoryFinder` — application-scoped configuration |

### Integration with the wider system

`FacesServlet` integrates with the rest of the application through:

- **`web.xml` / `web-full.xml`** — The servlet mapping controls which URLs are handled by JSF.
- **Backing beans** — CDI or JSF-managed beans that receive form data and host business logic.
- **Facelets (.xhtml) views** — The view templates that define the component tree structure.
- **JSF lifecycle artifacts** — Converters, validators, and listeners registered via annotation or XML.

## Notes for Developers

- **This is a stub.** The `FacesServlet` class body is empty. The class declaration exists but contains no implementation. Do not attempt to build functionality here; instead, use the reference implementation's production `FacesServlet`.
- **Servlet registration is configuration-driven.** The servlet is registered via `web.xml` / `web-full.xml`. Verify the `<servlet-class>` and `<url-pattern>` entries 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. Do not store mutable state in instance fields.
- **GET vs POST handling differs.** `POST` requests trigger the full lifecycle (all six phases). `GET` requests typically go through a truncated path. This affects how your components and views behave depending on the request method.
- **Extension point.** If you need custom pre- or post-processing of JSF requests, use a `Filter` placed before `FacesServlet` in the servlet filter chain rather than subclassing the servlet itself.
- **Exception handling.** Production `FacesServlet` implementations handle `ViewExpiredException` and other JSF-specific exceptions by dispatching to an error view. Ensure your error pages are properly configured.