# Javax

## Overview

The `javax` package represents the **Java EE (Jakarta EE) API surface** — a collection of namespaces that define the standard APIs for enterprise Java development. This root-level package is the top-level namespace under which a wide range of Java EE technologies are organized, from web services to persistence to user interfaces.

Rather than containing implementation code itself, `javax` serves as the organizational umbrella for Java EE sub-packages. Each sub-package (such as `javax.faces`, `javax.servlet`, `javax.persistence`, `javax.ws.rs`) defines a distinct technology area within the Java EE specification. This namespace allows developers and application servers to reference a stable, versioned API set that spans web, persistence, messaging, security, and transaction management.

## Sub-module Guide

### javax.faces

The `javax.faces` sub-package is the root of the **JavaServer Faces (JSF)** API — a server-side MVC (Model-View-Controller) framework for building component-based user interfaces in Java web applications. JSF manages the entire request lifecycle, from parsing incoming HTTP requests to rendering HTML responses, providing a structured, phase-driven model that decouples UI components from business logic.

Within the `javax.faces` package, the primary sub-package is `javax.faces.webapp`, which provides the bridge between the JSF lifecycle and the Java Servlet specification. Its key class, `FacesServlet`, acts as the **front-controller** for every JSF application — the single servlet declared in `web.xml` that receives all requests mapped to JSF URL patterns (e.g. `*.faces` or `/faces/*`).

`FacesServlet` translates incoming HTTP requests into the standardized **seven-phase JSF lifecycle**:

1. **Restore View** — Reconstructs the component tree from the previous request state or creates a fresh one.
2. **Apply Request Values** — Populates UI component values from HTTP request parameters.
3. **Process Validations** — Runs converter and validator logic on each component.
4. **Update Model Values** — Syncs validated UI component values into backend JavaBeans / CDI backing beans.
5. **Invoke Application** — Executes action listeners, navigation rules, and business logic.
6. **Render Response** — Builds and writes the HTML (or other format) response back to the client.

Beyond `webapp`, a production JSF deployment includes additional sub-packages: `javax.faces.component` (UI component tree model), `javax.faces.lifecycle` (lifecycle execution engine), and `javax.faces.el` (expression language evaluation).

## Key Patterns and Architecture

### Front-Controller Pattern

`FacesServlet` implements the **front-controller** design pattern — a single servlet entry point that normalizes request handling. Every JSF request funnels through one `FacesServlet` instance, ensuring consistent lifecycle execution regardless of the page being requested.

### Phase-Driven Lifecycle

The core architectural decision of JSF is the **seven-phase request lifecycle**. Each phase is a discrete step that the container walks through sequentially. If any phase throws a `FacesException` or encounters a validation failure, the flow short-circuits and control transfers to the render phase with an error state. This deterministic flow gives framework developers predictable hook points for interception and customization.

### Request-Scoped Context

Per-request state is held in `FacesContext`, stored in a `ThreadLocal` to avoid concurrency issues. This means `FacesServlet` is thread-safe by design — a single instance serves all requests while thread-local state keeps each request isolated.

```mermaid
flowchart LR
    P["javax (root)"] --> F["javax.faces (JSF API)"]
    F --> W["javax.faces.webapp<br/>FacesServlet"]
    F --> L["javax.faces.lifecycle<br/>7-phase lifecycle"]
    F --> C["javax.faces.component<br/>UI component tree"]
    F --> E["javax.faces.el<br/>expression language"]
```

```mermaid
flowchart TD
    A["HTTP Request"] --> B["FacesServlet.service"]
    B --> C["Restore View"]
    C --> D["Apply Request Values"]
    D --> E["Process Validations"]
    E --> F["Update Model Values"]
    F --> G["Invoke Application"]
    G --> H["Render Response"]
    H --> I["HTTP Response"]
```

## Dependencies and Integration

### Internal Dependencies

- **`javax.faces` core packages** — The broader JSF API provides the core abstractions (`FacesContext`, `Lifecycle`, component model, expression language) that `FacesServlet` orchestrates. The `javax.faces.webapp` sub-package acts as the integration layer between the JSF lifecycle and the servlet container.

### External Dependencies

- **`javax.servlet`** — `FacesServlet` implements the `javax.servlet.Servlet` interface and operates entirely within the standard servlet container lifecycle. It depends on the container for thread management, URL mapping, and request/response object creation.

### Configuration Integration

`FacesServlet` is wired into the application through standard servlet deployment descriptors:

- **`web.xml`** — Declares `FacesServlet` and maps it to a URL pattern. This is the most common configuration approach.
- **`web-full.xml`** — An alternative full-profile web descriptor that may enable additional servlet features such as async support or custom filters.

## Notes for Developers

- **Empty class in this fixture.** The source file (`FacesServlet.java`) contains only a class declaration with an empty body. In production JSF implementations, the class extends the reference implementation's internal `FacesServlet` base (from the Mojarra or MyFaces JAR). This fixture represents the minimal interface stub needed for deployment descriptor registration.
- **One servlet per application.** Declare exactly one `FacesServlet` instance per WAR file. JSF does not support multiple dispatcher servlets for the same application.
- **URL mapping is critical.** If the `*.faces` or `/faces/*` mapping is missing or misconfigured in `web.xml`, no JSF pages will render — requests will result in 404 errors.
- **Thread safety is guaranteed by design.** `FacesServlet` is instantiated once by the container and handles all requests through its `service()` method. Per-request state lives in `FacesContext` (a `ThreadLocal`), so there is no shared mutable state between requests.
- **Short-circuit behavior.** If any lifecycle phase fails, control skips remaining phases and jumps to render with an error state. This is intentional — the framework handles error rendering automatically when `FacesException` is thrown.