# Javax

## Overview

The `javax` module covers the Java Enterprise Edition (now Jakarta EE) platform namespace — the collection of Java APIs that define the server-side programming model for building enterprise applications on the JVM. This namespace includes APIs for web services, enterprise JavaBeans, transaction management, JavaMail, JAX-WS, and JavaServer Faces (JSF), among others.

Within this module, the indexed documentation focuses on the `javax.faces` subpackage — the runtime core of JavaServer Faces, a component-based web application framework built on top of the Java Servlet API. JSF provides a full server-side Model-View-Controller (MVC) stack, replacing raw servlet and JSP manipulation with a structured lifecycle, event model, and server-side UI component tree.

## Sub-module Guide

### `javax.faces` — The Web Application Framework

The `javax.faces` subpackage is the JSF runtime heart of this module. It encompasses:

- **Lifecycle infrastructure** (`javax.faces.lifecycle`) — the six-phase request lifecycle that drives every JSF request.
- **Component model** (`javax.faces.component`) — the server-side UI component tree (`UIComponent`, `UIViewRoot`, `UIInput`, `UIOutput`, `UIData`, etc.).
- **Context management** (`javax.faces.context`) — `FacesContext` and `ExternalContext`, which carry per-request state including messages, flash scope, and raw request/response objects.
- **Data binding** (`javax.faces.convert`, `javax.faces.validator`) — built-in converters for type conversion and validators for field-level validation rules.
- **Web entry point** (`javax.faces.webapp`) — `FacesServlet`, the Front Controller that bridges the servlet container to the JSF framework.

#### How the sub-modules relate

The `javax.faces.webapp` subpackage sits at the top of the dependency hierarchy — it is the *gateway* layer. All other `javax.faces` subpackages feed into it:

```mermaid
flowchart LR
    webapp["javax.faces.webapp<br/>(FacesServlet, Front Controller)"] --> ctx["javax.faces.context<br/>(FacesContext)"]
    webapp --> lifecycle["javax.faces.lifecycle<br/>(PhaseId, PhaseListener)"]
    webapp --> components["javax.faces.component<br/>(UIComponent Tree)"]
    webapp --> convert["javax.faces.convert<br/>(Type Converters)"]
    webapp --> validator["javax.faces.validator<br/>(Field Validators)"]
    webapp --> application["javax.faces.application<br/>(Navigation, Resources)"]
```

The `webapp` subpackage orchestrates the core subpackages: it creates a `FacesContext`, delegates to the lifecycle engine, which in turn manipulates the component tree, runs converters/validators, and updates backing beans. There are no independent sibling sub-modules at this level — `webapp` is the top-level child of `javax.faces`, and everything else it touches lives in sibling subpackages.

## Key Patterns and Architecture

### The Six-Phase JSF Lifecycle

Every HTTP request mapped to `FacesServlet` traverses a fixed sequence of six phases:

```mermaid
flowchart TD
    phase1["1. Restore View<br/>Rebuild component tree from state"] --> phase2["2. Apply Request Values<br/>Populate components from request params"]
    phase2 --> phase3["3. Process Validations<br/>Convert, validate, report errors"]
    phase3 --> phase4["4. Update Model Values<br/>Transfer valid data to backing beans"]
    phase4 --> phase5["5. Invoke Application<br/>Execute action methods and navigation"]
    phase5 --> phase6["6. Render Response<br/>Build HTML output from component tree"]
```

Validation failure at phase 3 short-circuits to phase 6 (Render Response) with errors displayed. This deterministic flow is the architectural backbone of the entire `javax.faces` module.

### Front Controller Pattern

`FacesServlet` implements the Front Controller pattern: a single entry point that classifies requests (GET vs POST), creates per-request `FacesContext` instances, and sequentially invokes lifecycle phases. This centralizes error handling, state management, and cross-cutting concerns across every JSF request.

### Server-Side Component State

JSF preserves the full UI component tree between requests through server-side view state stored in the HTTP session (or optionally in a hidden form field). The `UIViewRoot` is recreated each request from stored state during the Restore View phase, enabling rich interactivity without requiring the client to understand page structure.

### Extensibility Model

The module provides multiple extension hooks that developers use to customize behavior:

| Hook | Purpose |
|------|---------|
| `PhaseListener` | Execute custom logic before or after any lifecycle phase. |
| `ViewHandler` | Customize view creation, rendering, and navigation. |
| `FacesConverter` | Define custom type conversion (e.g., string-to-object). |
| `FacesValidator` | Apply custom validation rules to components. |
| `Lifecycle` | Implement a custom lifecycle (rare; `PhaseListener` is preferred). |
| `FacesListener` (Component) | React to component events like value change or add. |

For cross-cutting concerns such as authentication or logging, a Servlet Filter is typically preferred over extending the JSF lifecycle directly.

## Dependencies and Integration

### Internal Structure

