# Root

## Overview

The root package represents the top-level organizational boundary of the application. It has no source files or classes directly defined at this level. Instead, it serves as a namespace container for three distinct sub-modules, each occupying a different layer of the system:

- **`javax`** — The JSF framework integration layer, providing the servlet-to-faces bridge (`FacesServlet`) and deployment descriptor wiring.
- **`eo`** — The JSF presentation layer, where user-facing web pages are rendered through backing beans, logic controllers, and JSP views.
- **`com`** — The application and infrastructure layer, encompassing the Fujitsu Futurity application skeleton (X33 variant) and the `com.example` test-fixture namespace.

Together, these modules form a **Java EE web application** organized around the JavaServer Faces (JSF) MVC pattern. The architecture is a structural scaffold: servlet filters, context listeners, and a front-controller servlet are declared and wired through deployment descriptors, but their implementations are empty or no-op stubs. Business logic, controllers, and views have been partially defined (e.g., the ACA001 view flow) but remain unimplemented. This appears to be early-stage scaffolding — the plumbing is in place, the pipes are not yet carrying signal.

## Sub-module Guide

The root namespace contains three child modules, each representing a different concern:

### `javax` — JSF Framework Integration

The `javax` package is the organizational umbrella for the JavaServer Faces framework integration. Its sole child module is `javax.faces`, which groups the JSF servlet infrastructure (`javax.faces.webapp`). This is the **entry point** into the JSF request lifecycle — the `FacesServlet` class intercepts HTTP requests and delegates them into the six-phase JSF processing pipeline.

Currently, `FacesServlet` is an **empty stub** — declared and registered in both `web.xml` and `web-full.xml`, but containing no implementation. In a production system, this would bootstrap the JSF lifecycle (restore view, apply request values, process validations, update model values, invoke application, render response) for every matching request. The presence of dual deployment descriptors suggests the project targets both standard and full Java EE profiles.

This module does not implement application behavior; it provides the **framework plumbing** that other modules depend on. It sits at the lowest layer of the stack.

### `eo` — JSF Presentation Layer

The `eo` package contains the **presentation tier** — the code that renders user-facing web pages. Its only child module is `eo.web`, which is built on JSF and follows the classic MVC pattern:

- **Backing beans** (e.g., `ACA001SFBean`) — hold state and expose properties to the view layer.
- **Logic controllers** (e.g., `ACA001SFLogic`) — provide the controller hook where view-side business logic is implemented.
- **JSP views** (e.g., `FULL_ACA001010PJP.jsp`) — bind to bean properties for rendering.

The presentation layer is driven entirely by **XML-based wiring** (`faces-config.xml`, `WEBGAMEN*.xml`, `x33S*.xml`, `external-refs.xml`) rather than annotations. This allows configuration to be adjusted without source code changes, but makes refactoring and renaming more error-prone.

The `eo` module is a **leaf** in the package hierarchy — it does not import or reference other internal modules. It depends solely on the JSF framework and the servlet API. Its data model is intentionally thin, with only a single string property exposed per bean, consistent with best practices that delegate domain logic to service layers outside this tree.

### `com` — Application & Infrastructure

The `com` package is the most diverse, containing two functionally distinct sub-modules:

**`com.fujitsu.futurity`** — The Fujitsu Futurity application, a Japan-focused Java EE web application (X33 variant). Its primary responsibility is providing the **web-tier infrastructure layer**: request encoding filters and lifecycle listeners. The module contains two servlet-tier stubs:

| Component | Purpose |
|---|---|
| `X33JVRequestEncodingSjisFilter` | Sets character encoding (MS932 / Shift JIS) on incoming requests |
| `X33AppContextListener` | Provides startup and shutdown hooks for application-scoped resources |

Both components are wired through `web.xml` and `web-full.xml` but have no-op implementations. The X33 module has no internal Java dependencies — it depends only on the standard Servlet API.

**`com.example`** — A regression-test fixture namespace. It contains minimal stub classes (e.g., `KnownClass` in the `bugca002` sub-module) designed to be imported by JSP view files to exercise JSP compilation and import resolution. These are intentionally empty — no fields, no-op methods — and exist purely to test the build tooling pipeline, not to provide application behavior.

### How the Sub-modules Relate

The three child modules form a **layered web application architecture**:

```
javax.faces ──> eo.web ──> com.fujitsu.futurity
   (framework)    (presentation)    (infrastructure)
                          ^
                          |
                  com.example (test fixtures)
```

