# Javax

## Overview

The `javax` package is the root namespace for Java EE (now Jakarta EE) API classes in this codebase. It represents the **server-side, web-tier capabilities** that a Java application server provides out of the box — servlets, JavaServer Faces (JSF), and related web technologies.

This area of the codebase is the foundation for building **server-driven web applications** using component-based UI patterns. At the top level it encompasses:

- **`javax.faces`** — The JavaServer Faces framework, a component-based UI framework for building server-driven web applications with a well-defined request-processing lifecycle.

The `javax` namespace as a whole represents the Java EE web API contract: a set of interfaces and abstract classes that define *what* a web platform can do, while the actual implementations are provided by application server runtimes (WildFly, Tomcat, Jetty, WebLogic, etc.) and JSF provider libraries (Mojarra, MyFaces).

> **Note:** No source files are currently indexed under the `javax` package root or most of its sub-packages. The `javax.faces` sub-package is the primary documented entry point, and even there the source classes are typically spec-api stubs — the production implementations live in the application server or JSF provider JAR at runtime.

## Sub-module Guide

### `javax.faces` — JavaServer Faces

The `javax.faces` package provides the foundation for **JavaServer Faces (JSF)**, the component-based UI framework defined by [JSR 372 (JavaServer Faces 2.3)](https://jakarta.ee/specifications/faces/). It is the only child module currently documented for the `javax` package.

Within `javax.faces`, the most significant sub-package is **`webapp`**, which contains the `FacesServlet` class — the front-controller servlet that bridges HTTP requests from the servlet container into the JSF framework. This is the entry point that makes JSF a web framework rather than just an API specification.

**How the pieces fit together:**

`javax.faces` is organized as a layered architecture:

- **Core API (`javax.faces`)** — Base classes and interfaces that define the JSF programming model (`FacesContext`, `Lifecycle`, `UIViewRoot`, `FacesException`). These are the abstractions every JSF developer interacts with.
- **Web integration (`javax.faces.webapp`)** — The `FacesServlet` and related utilities that expose the JSF lifecycle as a standard servlet, making JSF deployable in any servlet-compliant container.
- **UI component tier (`javax.faces.component`, `javax.faces.render`)** — Component classes, renderer factories, and output generators (not yet indexed). This tier is where the visual component tree is defined and rendered.
- **State management (`javax.faces.view`, `javax.faces.application`)** — View state, navigation handling, and resource resolution (not yet indexed). This tier manages the persistence of component state across requests and resolves navigation outcomes.

The relationship between these layers is **unidirectional**: the web layer delegates to the core API, which coordinates with the component tier and state management. A request flows top-to-bottom through these layers, and the response flows back up.

## Key Patterns and Architecture

### Front-Controller Pattern

`FacesServlet` implements the classic **Front Controller** pattern. It is the single entry point for all JSF requests, centralizing the request-to-lifecycle dispatch logic. This keeps request handling consistent and allows the JSF framework to manage state, validation, and rendering uniformly across every request.

### Six-Phase Request Lifecycle

At the heart of JSF is a request-processing lifecycle that executes exactly six phases in order:

1. **Restore View** — Reconstruct the component tree from the previous request's state.
2. **Apply Request Values** — Populate component local values from incoming HTTP request parameters.
3. **Process Validations** — Run validators registered on each component and collect conversion errors.
4. **Update Model** — Transfer validated component values into backing bean properties.
5. **Invoke Application** — Execute action listeners, command handlers, and navigation logic.
6. **Render Response** — Build the HTML (or other format) output by rendering each component via its renderer.

This lifecycle is invoked by `FacesServlet` for every request it dispatches. The same request may re-enter the lifecycle multiple times (e.g., if validation fails during phase 3, the framework jumps to phase 6 to re-render the form with error messages).

### Per-Request Context

Each request receives its own `FacesContext` instance, stored in a `ThreadLocal`. This context is the single source of truth for the current request — it holds the component tree, application configuration, external context (raw `HttpServletRequest`/`HttpServletResponse`), and flash scope. `FacesServlet` itself is stateless (no instance fields), ensuring thread safety without synchronization.

### Request Flow

The following diagram shows how a typical JSF request flows through the system, from the browser to the managed bean and back:

```mermaid
flowchart LR
    DEV["Developer
Writes @ViewScoped bean"] --> APP["JSF Application
javax.faces"]
    APP --> WEB["Web Layer
javax.faces.webapp"]
    APP --> CORE["Core API
javax.faces"]
    WEB --> FS["FacesServlet
Front Controller"]
    CORE --> FC["FacesContext
Per-Request State"]
    CORE --> LC["Lifecycle
6-Phase Processing"]
    FS --> LC
    LC --> FC
    LC --> MB["Managed Bean
Backed Properties"]
    WEB --> CLIENT["HTTP Client
Browser"]
    CLIENT --> WEB
```

### Stub vs. Production

In this repository, `FacesServlet` is defined as an empty class skeleton. The real implementation lives in the JSF provider library (Mojarra or MyFaces) at runtime. This means:

- The source-level code is a placeholder for build-time or packaging purposes.
- The documented behavior comes from the JSF specification and standard usage patterns.
- Developers should not expect implementation details here — production logic is in the provider JAR.

## Dependencies and Integration

### Internal Dependencies

- **`javax.faces` core API** — `FacesServlet` depends on core classes like `FacesContext`, `Lifecycle`, and `Application` (not yet indexed under `javax.faces` itself).
- **`javax.servlet` API** — `FacesServlet` extends the standard servlet API in a full implementation, inheriting the servlet lifecycle (`init`, `service`, `destroy`).

### External Dependencies

- **Servlet container** — JSF runs inside a servlet container (Tomcat, Jetty, WildFly, etc.). The container manages the servlet lifecycle and routes HTTP requests based on URL patterns configured in `web.xml`.
- **JSF provider library** — At runtime, the actual `FacesServlet` implementation comes from the JSF provider (Mojarra or MyFaces), not the spec API JAR. The provider JAR is typically included as a dependency in the web application.

### Configuration

`FacesServlet` is configured via `web.xml` (or `web-full.xml`):

```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>*.jsf</url-pattern>
</servlet-mapping>
```

Common URL patterns include `*.jsf`, `*.faces`, `/faces/*`, or combinations thereof for flexibility.

## Notes for Developers

- **One servlet per application.** JSF requires exactly one `FacesServlet` instance per web application. Multiple URL pattern mappings to the same servlet are common and fully supported.
- **Thread-safe by design.** `FacesServlet` is stateless — no instance fields hold per-request data. All request state lives in `FacesContext`, backed by `ThreadLocal`.
- **URL pattern dictates behavior.** The URL pattern mapped to `FacesServlet` determines which requests enter the JSF lifecycle and which pass through directly to other servlets (e.g., static resources, REST endpoints).
- **Stub class in this repo.** The `FacesServlet` source is an empty class. Production behavior is provided by the JSF runtime library at deploy time.
- **No source files indexed.** The `javax.faces` package has no indexed source files in this repository. This is expected — `javax.faces` is the API layer; the implementation lives in the provider library.
- **Future scope.** As more sub-packages under `javax.faces` (component, render, view, application) are indexed, this overview should be expanded to cover those layers and their interactions with the core API and web layer.