# Javax

## Overview

The `javax` package serves as the root namespace for **Java EE / Jakarta EE web integration** within this codebase. It encompasses the standard `javax.*` package hierarchy used by Java web applications — most notably **JavaServer Faces (JSF)**, the component-based UI framework for building server-driven web applications.

This package does not contain hand-written implementations of the Java EE specifications themselves. Instead, it provides the **servlet-level wiring** that connects the application's web container to the JSF runtime (such as Mojarra or MyFaces, which are supplied by the application server or classpath). The primary responsibility is registering and configuring `FacesServlet` — the front controller servlet that processes all JSF-bound HTTP requests through the six-phase JSF lifecycle.

## Sub-module Guide

### `javax.faces`

The `javax.faces` sub-module is the entry point for JSF integration. It contains:

- **`javax.faces.webapp`** — The servlet integration layer. Its central class, `FacesServlet`, extends `HttpServlet` and acts as the front controller for all JSF-bound requests. This is the bridge between the standard Servlet API and the JSF component lifecycle.

The `FacesServlet` class in the source tree is a declaration-only stub. The actual lifecycle logic — phase management, component tree restoration, validation, and rendering — lives in the JSF reference implementation (Mojarra/MyFaces) that is provided at runtime. The source code here serves as a deployable servlet descriptor that applications register in `web.xml`.

**Relationship between sub-modules**: `webapp` is the only direct child under `javax.faces`, making the entire package's purpose narrowly focused on this single front controller servlet. There are no other sub-modules to coordinate with; `FacesServlet` is the sole public API surface that external components interact with. The package's responsibility is purely infrastructural — it exposes the JSF lifecycle as a servlet that the web container can dispatch requests to.

## Key Patterns and Architecture

### The JSF Request Lifecycle

The defining architectural pattern in this package is the **front controller pattern** implemented by `FacesServlet`. Every JSF-bound request follows a rigid six-phase lifecycle:

1. **Restore View** — Rebuild the component tree from the saved view state, or create a new one on first visit.
2. **Apply Request Values** — Populate UI component properties from the incoming request parameters.
3. **Process Validations** — Run validators registered on each component and collect conversion/validation errors.
4. **Update Model Values** — Transfer validated data from UI components to the backing Java beans.
5. **Invoke Application** — Fire action events, execute business logic, and determine the next navigation outcome.
6. **Render Response** — Build the HTML (or other format) response from the component tree.

If any phase detects an error (e.g., validation fails), `FacesServlet` handles the transition gracefully — for instance, skipping ahead directly to the Render Response phase with error messages displayed rather than proceeding further.

```mermaid
flowchart TD
    A["HTTP Request"] --> B{"URL matches
FacesServlet mapping?"}
    B -->|No| C["Pass through to
other servlets"]
    B -->|Yes| D["Phase 1: Restore View"]
    D --> E{"View exists?"}
    E -->|No| F["Create new
component tree"]
    E -->|Yes| G["Restore from
view state"]
    F --> H["Phase 2: Apply Request Values"]
    G --> H
    H --> I["Phase 3: Process Validations"]
    I --> J{"Validation errors?"}
    J -->|Yes| K["Phase 6: Render Response"]
    J -->|No| L["Phase 4: Update Model Values"]
    L --> M["Phase 5: Invoke Application"]
    M --> N["Determine navigation outcome"]
    N --> K
```

### Filter Chain Architecture

Requests enter `FacesServlet` through a servlet filter chain that sits in front of it. In this codebase, encoding filters such as `X33JVRequestEncodingSjisFilter` are positioned in this chain, ensuring character encoding is set before any JSF processing begins. The filter chain is registered in `web.xml` and `web-full.xml`, which also define the `FacesServlet` mapping itself.

### Component Tree and View State

While the component tree management code is not present in this package, `javax.faces.webapp` is responsible for orchestrating its lifecycle. The view state — a serialized representation of the component tree — is stored per session and referenced in the HTML page (typically as a hidden field such as `_idJsnAll`). `FacesServlet` coordinates the serialization and deserialization of this state across the Restore View and Render Response phases.

```mermaid
flowchart LR
    A["HTTP Client"] --> B["Web Container"]
    B --> C["EncodingFilter"]
    C --> D["FacesServlet"]
    D --> E["JSF Lifecycle Phase Manager"]
    E --> F["Phase 1: Restore View"]
    E --> G["Phase 2: Apply Request Values"]
    E --> H["Phase 3: Process Validations"]
    E --> I["Phase 4: Update Model Values"]
    E --> J["Phase 5: Invoke Application"]
    E --> K["Phase 6: Render Response"]
    D --> L["Managed Beans"]
    L --> M["Business Logic"]
```

## Dependencies and Integration

### Inbound Dependencies

| Consumer | Purpose |
|---|---|
| `web.xml` | Registers `FacesServlet` with the servlet container and defines URL mappings |
| `web-full.xml` | Full Jakarta EE deployment descriptor registering `FacesServlet`, along with supporting filters like `SjisFilter` |

### Outbound Dependencies

`FacesServlet` integrates with:

- **JSF API** (`javax.faces.*`) — the core JSF framework classes for component tree management, phase listeners, and lifecycle execution. The full implementation comes from the JSF reference implementation at runtime.
- **Servlet API** (`javax.servlet.*`, `javax.servlet.http.*`) — standard web container interfaces for HTTP request and response handling.
- **Application-specific listeners and filters** — in this project, encoding filters (`X33JVRequestEncodingSjisFilter`) and context listeners (`X33AppContextListener`) are wired into the servlet filter chain around `FacesServlet`.

### Deployment Configuration

`FacesServlet` is mapped to URL patterns in the application's deployment descriptors. The choice of mapping has significant implications:

| URL Pattern | Implication |
|---|---|
| `*.jsf` | Safe and conventional; only JSF pages are processed through the lifecycle |
| `/faces/*` | All paths under `/faces/` are handled; less common in modern JSF |
| `/*` | Intercepts all requests, which can cause issues with static resources unless a resource handler is configured |

## Notes for Developers

### Empty Class Body is Expected

The `FacesServlet` class in the source code contains only a package declaration and class header with no methods or fields. This is expected — the full servlet implementation is provided by the JSF reference implementation at runtime. Do not be alarmed by the empty body; the behavioral logic comes from the servlet container's deployment of the JSF library on the classpath.

### Servlet Mapping Has Consequences

The URL pattern used to map `FacesServlet` significantly affects behavior. Using `/*` will intercept every request, including static assets, which may cause unexpected errors if no resource handler is configured. When in doubt, prefer `*.jsf` or `/faces/*` to avoid unintentionally processing static content.

### Filter Chain Best Practices

If you add filters around `FacesServlet`, keep these constraints in mind:

- Filters run **before** `FacesServlet` processes the request, so they can inspect or modify request parameters but must forward the request properly.
- Filters must not prematurely commit the response buffer, as this would cause `IllegalStateException` during the JSF render phase.
- Encoding filters should set the character encoding **before** any JSF processing, typically by calling `request.setCharacterEncoding()`.

### Extending FacesServlet

If you need custom lifecycle behavior — such as per-request audit logging or custom view restoration — the recommended approach is to extend `FacesServlet` and override lifecycle methods such as `initFacesContext()` or `createFacesContext()`. Alternatively, implement a `PhaseListener` to inject behavior at specific lifecycle phases without modifying the servlet itself.