- **`javax.faces`** provides the framework entry point (`FacesServlet`) that all HTTP requests flow through.
- **`eo.web`** sits on top of this framework, using the JSF infrastructure to render user-facing pages. Its backing beans and logic controllers are the concrete application of the framework.
- **`com.fujitsu.futurity`** (X33) provides the servlet-tier infrastructure (encoding filter, context listener) that operates at a lower level — between the raw servlet container and the JSF layer. It handles pre-request transformations (character encoding) and application lifecycle.
- **`com.example`** is orthogonal to the application stack — it exists purely for regression testing, providing stub classes that JSP views import to exercise the build tooling.

The `eo.web` presentation layer and the `javax.faces` framework layer share a common dependency: **JSF**. The `eo.web` module uses JSF beans and JSP views, while `javax.faces` provides the servlet integration point. In a fully implemented application, requests would flow from the servlet container through `FacesServlet`, into the JSF lifecycle, and then through the backing beans in `eo.web`.

The `com.fujitsu.futurity` X33 module operates at the servlet tier, below JSF. Its encoding filter would execute before JSF processes a request, ensuring that the request character encoding is set correctly. Its lifecycle listener would fire once at deployment, independent of request processing.

## Key Patterns and Architecture

### Unified Layered Architecture

All three sub-modules contribute to a **single Java EE web application** architecture. The layers are:

```mermaid
flowchart TD
    subgraph JAVAX["javax.faces
JSF Framework Layer"]
        WEBAPP["FacesServlet
Front-controller"]
    end
    subgraph EO["eo.web
JSF Presentation Layer"]
        WEBVIEW["webview
Beans + logic + views"]
        ACA001["ACA001SF
View flow"]
    end
    subgraph COM["com
Application & Infrastructure"]
        X33["X33 Sub-module
Filter + Listener"]
    end
    JSP["Browser / JSP Views"] --> SERVLET
    SERVLET["Servlet Container"] --> WEBAPP
    WEBAPP --> LIFECYCLE["JSF Lifecycle
6 phases"]
    LIFECYCLE --> WEBVIEW
    WEBVIEW --> ACA001
    X33 -->|pre-processes| SERVLET
```

This diagram shows the high-level architecture: the `javax` module provides the framework entry point, `eo` provides the presentation logic, and `com.fujitsu.futurity` provides servlet-tier infrastructure. Requests flow from the browser through the servlet container, into the JSF lifecycle, and down to the presentation beans and views.

### Common Architectural Patterns

**1. Stub Scaffolding**

All three sub-modules follow the same pattern: infrastructure hooks built ahead of business logic. `FacesServlet`, `X33JVRequestEncodingSjisFilter`, `X33AppContextListener`, and `ACA001SFLogic.execute()` are all declared and wired but contain empty or no-op bodies. This is consistent across the entire codebase and suggests a deliberate approach: build the plumbing first, then fill in the pipes.

**2. XML-Driven Configuration**

Both `javax.faces` (FacesServlet registration) and `eo.web` (bean and logic wiring) rely exclusively on XML deployment descriptors rather than annotations. This creates a decoupled, profile-aware configuration strategy where wiring can vary across deployment targets without source code changes. However, it also means refactoring requires auditing all XML files — not just source code references.

**3. Lifecycle vs. Request Separation**

The `com.fujitsu.futurity` X33 module cleanly separates concerns: `X33AppContextListener` operates at application deployment time (singleton), while `X33JVRequestEncodingSjisFilter` operates per HTTP request (repeated). This is the standard Java EE servlet pattern and provides a clear mental model for where new infrastructure components should fit.

**4. Thin Presentation Data Model**

The `eo.web` module exposes minimal state at the presentation layer — `ACA001SFBean` provides only a single read-only string property. This is consistent with JSF best practices where the web tier should be thin and delegate to service layers, which may reside in packages not yet indexed in this documentation.

**5. Dual Source Trees**

`ACA001SFLogic` exists in two source trees (`full-fixture-codebase` and `xml-unresolved-fqn`), suggesting a dual-tree build or documentation pipeline. This pattern may extend to other modules as the codebase matures. Developers working in this area should be aware of which tree they are editing and whether changes need propagation.

### Request Flow (Fully Implemented)

In a fully implemented version of this application, a typical request would follow this path:

