# Javax / Faces

## Overview

The `javax.faces` package represents the root of the JavaServer Faces (JSF) integration within this codebase. JSF is the Java EE component-based web framework that provides a structured, event-driven model for building user interfaces — akin to Swing or JavaFX, but for web applications. In this project, the JSF layer is wired into the servlet container as the primary request dispatcher, handling all `.xhtml` and `.jsf` pages through a standardized six-phase request lifecycle.

This package area is responsible for bridging the standard Servlet API with the JSF component model. It does not contain business logic or domain entities; rather, it is pure infrastructure that enables the rest of the web application to operate on a declarative, component-tree basis. The codebase appears to use a minimal or fixture-based JSF setup — the core `FacesServlet` is declared as an empty class stub, suggesting that actual JSF runtime behavior is expected to come from an external implementation library (e.g., Eclipse Mojarra or Apache MyFaces) rather than from code within this repository.

## Sub-module Guide

This subpackage delegates to a single child module:

### `javax.faces.webapp` — Web Servlet Integration

The `webapp` subpackage provides the servlet entry point that connects HTTP requests to the JSF request lifecycle. It contains the `FacesServlet` class, which is declared as the central dispatcher for all JSF-managed requests in this application.

**How it relates to the parent.** While `javax.faces` itself is a top-level package stub in this codebase (with no indexed source files or classes), the `webapp` subpackage is where the actual integration work happens — `FacesServlet` extends or replaces `javax.servlet.http.HttpServlet` to receive HTTP requests and delegate them to the JSF framework. In a fully-populated JSF runtime, the parent package (`javax.faces`) would contain the core API classes (components, lifecycle, faces context, converters, validators, navigation rules), while `javax.faces.webapp` sits at the boundary, translating between the Servlet world and the JSF world.

In this fixture, the relationship is simple but structural: the `webapp` module is the only concrete piece of the JSF puzzle that exists in code, and it exists to satisfy the deployment descriptor (`web-full.xml`). The parent `javax.faces` namespace provides the broader API contract, while `webapp` is the wire that plugs it into a Servlet container.

## Key Patterns and Architecture

### Request Lifecycle Pattern

JSF applications follow a well-defined six-phase lifecycle that every request passes through. `FacesServlet` orchestrates this:

```mermaid
flowchart TD
    Client["HTTP Client
.xhtml / .jsf requests"] --> Servlet["FacesServlet
javax.faces.webapp"]

    Servlet --> Filter["SjisFilter
Shift-JIS Encoding"]
    Filter --> Servlet
    Servlet --> Lifecycle["JSF Lifecycle
javax.faces.lifecycle"]
    Lifecycle --> Phases["JSF Phases
Restore View to Render Response"]
    Phases --> Response["HTTP Response
Rendered XHTML"]
```

1. **Restore View** — The framework reconstructs the component tree from the previous state (or creates a fresh one for POST requests).
2. **Apply Request Values** — Input component values from the HTTP request are decoded and set on the component tree.
3. **Process Validations** — Each component's validators (built-in and custom) run against the submitted values.
4. **Update Model** — Valid values are pushed into the backing beans (ManagedBeans / CDI beans).
5. **Invoke Application** — Application-level actions (button clicks, command links) are executed.
6. **Render Response** — The component tree is rendered, typically into XHTML/HTML, and written to the response.

This phase-based architecture decouples request handling, validation, state management, and rendering into distinct steps, making it straightforward to intercept or extend any part of the flow through JSF lifecycle listeners or phase events.

### Servlet-Driven vs. Filter-Driven Request Handling

The `web-full.xml` declares both `FacesServlet` and a `SjisFilter` (for Japanese Shift-JIS character encoding). Servlet filter execution order follows declaration order in the descriptor, so the encoding filter runs before `FacesServlet` processes the request. This ensures that request parameters are correctly decoded before JSF binds them to component values — a crucial detail for multi-byte character support in internationalized applications.

### Stub vs. Implementation Separation

The `FacesServlet` in this codebase is an empty class stub. This pattern suggests one of two things:

- **Fixture / test setup**: The repository may be a minimal build configuration or test fixture where the JSF runtime is provided externally (via a dependency like Mojarra). The stub satisfies the compiler while delegating to the library at runtime.
- **Extension point**: The stub may be intended as a base class to be extended or replaced by a subclass with real implementation, following a template or override pattern.

In either case, the architectural intent is clear: this is not where JSF logic lives. The logic belongs in the JSF implementation library and in the application's own managed beans and views.

## Dependencies and Integration

### External Dependencies

| Dependency | Role |
|------------|------|
| `javax.servlet` / `javax.servlet.http` | Servlet API — `FacesServlet` must implement or extend these interfaces to function as a web container servlet. |
| `javax.faces.lifecycle` | JSF core API — the `Lifecycle` interface that `FacesServlet` delegates to for phase execution. |
| `javax.faces.component` | JSF component tree API — used during the Restore View and Render Response phases. |
| `javax.faces.context` | `FacesContext` — the request-scoped object holding all state during a JSF request. |

### Inbound Integrations

| Source | Relationship |
|--------|-------------|
| `web-full.xml` | Registers `FacesServlet` as a named servlet and declares `SjisFilter` as an encoding filter preceding JSF processing. |
| XHTML views | The `.xhtml` pages (Facelets templates) are the primary client-side artifact that `FacesServlet` renders and serves. |

### Integration Notes

- `FacesServlet` is the sole gateway into the JSF pipeline from the Servlet container. Every `.xhtml` or `.jsf` URL in the application routes through it.
- Character encoding is handled orthogonally by `SjisFilter` before the JSF pipeline begins, keeping JSF concerns separate from transport-level concerns.
- There is no `<servlet-mapping>` visible in the fragment shown, meaning the full URL-to-servlet mapping is either in a separate deployment descriptor or handled by the container's default behavior. In production, a pattern like `*.xhtml` or `/faces/*` is typically mapped.

## Notes for Developers

- **Empty stub class**: `FacesServlet.java` is currently an empty class declaration. Do not assume this file is where you add JSF servlet logic. If you need to customize request handling, extend `FacesServlet` or add a filter around it — do not add implementation to the stub itself unless you are replacing the JSF runtime.
- **No indexed source files**: The parent `javax.faces` package has zero indexed source files, classes, or methods. This is because the core JSF API is part of the Java EE runtime, not this codebase. All actual source you will work with lives in `javax.faces.webapp` (the servlet) or in application-level beans, views, and configuration.
- **Filter ordering matters**: The `SjisFilter` is declared before `FacesServlet` in `web-full.xml`. Changing this order could break character encoding for Japanese inputs. Be cautious if refactoring the descriptor.
- **URL mapping may be implicit**: If requests are not reaching `FacesServlet`, check whether a `<servlet-mapping>` exists elsewhere or whether the container is using a default pattern.
- **No nested submodules**: There are no additional modules under `javax.faces`. All JSF-related structure in this codebase flows through the `webapp` subpackage.