# Root

## Overview

The root package acts as a namespace container with no indexed source files, classes, or methods at its own level. It organizes three distinct concern areas, each occupying its own branch of the package hierarchy:

- **`com`** — The Java convention prefix, split into two unrelated sub-branches. `com.example` contains lightweight test-fixture stubs used to exercise code-quality and linting rules. `com.fujitsu.futurity` hosts the Futurity application platform, a Java EE-based web application structured around a regional-variant architecture (separate packages for different market deployments such as Japan, US, and Europe).
- **`eo`** — The application's presentation tier, built on JavaServer Faces (JSF). It provides the user-facing web UI through a layered package structure (`eo.web` → `eo.web.webview` → leaf view modules like `ACA001SF`), where each view is decomposed into a backing bean (state holder) and a logic class (action handler).
- **`javax`** — The Java EE framework layer, specifically the `javax.faces` sub-packages that provide the JSF runtime infrastructure (`FacesServlet`, lifecycle management, component models). This is the underlying framework that `eo.web` depends on to function.

At the package level the codebase is largely skeletal. Most documented modules contain stub classes, no-op filters, and placeholder listeners wired through XML deployment descriptors. The architecture appears to be in scaffolding or migration state: the structural hooks are in place, but active runtime logic has not yet been implemented across the majority of the module tree. The `com.example` and `eo.web.webview.ACA001SF` sub-modules are explicitly labeled as forward-looking scaffolds (e.g., the Javadoc comment "Futurity view logic" on `ACA001SFLogic`).

## Sub-module Guide

### The `com` branch

The `com` namespace splits into two entirely unrelated sub-branches that share only the top-level Java convention of prefixing with `com`.

**`com.example` — Test-fixture stubs**

This sub-branch exists solely to support code analysis, linting, and static analysis tooling. It contains no production code. Its only child, `com.example.bugca002`, provides a `KnownClass` placeholder whose sole purpose is to satisfy Java import resolution in test JSP files (specifically `BugCa002Language Before Import.jsp`). The class has an empty `execute()` method as a minimal API surface.

The `bugca002` module is tightly coupled to a single consumer: the JSP file that imports `KnownClass` to test language-level import behavior. The naming convention (`bugca002`) maps to a code quality rule scenario, and the relationship is directional — `bugca002` provides the type, and the JSP consumes it to validate that the import resolves correctly.

**`com.fujitsu.futurity` — Futurity platform**

The Futurity platform is a Java EE web application built around a **regional-variant architecture**. The documented `x33` subpackage (Japanese market) defines the pattern that all other regional variants (e.g., `X33US`, `X33EU`) mirror. Each variant provides its own:

- **Context listener** (`X33AppContextListener`) — bootstraps x33-specific resources at application startup. Currently a no-op stub with no methods or imports.
- **Character-encoding filter** (`X33JVRequestEncodingSjisFilter`) — intercepts incoming HTTP requests and sets the request character encoding to Shift JIS (`MS932`) for the Japanese market. Currently passes requests through unmodified.

The platform uses traditional XML-driven deployment (`web.xml` / `web-full.xml`) with no Spring annotations, Java-based configuration, or dependency injection. The regional-variant pattern lets each market deploy its own encoding strategy and initialization logic while sharing the broader application core. The filter and listener serve complementary roles in the servlet pipeline: the listener runs once at startup, the filter runs per-request.

### The `eo` branch

The `eo` namespace contains the application's JSF-backed presentation tier.

**`eo.web` — Presentation tier**

This is the top-level package for the application's web UI. It delegates all view-level responsibility to its sole child, `eo.web.webview`. If new web-level capabilities are added (e.g., REST controllers, servlet filters), they would appear as sibling sub-packages under `eo.web`.

**`eo.web.webview` — JSF view tier**

This sub-package implements the JSF view layer using a consistent **two-class-per-view** pattern. Each JSF page gets:

- A **backing bean** (e.g., `ACA001SFBean`) that holds view-scoped state and exposes JavaBean properties bound to UI components via EL expressions (e.g., `#{aca001sfBean.value}`).
- A **logic class** (e.g., `ACA001SFLogic`) that contains the `execute()` action handler invoked when a user submits a form or clicks a button.