1. **Browser sends HTTP request** targeting a JSF-managed URL (e.g., `*.jsf`).
2. **Servlet container** reads `web.xml` and routes the request to `FacesServlet`.
3. **X33 encoding filter** (`X33JVRequestEncodingSjisFilter`) pre-processes the request, setting the character encoding to MS932 (Shift JIS) if not already specified.
4. **JSF lifecycle** begins: restore view, apply request values, process validations, update model values, invoke application, render response.
5. **`ACA001SFLogic.execute()`** is invoked as the controller entry point within the JSF lifecycle.
6. **`ACA001SFBean`** provides data to the JSP view.
7. **JSP view** (`FULL_ACA001010PJP.jsp`) renders HTML bound to bean properties.
8. **HTML response** is returned to the browser.

## Dependencies and Integration

### Internal Dependencies

The root package has no direct child modules of its own — all work is delegated to the three sub-packages:

| Parent Module | Child Module | Relationship |
|---|---|---|
| `javax` | `javax.faces` | Organizational umbrella for JSF framework integration |
| `javax.faces` | `javax.faces.webapp` | Contains the `FacesServlet` front-controller |
| `eo` | `eo.web` | JSF presentation layer (backing beans, views, logic) |
| `eo.web` | `eo.web.webview` | Webview layer with JSF MVC components |
| `eo.web.webview` | `ACA001SF` | Single view flow: bean, logic, JSP |
| `com` | `com.fujitsu` | Packaging root for Fujitsu Futurity |
| `com.fujitsu` | `com.fujitsu.futurity` | Futurity application container |
| `com.fujitsu.futurity` | `com.fujitsu.futurity.web` | Web-tier infrastructure |
| `com.fujitsu.futurity.web` | `X33` | X33 variant: filter + listener |
| `com` | `com.example` | Regression test fixtures |
| `com.example` | `bugca002` | Stub class for JSP import testing |

### External Dependencies

| Dependency | Used By | Purpose |
|---|---|---|
| `javax.servlet` | FacesServlet, X33 filter/listener | Servlet API for HTTP request/response handling |
| `javax.faces` | eo.web backing beans and logic | JSF framework for MVC wiring and lifecycle |
| `java.lang` | All modules | Default Java runtime (implicit) |

The project references `javax.servlet` (Java EE / Servlet 3.x) package naming. Developers should confirm whether the build has migrated to `jakarta.servlet` (Jakarta EE / Servlet 5.x+), as this would require updating all imports before implementation work.

### Deployment Integration

All three sub-modules share a common deployment strategy:

- **Dual deployment descriptors:** Both `web.xml` (standard) and `web-full.xml` (full Java EE profile) are used across all modules. Any configuration or implementation changes must be reflected in both files.
- **XML-based wiring:** No module uses annotation-based discovery (e.g., `@WebServlet`, `@ManagedBean`). All components are explicitly declared in XML.

## Notes for Developers

- **Everything is a stub.** `FacesServlet`, `X33JVRequestEncodingSjisFilter`, `X33AppContextListener`, and `ACA001SFLogic.execute()` are all declared but contain no executable logic. Adding implementation is safe — there is no existing behavior to break.

- **Character encoding is a priority area.** If the X33 application handles Japanese content, implementing `X33JVRequestEncodingSjisFilter` is likely one of the first practical tasks. Check `req.getCharacterEncoding() == null` before setting the encoding to avoid overriding explicit client headers.

- **Servlet API version matters.** The code references `javax.servlet` (Java EE / Servlet 3.x). Confirm whether the project has migrated to `jakarta.servlet` (Jakarta EE / Servlet 5.x+) before implementing any interface methods.

- **Coordinate across deployment profiles.** Changes to `web.xml` should be mirrored in `web-full.xml`. Divergence between these profiles is a common source of environment-specific bugs.

- **XML configuration density.** The `eo.web.webview` module references the same bean and logic classes across six XML files. Before refactoring or renaming, audit all configuration files to avoid broken runtime references.

- **Dual source trees.** `ACA001SFLogic` exists in both `full-fixture-codebase` and `xml-unresolved-fqn`. One appears canonical; changes may need to be propagated to the other. Be aware of which tree you are editing.

- **Stub classes are intentional.** Classes in `com.example` (e.g., `KnownClass`) are deliberately sparse by design. Do not assume missing fields, methods, or logic are oversights — they are intentional test fixtures. If you need a non-trivial class for testing, create it in a new module rather than modifying an existing stub.

- **Indexing caveat.** Static analysis of the `com.fujitsu` and `javax.faces` root modules reports zero indexed classes and methods because the stub classes implement interfaces with empty bodies. When implementation is added, the code index should be refreshed to capture new symbols.

- **No source files directly under root.** The root package itself contains no source files, classes, or dependencies. All operational content lives in the three sub-packages (`javax`, `eo`, `com`). The root serves purely as an organizational boundary.