# Javax

## Overview

The `javax` package in this codebase anchors the Java EE web layer, with its most substantive sub-module being `javax.faces` — the root namespace for JavaServer Faces (JSF), the component-based MVC framework for building web UIs in Java. JSF provides a request-driven, stateful programming model where UI components are assembled into trees, bound to managed beans, and rendered as HTML through a six-phase lifecycle.

Within this repository, `javax.faces` exists primarily as a structural and API-level reference rather than a full implementation. Source files and classes have not been indexed, which indicates the actual JSF runtime (such as Mojarra or MyFaces) is expected from external dependency JARs on the classpath. What is present in the project — the `FacesServlet` stub and the web.xml mapping in `web-full.xml` — establishes the contract: this application is JSF-capable, and the servlet entry point is wired up to delegate request processing to the JSF lifecycle.

The `javax` area is therefore best understood as a **dependency-driven module**. Its behavior comes from libraries pulled in at build/runtime, and the codebase here documents where and how those libraries are integrated.

## Sub-module Guide

### javax.faces — The JSF API Surface

The only indexed child under `javax` is `javax.faces`. This sub-module encompasses the entire JSF API contract: the components, lifecycle, context objects, and web integration points that together form the MVC framework.

Within `javax.faces`, the only further child module present in this codebase is `javax.faces.webapp`, which is the web-facing bridge between the servlet container and the JSF lifecycle. All other JSF subpackages (`javax.faces.component`, `javax.faces.render`, `javax.faces.event`, etc.) are expected from the runtime library and are not present in this index.

**How they relate:** The `javax.faces` parent defines the contracts (Application, Lifecycle, FacesContext), while `javax.faces.webapp` provides the concrete servlet (`FacesServlet`) that puts those contracts into action when an HTTP request arrives. Think of the parent as the specification and the webapp subpackage as the bridge that translates HTTP into the JSF world.

## How the Pieces Fit Together

```mermaid
flowchart TD
    WEB["web-full.xml<br/>deployment descriptor"] --> SERV["FacesServlet<br/>javax.faces.webapp"]
    SERV -->|Declared as servlet| CONTAINER["Servlet Container<br/>e.g. Tomcat, GlassFish"]
    CONTAINER -->|HTTP Request| SERV
    SERV -->|Delegates| LIFECYCLE["JSF Lifecycle<br/>(javax.faces.lifecycle)"]
    LIFECYCLE --> PHASE1["RestoreView"]
    LIFECYCLE --> PHASE2["ApplyRequestValues"]
    LIFECYCLE --> PHASE3["ProcessValidations"]
    LIFECYCLE --> PHASE4["UpdateModelValues"]
    LIFECYCLE --> PHASE5["InvokeApplication"]
    LIFECYCLE --> PHASE6["RenderResponse"]
    PHASE4 --> BEANS["Managed Beans<br/>Application Model"]
    PHASE6 --> VIEW["JSF View<br/>Facelets / JSP"]
```

1. The **deployment descriptor** (`web-full.xml`) registers `FacesServlet` as the servlet handling JSF URL patterns.
2. The **servlet container** (Tomcat, GlassFish, etc.) dispatches matching HTTP requests to `FacesServlet`.
3. `FacesServlet` **delegates** to the JSF lifecycle, which runs through its six phases.
4. During those phases, **managed beans** supply application state and **JSF view templates** (Facelets or JSP) produce the final HTML response.

## Key Patterns and Architecture

### Front Controller Pattern
`FacesServlet` acts as a front controller, centralizing all request handling and funneling JSF traffic through a single entry point. There is exactly one `FacesServlet` per application, and it must be thread-safe since the runtime uses thread-local storage to isolate per-request data (via `FacesContext`).

### Phase-Based Lifecycle
The JSF request is processed through six mandated phases, each with a distinct responsibility:

| Phase | Responsibility |
|---|---|
| RestoreView | Reconstruct the component tree from the view state |
| ApplyRequestValues | Capture user input from the rendered components |
| ProcessValidations | Run converters and validators on submitted values |
| UpdateModelValues | Push validated values into managed bean properties |
| InvokeApplication | Execute action listeners and navigation rules |
| RenderResponse | Build the HTML response from the component tree |

This phased architecture cleanly separates concerns: component restoration, input capture, validation, model mutation, business logic, and rendering are each isolated into their own phase.

### Stub Implementation
In this codebase, `FacesServlet` appears as a minimal class stub (`public class FacesServlet {}`). The real lifecycle implementation, component rendering, and state management come from the JSF runtime dependency (e.g., Mojarra or MyFaces) on the classpath. This repository provides the API skeleton and integration point; production behavior is provided externally.

## Dependencies and Integration

### Inbound Dependencies
- **`web-full.xml`** — The deployment descriptor at [`full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml) registers `FacesServlet` with the servlet container:

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

  This confirms the application is JSF-capable and wires the servlet to handle JSF URL patterns.

### Outbound Dependencies
- **`javax.servlet`** — `FacesServlet` extends `HttpServlet`, integrating with the servlet API to receive HTTP requests.
- **`javax.faces` core packages** — The webapp subpackage delegates to core JSF API classes (`javax.faces.application.Application`, `javax.faces.lifecycle.Lifecycle`) for actual request processing.
- **External JSF runtime** — The production implementation of `FacesServlet` and the full lifecycle comes from a JSF implementation library (Mojarra, MyFaces, or similar) on the classpath.

## Notes for Developers

- **Don't look for lifecycle code here:** The `FacesServlet` stub in this repository is a placeholder. The real implementation — phase logic, view restoration, rendering, state management — lives in the JSF runtime dependency. Do not expect to find these in the source tree.

- **URL mapping drives behavior:** How `FacesServlet` is mapped in `web.xml` (e.g., `*.jsf`, `*.faces`, `/faces/*`) determines which URLs trigger the JSF lifecycle. Changes to the mapping are the primary lever for routing behavior.

- **Thread safety matters:** Since JSF declares exactly one `FacesServlet` per application and uses `FacesContext` bound per-request via thread-local storage, the servlet must be thread-safe. Avoid storing per-request state in instance fields.

- **Zero indexed symbols:** This module currently has zero indexed source files, classes, interfaces, and methods. The API contract is defined externally; this documentation reflects the structural role the package plays rather than concrete implementation details.

- **Other JSF subpackages are absent:** Subpackages like `javax.faces.component`, `javax.faces.render`, and `javax.faces.event` are expected from the runtime library and are not present in this codebase's index. Only `javax.faces.webapp` has any presence here.