# Root

## Overview

This repository is a multifaceted codebase centered around three distinct Java web application domains: a legacy Japanese enterprise system built on the Servlet/JSP stack, a JSF-based presentation layer, and a test fixture infrastructure for static analysis rules (SonarQube-style linting). Together, these packages form a system that spans production-facing web infrastructure, presentation-layer MVC scaffolding, and code-quality tooling fixtures.

At the highest level, the codebase represents a **stub-first development model**: large swathes of the code exist as structural scaffolding — classes registered in deployment descriptors, beans wired through XML config, and empty method bodies awaiting business logic. This suggests the repository is either a greenfield scaffold for an enterprise application, a maintenance burden on a legacy system, or a combination of both. The presence of extensive test fixture packages further indicates the project invests in static analysis and structural linting rules.

The three major areas of responsibility are:

1. **`javax.faces`** — The JSF framework API surface (front-controller servlet, lifecycle, component model). This is the foundational web framework the application depends on.
2. **`com`** — Application-level packages, split into the `fujitsu` sub-package (a Japanese enterprise web-tier scaffold with Shift JIS encoding support) and the `example` sub-package (test fixtures for import-resolution linting rules).
3. **`eo`** — A JSF MVC presentation layer (`eo.web`) that bridges the application's business layer to end users through XML-configured backing beans and JSP views.

## Sub-module Guide

The root packages form a layered architecture where each child sub-module serves a distinct role:

### `javax.faces` — The JSF Framework Foundation

This namespace exposes the public API surface of JavaServer Faces. The key component is `javax.faces.webapp.FacesServlet`, which implements the front controller pattern: a single servlet that all JSF requests flow through. It orchestrates the six-phase JSF lifecycle (restore view, apply request values, process validations, update model values, invoke application, render response) for every intercepted HTTP request.

The `FacesServlet` is the bridge between the servlet container and the JSF runtime. It creates a per-request `FacesContext`, dispatches through lifecycle phases, renders the component tree via pluggable render kits, and cleans up the context. This package has no implementation beyond a minimal stub — a production-grade implementation would contain the full lifecycle delegation logic.

**How it fits:** This is the framework layer. Application code (`com.fujitsu` and `eo.web`) builds on top of it. The `FacesServlet` is registered in `web.xml` and `web-full.xml` deployment descriptors, making it the central request-routing component.

### `com.fujitsu` — The Servlet Web Tier (Stub-And-Wire)

The `com.fujitsu` package is the root namespace for "Futurity," an older Japanese enterprise application. At the current stage, this entire package follows a **stub-and-wire** pattern: classes are registered in deployment descriptors and can be instantiated by the servlet container, but they contain no implementation logic. The sole active sub-module is:

**`com.fujitsu.futurity.web.x33`** — Contains a `ServletContextListener` (`X33AppContextListener`) for application bootstrap/teardown, and a servlet filter (`X33JVRequestEncodingSjisFilter`) for normalizing character encoding (Shift JIS) on incoming HTTP requests. Both components are no-op stubs.

This package sits as the outermost boundary between the servlet container and any future business-layer packages. It intercepts requests and manages lifecycle events. The dual registration of both filter and listener in `web.xml` and `web-full.xml` (supporting basic and full deployment profiles) should be audited for potential duplicate activations.

**How it relates to `javax.faces`:** Both packages serve the web-tier responsibility, but from different angles. `javax.faces` provides the JSF framework runtime; `com.fujitsu` provides the application-specific servlet configuration. They coexist in the same deployment — `FacesServlet` handles JSF requests while the `X33JVRequestEncodingSjisFilter` may intercept all requests (including JSF ones) to normalize encoding.

**How it relates to `eo.web`:** Both are web-facing layers, but `com.fujitsu` operates at the servlet/filter level (lower-level HTTP handling, encoding normalization), while `eo.web` operates at the JSF MVC level (backing beans, JSP views, XML-configured wiring). They could coexist in the same application: the `com.fujitsu` filter intercepts HTTP requests first, then JSF-managed requests flow through `FacesServlet` into `eo.web` view components.

### `eo.web` — The JSF MVC Presentation Layer

The `eo.web` package is the user-facing presentation layer of the EO application. It follows a uniform two-class JSF MVC pattern:

- **Backing beans** (e.g., `ACA001SFBean`) — Lightweight POJOs with a single property, visible to the JSP view via Expression Language.
- **Logic handlers** (e.g., `ACA001SFLogic`) — Controller objects whose `execute()` method prepares data for the bean. Currently empty — a stub awaiting implementation.

This sub-module is wired entirely through XML descriptors (`faces-config.xml` and supplemental `WEBGAMEN_*`, `x33S_*` files), consistent with traditional JSF 1.x / early JSF 2.x deployment. The `webview` sub-package (`eo.web.webview`) is the only current sub-module, handling a "futurity view" use case.

**How it fits:** This is the highest-level application code — the part that directly renders data to users. It depends on the JSF framework (`javax.faces`) for its lifecycle and rendering infrastructure.

### `com.example` — Test Fixtures for Static Analysis

This package exists entirely as structural scaffolding for static analysis. It does not contain production code. The only sub-module is:

**`com.example.bugca002`** — A minimal stub class (`KnownClass`) that serves as an import resolution target for the `bug-ca-002` Sonar rule. This rule checks that JSP `<jsp:useBean>` or `<%@ page import %>` directives appear in canonical order. `KnownClass` gives the rule a concrete class to validate against.

This area follows a **fixture-based testing pattern**: classes are minimal, have no dependencies, and exist solely as deterministic anchors for linting rules. Each rule gets its own package, preventing cross-rule interference.

**How it relates to everything else:** This is a leaf in the module dependency graph. It is consumed by test fixture JSP files (like `BugCa002Language Before Import.jsp`) that the static analysis engine uses to validate import-resolution and structural rules. It does not interact with the production code in any way.

## Key Patterns and Architecture

### Stub-and-Wire (Comprehensive)

A unifying pattern across `com.fujitsu` and `eo.web` is the **stub-and-wire** development strategy: infrastructure is wired into deployment descriptors first so that deployment, XML validation, and integration tests pass, and business logic is filled in later. This means:

- Servlet filters, listeners, and beans are registered but contain no-op implementations.
- Bean properties are present but lack setters (preventing user input binding until logic is added).
- Logic handler `execute()` methods are empty bodies awaiting business service calls.

This pattern allows the team to establish a stable deployment baseline before implementation, but it also means the codebase's runtime behavior is currently invisible — the servlet container creates these objects with no observable effect.

### JSF MVC Pattern

Both `javax.faces` (as the framework) and `eo.web` (as the application layer) implement the JSF MVC pattern, but at different abstraction levels:

```
[Backing Bean] <--> [Logic Handler]
       ^                    |
       |                    | prepares data
       |                    v
       +---- JSP View <----+
```

The backing bean is the model visible to the view. The logic handler serves as the controller, fetching data and writing it to the bean. The JSP renders the bean's properties via JSF EL. Configuration-driven wiring (XML descriptors) replaces annotation-heavy setup, consistent with older JSF versions.

### Import Resolution as Structural Validation

The `com.example` package demonstrates a subtle architectural concern: **import resolution validation**. Static analysis tools must be able to resolve every import reference (from JSP files, backing beans, logic classes) against actual class definitions. The fixture classes in `com.example` serve as guaranteed-resolution anchors — they are minimal, dependency-free, and always resolvable, making them reliable targets for linting rule testing.

### Front Controller + Encoding Filter

The integration between `com.fujitsu` and `javax.faces.webapp.FacesServlet` illustrates a common web architecture pattern:

1. The `X33JVRequestEncodingSjisFilter` (in `com.fujitsu`) intercepts **all** HTTP requests first, normalizing character encoding.
2. Requests matching the JSF URL pattern (e.g., `*.jsf`) then flow to `FacesServlet`, which delegates to the JSF lifecycle.
3. `FacesServlet` dispatches through the six-phase lifecycle, eventually rendering a response from the `eo.web` backing beans.
4. On application shutdown, `X33AppContextListener.contextDestroyed()` handles cleanup.

### Module Interaction Diagram

The following diagram shows how the three major package areas interact:

```mermaid
flowchart TD
    subgraph framework["JSF Servlet Framework"]
        JF["javax.faces - JSF API surface"]
        JFW["javax.faces.webapp - FacesServlet"]
    end
    subgraph apps["Application Packages"]
        FJT["com.fujitsu - Servlet web tier"]
        EO["eo.web - JSF MVC presentation"]
    end
    subgraph test["Test Infrastructure"]
        CE["com.example - Static analysis fixtures"]
    end
    JF --> JFW
    EO --> JFW
    FJT --> JF
    CE -.-> JFW
```

## Dependencies and Integration

### External Framework Dependencies

| Dependency | Purpose |
|---|---|
| `javax.servlet.*` | Servlet API — all web-tier classes depend on `Filter`, `FilterChain`, `FilterConfig`, `ServletContextListener`, `ServletRequest`, `ServletResponse` |
| `javax.faces.*` | JSF API — backing beans, lifecycle, component tree, render kit |
| `web.xml` / `web-full.xml` | Deployment descriptors registering `FacesServlet`, filters, and listeners. The dual registration across basic and full profiles should be audited. |
| `faces-config.xml` | JSF managed bean registration and view configuration for `eo.web` components |

### Cross-Module Flow

Production requests flow through this sequence:

1. **Servlet container** receives an HTTP request.
2. **`X33JVRequestEncodingSjisFilter`** (in `com.fujitsu`) intercepts and normalizes character encoding.
3. If the request matches a JSF pattern, **`FacesServlet`** (`javax.faces.webapp`) creates a `FacesContext` and starts the six-phase lifecycle.
4. **`eo.web`** backing beans and logic handlers participate in the lifecycle phases (apply request values, update model, render response).
5. The response is rendered to the browser as HTML.

### Test Infrastructure Dependencies

Test fixtures in `com.example` are consumed by JSP test files (e.g., `BugCa002Language Before Import.jsp`) that validate static analysis rules. These fixtures are not part of the production runtime and are isolated from the application packages.

### No Child Modules at Root Level

At the top level, there are no further sub-packages beyond the three documented areas. All related code resides within the sub-packages already described.

## Notes for Developers

- **This is largely a stub-only codebase.** Large portions of `com.fujitsu` and `eo.web` contain empty method bodies and are registered in deployment descriptors as no-ops. Any developer working in these packages should treat existing classes as scaffolding and plan for significant implementation work ahead.

- **Stub-and-wire is intentional.** Classes are deployed-first, logic-second. This allows the team to establish deployment baselines (XML validation, integration tests) before writing business logic. Do not treat empty `execute()` methods as complete implementations.

- **JSF version matters.** The reliance on `faces-config.xml` for bean registration (rather than `@ManagedBean` or `@Named` annotations) suggests this codebase targets JSF 1.x or early JSF 2.x. When adding new components, check whether annotation-based configuration is available or if XML wiring is still required.

- **The `javax.faces` namespace is Java EE.** In Jakarta EE 9+ (JSF 3.x+), the package is `jakarta.faces.*`. Migration between the two requires namespace replacement across all imports and deployment descriptors.

- **Dual deployment profile registration.** Both `web.xml` and `web-full.xml` register the same filters and listeners. If both descriptors are deployed simultaneously, the servlet container may issue warnings or behave unpredictably due to duplicate registrations. Audit these configurations.

- **Test fixtures must stay minimal.** Classes in `com.example` are intentionally empty. Adding business logic, dependencies, or side effects would turn a test fixture into production code, introducing unnecessary risk and maintenance burden.

- **Package naming convention for fixtures.** The `bugca002` package name follows the pattern `<rule-id-classifier>` used across the project. New test fixtures for other rules should follow the same pattern: create a package named after the rule, place a minimal class inside, and reference it from the appropriate fixture JSP/JSF file.

- **Extension points.** When implementing business logic:
  - `com.fujitsu`: `X33JVRequestEncodingSjisFilter.doFilter()` for encoding normalization, `X33AppContextListener.contextInitialized()` for bootstrap.
  - `eo.web`: `ACA001SFLogic.execute()` for futurity view data preparation.
  - `javax.faces`: `FacesServlet` is a framework-level component — modifications should follow the Jakarta Faces specification rather than be implemented from scratch.

- **This area does not execute at runtime.** Any developer encountering `com.example` classes in a runtime stack trace should investigate why test infrastructure code is being loaded outside of analysis.