The `ACA001SF` leaf module is a representative example. Its bean exposes a single read-only `String` property (`value` via `getValue()`), and its logic class has an empty `execute()` method with the Javadoc comment "Futurity view logic" — a deliberate indicator that this is a forward-looking scaffold.

The same view components participate in multiple navigation contexts, wired through XML files (`faces-config.xml`, `WEBGAMEN_FULL_ACA001.xml`, `WEBGAMEN_ACA001010PJP.xml`, `x33S_ACA001.xml`, `external-refs.xml`). This declarative wiring means the same Java classes can be reused across different workflows without code changes. Views communicate through JSF navigation rules defined in XML, not through direct Java references.

### The `javax` branch

The `javax` namespace provides the JSF framework infrastructure that `eo.web` depends on.

**`javax.faces` — JSF core framework**

This package sits at the root of the JSF framework namespace. It defines the core abstractions: the six-phase request lifecycle (Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, Render Response), the component tree model, and application state management. The package itself has no directly indexed source files — its types live in subpackages.

**`javax.faces.webapp` — FacesServlet**

This sub-package provides `FacesServlet`, the central entry point for all JSF requests. It intercepts HTTP traffic routed via URL patterns (typically `*.xhtml` or `/faces/*`) and drives the JSF lifecycle. In this codebase, `FacesServlet` is a minimal stub — the actual lifecycle implementation is inherited from the JSF reference implementation (e.g., Mojarra or MyFaces). All behavioral configuration happens through `web.xml` and `web-full.xml` deployment descriptors.

### How the three branches relate

The three branches serve distinct layers of the system:

- **`javax.faces`** provides the runtime framework that **`eo.web.webview`** uses to implement its JSF views. The `FacesServlet` is configured in `web.xml` alongside the Futurity platform's filter and listener.
- **`com.fujitsu.futurity`** shares the same servlet container and deployment descriptors (`web.xml`, `web-full.xml`) with the JSF infrastructure. Its context listener and encoding filter operate as co-located infrastructure alongside `FacesServlet`.
- **`com.example`** is isolated from the application tiers. It exists only as a test-fixture namespace for code-quality tooling and has no runtime dependencies on `eo`, `javax`, or `com.fujitsu.futurity`.

The `javax.faces` and `eo.web` modules together form a two-tier JSF web architecture: the framework tier (`javax.faces`) handles request routing and lifecycle, while the application tier (`eo.web`) handles view state and action handling. The `com.fujitsu.futurity` module sits at the servlet-container layer, providing lifecycle hooks and request-processing interceptors that sit between the container and both the JSF servlet and any business logic.

## Key Patterns and Architecture

### Skeleton / stub pattern across the codebase

A unifying observation is that the majority of documented modules are scaffolds. Filters that pass requests through unmodified, listeners with no methods, and logic classes with empty `execute()` methods suggest the codebase is in one or more of these states:

1. **Fresh scaffolding** — the structural skeleton is in place and implementation is deferred.
2. **Migration aftermath** — logic existed previously but was migrated to higher-level layers (e.g., global servlet container configuration in `server.xml`).
3. **Variant scaffolding** — `com.fujitsu.futurity` shares infrastructure with other regional variants, with market-specific logic deferred to sibling packages.

The "Futurity" Javadoc comments across both `com.fujitsu.futurity` and `eo.web.webview.ACA001SF` confirm this intent — these modules were created as structural placeholders.

### Two-class JSF view pattern

The foundational architectural pattern in `eo.web.webview` is the separation of view state from view behavior. Every JSF page gets two corresponding classes:

```
[JSF page JSP]  <-->  [Bean: state holder]  <-->  [Logic: action handler]
```

- **Bean properties** survive across render phases and are bound to UI components via EL (e.g., `#{aca001sfBean.value}`).
- **Logic methods** handle side-effectful operations — form submissions, business processing, navigation decisions.

This maps directly to the JSF lifecycle: beans are resolved and bound during the Page Render phase, and logic `execute()` methods are invoked during the Invoke Application phase.

### Regional-variant architecture

The `com.fujitsu.futurity` platform uses a **variant package pattern**: each market deployment gets its own sub-package under `web` with identically named classes but region-specific behavior. This is a classic multi-tenant strategy in Java EE applications where the deployment descriptor (or Maven profiles) selects which variant package's classes are compiled into the WAR file. Character encoding is a first-class concern scoped per variant — the Japanese variant targets Shift JIS (`MS932`), while other variants would target their market's standard encoding (UTF-8 for US, ISO-8859-1 for legacy EU).