The `javax.faces` package depends on core Java EE APIs. The integration chain flows as follows:

```mermaid
flowchart TD
    subgraph External["External"]
        client["Browser / Client"]
    end
    subgraph Servlet["javax.faces.webapp"]
        servlet["FacesServlet"]
        lifecycle["JSF Lifecycle"]
        stateMgmt["View State Mgmt"]
    end
    subgraph Core["javax.faces Core"]
        ctx["FacesContext"]
        viewRoot["UIViewRoot"]
        components["UIComponent Tree"]
        managedBeans["Managed Bean"]
    end
    subgraph Config["Configuration"]
        webXml["web-full.xml"]
        initParams["Init Parameters"]
    end
    client -->|"HTTP Request"| servlet
    servlet -->|"invokes"| lifecycle
    lifecycle -->|"Restore View"| viewRoot
    viewRoot -->|"holds"| components
    lifecycle -->|"Apply Request Values"| ctx
    lifecycle -->|"Process Validations"| ctx
    lifecycle -->|"Update Model"| managedBeans
    lifecycle -->|"Invoke Application"| managedBeans
    lifecycle -->|"Render Response"| components
    components -->|"encodeEnd"| html["HTML Output"]
    html --> client
    servlet -->|"stores state"| stateMgmt
    stateMgmt -->|"restores"| viewRoot
    servlet -->|"reads config from"| webXml
    webXml --> initParams
```

### External Dependencies

| External System | Integration Method |
|----------------|-------------------|
| Servlet Container | `javax.servlet.Servlet` API; integrates with Tomcat, Jetty, WebLogic, etc. |
| Facelets | `.xhtml` view technology; the modern JSF 2.x+ default view handler. |
| JSP (legacy) | `.jsp` views; supported in older JSF 1.x applications. |
| CDI / Managed Beans | `javax.enterprise.context` (CDI, JSF 2.x+) or JSF's built-in managed-bean mechanism (JSF 1.x). |
| EL (Expression Language) | `javax.el` resolves `${bean.property}` expressions in view templates. |

### Configuration

JSF behavior is controlled through initialization parameters in the web deployment descriptor (`web-full.xml`):

| Parameter | Purpose |
|-----------|---------|
| `javax.faces.DEFAULT_SUFFIX` | Default view file extension (e.g., `.xhtml` for Facelets). |
| `javax.faces.PROJECT_STAGE` | Runtime stage (`Development`, `Production`, `System`, `UnitTest`). |
| `javax.faces.FACELETS_REFRESH_PERIOD` | Facelets template reload interval during development. |

Project stage controls debug output, EL validation strictness, and template compilation caching — a critical distinction for production deployments.

## Notes for Developers

### Thread Safety

`FacesServlet` is inherently thread-safe. The servlet container creates a single instance handling all requests concurrently. Each request receives its own `FacesContext` instance, so there is no shared mutable state between threads at the request level.

### Extending vs. Using Hooks

You should **not** extend `FacesServlet` directly. Instead:

- Use **`PhaseListener`** for pre/post lifecycle phase hooks.
- Use a **Servlet Filter** for cross-cutting concerns (authentication, logging, GZIP compression).
- Use **`ViewHandler`** overrides to customize view creation and rendering.
- Use **`FacesConverter`** / **`FacesValidator`** for type-specific logic.

### Project Stages in Practice

- **`Development`** — Disables facelets compilation caching, enables strict EL validation and debug output. Ideal for local iteration.
- **`Production`** — Enables all optimizations, disables debug output. The default deployment stage.
- **`System`** / **`UnitTest`** — Intermediate stages for integration testing or system-level validation.

### Troubleshooting

| Symptom | Likely Cause |
|---------|-------------|
| 404 on JSF pages | Servlet mapping in `web-full.xml` does not match the request URL pattern. |
| Missing component tree state | Session storage limits exceeded; check session configuration for large component trees. |
| EL expressions not resolving | Verify `javax.faces.DEFAULT_SUFFIX` is set correctly and the Facelets/JSP library is on the classpath. |
| Duplicate form submission issues | Ensure proper use of the POST-Redirect-GET pattern in action methods. |

### State Management Considerations

For large-scale deployments, the default server-side view state stored in the HTTP session can become a memory bottleneck. Options include:

- **Client-side state** — Store view state in a hidden form field instead of the session (`javax.faces.STATE_SAVING_METHOD=context`). This shifts memory to the client but increases page size.
- **Stateless views** — Use `UIViewRoot` without state saving for pages with no form input or AJAX updates.
- **Session replication** — In clustered environments, ensure HTTP sessions (and their stored view state) are properly replicated across nodes.

### View Technology Choice

- **Facelets (`.xhtml`)** is the modern, recommended view technology for JSF 2.x and later. It offers template composition, tag libraries, and faster compilation than JSP.
- **JSP (`.jsp`)** is legacy and primarily seen in JSF 1.x applications. It has slower compilation and limited template support.