# Javax

## Overview

The `javax` package area contains the Java EE runtime integration layer for this codebase, primarily centered on **JavaServer Faces (JSF)**. JSF is the component-based web framework used here for building user interfaces — providing a structured, event-driven model analogous to Swing or JavaFX, but adapted for web applications.

This area is pure infrastructure. It does not contain business logic or domain entities. Instead, it bridges the standard Servlet API with the JSF component model, enabling the rest of the application to operate on a declarative, component-tree basis. The `javax.faces` subpackage is the key entry point, wiring the `FacesServlet` into the servlet container as the primary request dispatcher for all `.xhtml` and `.jsf` pages through the standardized six-phase JSF request lifecycle.

The core JSF API classes themselves are not part of this repository — they are provided externally by an implementation library such as Eclipse Mojarra or Apache MyFaces. What lives here is the stub wiring and deployment configuration that satisfies the build and runtime expectations of the JSF framework.

## Sub-module Guide

This package delegates to a single child module:

### `javax.faces` — JSF Integration

The `javax.faces` subpackage provides the JSF layer. Within it, the `javax.faces.webapp` subpackage is where the actual integration code resides — specifically the `FacesServlet` class.

**Relationship**: While the parent `javax.faces` namespace has no indexed source files (the core JSF API is provided by the Java EE runtime), `webapp` contains the one concrete piece of JSF plumbing in this codebase. The parent defines the broader API contract; `webapp` is the wire that plugs it into a Servlet container. In a fully-populated JSF runtime, the parent package would hold component, lifecycle, and faces context classes — but here, all that logic lives in the external JSF library, not in this repository.

## Key Patterns and Architecture

### Six-Phase Request Lifecycle

Every JSF request flows through a well-defined lifecycle orchestrated by `FacesServlet`:

```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"]
```

The six phases are:

1. **Restore View** — The framework reconstructs the component tree from 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 backing beans (ManagedBeans or 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 with Filter Pre-processing

The deployment descriptor (`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 request parameters are correctly decoded before JSF binds them to component values — a critical detail for multi-byte character support in internationalized applications.

### Stub vs. Implementation Separation

`FacesServlet` in this codebase is an empty class stub. This pattern indicates 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.

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 extend these 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 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 deployment descriptor fragment shown, meaning the full URL-to-servlet mapping is either in a separate 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 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.