### XML-driven configuration

Across both `com.fujitsu.futurity` and `eo.web`, all component registration is XML-driven:

| XML file | Purpose | Used by |
|---|---|---|
| `web.xml` | Servlet, filter, and listener registration | Futurity platform (`com.fujitsu.futurity`), JSF (`javax.faces.webapp`) |
| `web-full.xml` | Full-deployment profile overrides | Futurity platform, JSF |
| `faces-config.xml` | JSF managed-bean declarations | `eo.web.webview` |
| `WEBGAMEN_*.xml` | Navigation rules | `eo.web.webview` views |
| `x33S_*.xml` | Navigation rules (regional context) | `eo.web.webview` views |
| `external-refs.xml` | External wiring references | `eo.web.webview` views |

This declarative approach means the same Java classes can participate in different workflows without code changes — wiring is a matter of adding XML entries.

### The JSF request lifecycle

The `eo.web` presentation tier and the `javax.faces` framework tier cooperate through the standard six-phase JSF request lifecycle. A typical request through the system follows this flow:

1. **Encoding filter** intercepts the request and sets the character encoding.
2. **FacesServlet** receives the request and begins the JSF lifecycle.
3. **Restore View** — JSF resolves the view definition and restores (or creates) the component tree.
4. **Apply Request Values / Process Validations / Update Model** — submitted form values are validated and propagated into backing beans.
5. **Invoke Application** — the logic class's `execute()` method is called as the action handler.
6. **Render Response** — the component tree is rendered as HTML and returned to the client.

```mermaid
flowchart TD
    subgraph Client["Browser"]
        REQ["HTTP Request"]
        RESP["HTML Response"]
    end
    subgraph Servlet["Servlet Container"]
        FILTER["EncodingFilter
X33JVRequestEncodingSjisFilter"]
        FACES["FacesServlet
javax.faces.webapp"]
    end
    subgraph JSFLifecycle["JSF Lifecycle
javax.faces"]
        LV["1. Restore View"]
        AV["2-4. Apply, Validate,
Update Model"]
        IA["5. Invoke Application"]
        RR["6. Render Response"]
    end
    subgraph EoView["eo.web.webview
Application views"]
        BEAN["Backing bean
State + data"]
        LOGIC["Logic class
execute() handler"]
    end
    REQ --> FILTER
    FILTER --> FACES
    FACES --> LV
    LV --> AV
    AV --> IA
    IA --> RR
    RR --> RESP
    BEAN -.->|EL binding| REQ
    LOGIC -.->|action=| IA
```

### Test-fixture stub-as-dependency pattern

The `com.example` package follows a **stub-as-dependency** pattern. Classes like `KnownClass` are intentionally empty or near-empty, designed solely to satisfy the compiler and enable import resolution. Each fixture is consumed by at most one other unit (single-consumer coupling), making it easy to trace which test exercises which fixture.

## Dependencies and Integration

### External dependencies

| Dependency | Used by | Role |
|---|---|---|
| `javax.servlet` API | `com.fujitsu.futurity.web`, `javax.faces.webapp` | Servlet interfaces (`Filter`, `FilterChain`, `ServletContextListener`, `HttpServlet`) |
| `javax.faces` API | `eo.web.webview`, `javax.faces` | JSF lifecycle, component tree, view state, managed beans |
| JSP | `eo.web.webview` | View layer (`.jsp` files with JSF tag libraries) |
| `java.lang` (standard library) | `com.example.bugca002` | The sole dependency of the `KnownClass` fixture |

### Internal relationships

The three branches relate to each other as follows:

- **`javax.faces`** provides the runtime framework that **`eo.web.webview`** uses to implement its JSF views. The `FacesServlet` is configured in `web.xml` alongside the Futurity platform's filter and listener.
- **`com.fujitsu.futurity`** shares the same servlet container and deployment descriptors (`web.xml`, `web-full.xml`) with the JSF infrastructure. Its context listener (`X33AppContextListener`) and encoding filter (`X33JVRequestEncodingSjisFilter`) operate as co-located infrastructure alongside `FacesServlet`.
- **`com.example`** is isolated from the application tiers. It exists only as a test-fixture namespace for code-quality tooling and has no runtime dependencies on `eo`, `javax`, or `com.fujitsu.futurity`.

### Integration diagram

```mermaid
flowchart TD
    subgraph AppServer["Java EE Application Server"]
        subgraph ComNS["com namespace"]
            Example["com.example
Test fixture stubs"]
            Futurity["com.fujitsu.futurity
Futurity platform
Regional-variant architecture"]
        end
        subgraph EoNS["eo namespace"]
            WebTier["eo.web
Presentation tier
JSF-backed web UI"]
            subgraph WebViews["eo.web.webview
JSF view tier"]
                Views["View beans + logic classes
(e.g., ACA001SF)"]
            end
        end
    end
    subgraph Framework["javax.faces
JSF framework layer"]
        Servlet["javax.faces.webapp
FacesServlet"]
        Core["javax.faces.core
Lifecycle, components"]
    end
    subgraph Deployment["Deployment descriptors"]
        WebXML["web.xml / web-full.xml"]
        FacesConfig["faces-config.xml
Managed bean declarations"]
        NavRules["WEBGAMEN_*.xml
x33S_*.xml
Navigation rules"]
    end
    WebXML -->|registers| Futurity
    WebXML -->|registers| Servlet
    WebXML -->|registers| WebTier
    FacesConfig -->|declares beans| WebTier
    NavRules -->|wires navigation| Views
    Core -->|lifecycle runtime| Servlet
    Servlet -->|drives| Core
    WebTier -->|uses| Core
    Futurity -->|shared container| Servlet
```

### Namespace considerations

The codebase uses the `javax.*` namespace (Jakarta EE 8 or earlier convention). If planning to migrate to Jakarta EE 9+, the `javax.faces` packages will become `jakarta.faces`, `javax.servlet` packages will become `jakarta.servlet`, and all XML deployment descriptor class references will need updating.

## Notes for Developers

- **This codebase is largely scaffolding.** The majority of documented modules contain stub classes with no active runtime logic. Filters pass requests through unmodified, listeners have no methods, and logic classes have empty `execute()` methods. Before making changes, verify whether the intended logic has been migrated to servlet container configuration, sibling regional packages, or a different module entirely.

- **Look for "futurity" Javadoc comments.** The comment "Futurity view logic" on `ACA001SFLogic` is a deliberate indicator of forward-looking scaffolding. Similar comments across the codebase signal planned-but-not-yet-implemented features.

- **XML is the extension mechanism.** To add a view, register a listener, or wire a filter, you modify XML deployment descriptors (`web.xml`, `faces-config.xml`, `WEBGAMEN_*.xml`) rather than Java code. The wiring is declarative.

- **The `com.example` branch is not production code.** Classes here are test fixtures for code-quality tooling. Adding business logic to `KnownClass` or other stubs is unlikely to be the right direction. If a new sub-package is needed, follow the `bugcaXXX` naming convention where `XXX` corresponds to the code quality rule being tested.

- **No cross-module relationships are currently detected.** This is consistent with the stub state — when `execute()` methods are implemented, we would expect to see calls into domain services or DAO layers from the `eo.web.webview` logic classes.

- **The filter is safe to remove or deprecate.** Since `X33JVRequestEncodingSjisFilter.doFilter()` passes requests through unmodified, removing it from `web.xml` has no runtime impact unless filter ordering in the descriptor is significant. If encoding needs to be re-added, call `req.setCharacterEncoding("MS932")` before `chain.doFilter(req, res)`.

- **Bean properties need setters for form binding.** The sample `ACA001SFBean` exposes `value` only via a getter. If creating a new bean that needs form input binding (e.g., `<h:inputText value="#{bean.property}"/>`), remember to provide a corresponding setter.

- **Regional variant strategy.** If adding a new market variant to `com.fujitsu.futurity`, mirror the `x33` structure: create a sub-package under `com.fujitsu.futurity.web`, implement a character-encoding filter appropriate to the market, and register both the filter and listener in `web.xml`.

- **The listener should implement `ServletContextListener`** when lifecycle logic is added. The `contextInitialized()` method is the natural place to bootstrap variant-specific resources, and `contextDestroyed()` for cleanup on shutdown.