# Root

## Overview

This root namespace is the top-level organizational container for a Java EE web application codebase. It does not contain any source files, classes, or methods itself — its role is purely structural, grouping the codebase into three major package families, each representing a distinct architectural concern:

- **`com.fujitsu`** — The Fujitsu application root, organizing the **Futurity** multi-market web application and its locale-specific variants (notably the Japanese X33 variant with Shift-JIS encoding support).
- **`eo.web`** — The **web presentation layer** of the Futurity application, implementing a server-side MVC architecture with Struts-style XML-driven request routing and JSP-based views.
- **`javax.faces`** — The **JSF framework integration** layer, providing the `FacesServlet` front-controller and wiring the application to the JavaServer Faces component-based UI framework.

Together, these packages form the outer boundary of the application: they accept HTTP requests from browsers, route them through encoding and locale filters, dispatch them via MVC logic and JSF lifecycle phases, and return rendered HTML responses. All actual business logic, data models, and service implementations reside in downstream packages not indexed at this level.

This is a **scaffold-heavy codebase**. Multiple components across all three packages are in skeleton state — class structures are correctly defined with the right interfaces and integration points, but implementation bodies are deferred or no-op. This is common in localization work and greenfield applications where the framework is established before feature-specific logic is fully specified.

## Sub-module Guide

The root namespace organizes three independent top-level package families. Here is how each contributes to the overall system:

### `com.fujitsu` — Fujitsu Application Root

This package is the organizational umbrella for Fujitsu's Java EE applications. It contains no code at this tier — its sole purpose is grouping application code under a shared namespace prefix. The actual application lives in its child `futurity` subpackage, which provides the HTTP boundary layer for the Futurity browser-based multi-market application.

**What it handles**: Servlet filter registration, encoding normalization (particularly Shift-JIS for the Japanese X33 variant), application context initialization, and request preprocessing before data enters the core application logic.

### `eo.web` — Web Presentation Layer

This package serves as the **presentation tier** of the Futurity application. It implements a server-side MVC architecture where incoming HTTP requests are routed through XML-driven action configuration to logic classes, which populate data beans that JSP views render into HTML.

**What it handles**: Request routing, view rendering, response generation, and the bean-logic-JSP triad pattern for each feature module. It is currently in skeleton state, with `ACA001SF` serving as the reference pattern for all future webview modules.

### `javax.faces` — JSF Framework Layer

This package provides the **JavaServer Faces integration** layer. It exposes the `FacesServlet` front-controller (in the `webapp` sub-package) which bridges HTTP requests from the servlet container into the JSF six-phase request lifecycle.

**What it handles**: Serving as the single entry point for all JSF-driven requests, managing per-request `FacesContext` instances, and coordinating the six JSF lifecycle phases (Restore View, Apply Request Values, Process Validations, Update Model, Invoke Application, Render Response). The actual implementation is provided by a JSF runtime library (Mojarra or MyFaces) at deploy time.

### How the Sub-modules Relate

These three packages represent **horizontal architectural layers** rather than vertical feature groupings. They share a common concern — handling HTTP requests from browsers — but approach it from different angles:

| Aspect | `com.fujitsu` | `eo.web` | `javax.faces` |
|---|---|---|---|
| **Role** | Application namespace | MVC presentation | JSF framework |
| **Focus** | Locale, encoding, lifecycle | View, routing, beans | JSF lifecycle, components |
| **State** | Scaffold + filters | Skeleton MVC | Stub servlet |
| **Entry point** | X33 encoding filter | XML action config | FacesServlet |

In practice, a request from a browser might pass through the `com.fujitsu` X33 filter for encoding normalization, then be routed through the `eo.web` MVC layer or the `javax.faces` JSF lifecycle — depending on which feature or page is being accessed. The choice between MVC (Struts-style) and JSF appears to be per-feature, with both frameworks coexisting in the same application.

## Key Patterns and Architecture

### High-level Package Structure

The following diagram shows how the three top-level package families relate:

```mermaid
flowchart TD
    ROOT["Root namespace<br/>(no source files)"] --> FUJITSU["com.fujitsu<br/>Fujitsu app root"]
    ROOT --> EO["eo.web<br/>Web presentation layer"]
    ROOT --> JAVAX["javax.faces<br/>JSF framework layer"]
    FUJITSU --> FUTURITY["com.fujitsu.futurity<br/>Futurity web app"]
    FUTURITY --> WEB["web subpackage<br/>HTTP boundary"]
    WEB --> X33["x33 subpackage<br/>Japanese locale variant"]
    EO --> WEBVIEW["eo.web.webview<br/>MVC sub-packages"]
    WEBVIEW --> ACA["ACA* modules<br/>bean-logic-JSP triad"]
    JAVAX --> WEAPP["javax.faces.webapp<br/>FacesServlet front-controller"]
    WEAPP --> CORE["javax.faces core API<br/>FacesContext, Lifecycle"]
    X33 --> FILTER["X33 encoding filter<br/>Shift-JIS support"]
    WEBVIEW -.->|delegates to| SERVICES["Application services<br/>(future)"]
    FILTER -.->|dispatches to| SERVLETS["Target servlets<br/>(downstream)"]
```

### Request Processing Architecture

At the request level, the three packages each provide a distinct gateway pattern. Here is how they interact in a typical request flow:

```mermaid
sequenceDiagram
    participant Browser as "Browser / Client"
    participant Container as "Servlet Container"
    participant Filter as "X33 Filter<br/>com.fujitsu"
    participant MVC as "eo.web Logic<br/>Struts-style routing"
    participant JSF as "FacesServlet<br/>javax.faces"
    participant Bean as "Data Bean<br/>eo.web"
    participant View as "JSP View<br/>eo.web"
    Browser->>Container: HTTP request
    Container->>Filter: doFilter
    Filter->>MVC: chain.doFilter (encoded)
    alt MVC Route
        MVC->>Bean: execute() populates
        Bean->>View: request scope
        View-->>Filter: HTML response
        Filter-->>Browser: respond
    else JSF Route
        JSF->>JSF: 6-phase lifecycle
        JSF-->>Filter: rendered response
        Filter-->>Browser: respond
    end
```

A request may take the MVC path (XML-action-configured `*Logic` class) or the JSF path (`FacesServlet`-managed lifecycle), depending on which feature or page is being accessed. The X33 encoding filter is common to both paths, ensuring character encoding is normalized before the request enters either framework.

### Architectural Layering

```mermaid
flowchart TD
    Client[Browser / Client] --> Filters["Encoding & Locale Filters<br/>com.fujitsu"]
    Filters --> Dispatcher["Request Dispatcher<br/>MVC + JSF gateways"]
    Dispatcher --> Logic["Business Logic<br/>(*Logic, Managed Beans)"]
    Logic --> Services["Application Services<br/>(downstream, not indexed)"]
    Services --> Data["Data Layer<br/>(database, not indexed)"]
```

The request flows from the browser through an encoding-aware filter at the `com.fujitsu` boundary, then branches into either the `eo.web` MVC layer or the `javax.faces` JSF layer, before delegating downward into business logic and data access (which reside in downstream packages not indexed at this level).

### Design Patterns in Use

**Front Controller Pattern** — Both `javax.faces.webapp.FacesServlet` and the Struts-style XML action configuration in `eo.web` implement the front controller pattern, centralizing request dispatch logic. This ensures consistent request handling, state management, and error handling across the application.

**MVC (Model-View-Controller)** — The `eo.web.webview` package follows a classic Struts 1.x MVC pattern: XML-driven action configuration routes requests to `*Logic` classes (Controller), which populate `*Bean` data objects (Model) that JSP views (View) render into HTML. This triad is the repeating structural unit across all webview modules.

**Filter Chain Pattern** — The `com.fujitsu.futurity` X33 filter uses the standard Java EE `javax.servlet.Filter` interface, sitting in the servlet filter chain to normalize request encoding (Shift-JIS) before dispatching to downstream servlets. The filter's `init()` method is the natural extension point for reading encoding parameters.

**Delegation to Downstream** — Across all three packages, the pattern is consistent: these packages handle only the boundary concerns (encoding, routing, view rendering). Actual business logic and data access are delegated to packages not indexed at this level, suggesting a clean dependency inversion where the presentation layer depends on — but does not contain — the domain logic.

## Dependencies and Integration

### External Framework Dependencies

| Dependency | Used By | Role |
|---|---|---|
| `javax.servlet.*` | `com.fujitsu`, `javax.faces` | Servlet API — filter interface, request/response types, listener interface |
| **Struts 1.x** (inferred) | `eo.web` | XML action configuration, `*Logic` class lifecycle |
| **JSF 2.x** (spec API) | `javax.faces` | Component-based UI framework, six-phase lifecycle |
| **JSP / JSTL** | `eo.web` | Server-side view templates rendered by the MVC logic layer |
| **JSF provider** (Mojarra / MyFaces) | `javax.faces` at runtime | Production implementation of `FacesServlet` and JSF core |

### Internal Integration Points

The three packages integrate with the rest of the application (downstream packages not indexed at this level) through these interfaces:

1. **`com.fujitsu`** — The X33 filter delegates to downstream target servlets and controllers for actual request processing. The `X33AppContextListener`, once implemented, would initialize locale-specific resources at startup (e.g., registering locale-aware `NumberFormat` or `DateFormat` instances).

2. **`eo.web`** — The `*Logic` classes are intended to delegate to application services for business processing and data access. Currently they are stubs with empty `execute()` methods. New features should follow the `ACA001SF` reference pattern: add logic first, then wire the XML action config and JSP views.

3. **`javax.faces`** — The `FacesServlet` delegates into the JSF managed bean layer during the Invoke Application lifecycle phase. The actual managed bean implementations would reside in downstream application packages, not within the spec API classes.

### Configuration

| Configuration | Package | Mechanism |
|---|---|---|
| Filter registration | `com.fujitsu` | `web-full.xml` servlet filter mapping |
| Action routing | `eo.web` | `WEBGAMEN_*.xml` declarative XML configuration |
| JSF servlet mapping | `javax.faces` | `web-full.xml` servlet and servlet-mapping |
| JSF lifecycle config | `javax.faces` | `faces-config.xml` (application-scoped) |

## Notes for Developers

- **No source code at the root level** — The root namespace is purely organizational. All actual code lives in the `com.fujitsu`, `eo.web`, and `javax.faces` package trees.

- **Widespread scaffolding** — This is a key characteristic of the codebase. Multiple components across all three packages are in scaffold or skeleton state:
  - `X33JVRequestEncodingSjisFilter` forwards all requests unmodified (no encoding transformation implemented yet).
  - `X33AppContextListener` has no lifecycle methods implemented.
  - `ACA001SFLogic.execute()` is an empty stub.
  - `FacesServlet` is an empty class (production implementation comes from the JSF provider JAR).
  - Data beans define only getters, not setters (read-only direction).

- **Two concurrent presentation frameworks** — The application uses both Struts-style MVC (`eo.web`) and JavaServer Faces (`javax.faces`). This suggests either a migration in progress, coexistence of legacy and modern UI features, or locale-specific UI variants (e.g., the X33 Japanese variant may favor one framework over the other).

- **Localization is a first-class concern** — The X33 variant with Shift-JIS encoding support appears in the `com.fujitsu` layer. If you are working on other market variants, check for related encoding filters or locale configurations in sibling packages under `com.fujitsu`.

- **Feature extension model** — New features in `eo.web` should follow the `ACA001SF` pattern: create a new `ACA002SF` (or similar) sub-package under `eo.web.webview` with the `*Bean` / `*Logic` / JSP triad, then add an entry to the XML action configuration file. New JSF pages follow the standard JSF convention of placing `.xhtml` views under `WEB-INF/views/` (or similar) and wiring managed beans through `faces-config.xml`.

- **No business logic or data access** — This layer contains no data model classes, DTOs, or entity types. It is purely a request-processing and lifecycle infrastructure layer. Business logic and data access reside in downstream packages.

- **Thread safety by design** — Both `FacesServlet` and the Struts-style logic classes are stateless at the instance level. All per-request state lives in `FacesContext` (JSF) or request scope (MVC beans), ensuring thread safety without synchronization.

- **Configuration changes require reload** — Changes to XML action routing (in `eo.web`) and servlet filter mapping (in `com.fujitsu`) typically require a configuration reload or application restart. The XML-driven approach allows hot routing changes but is sensitive to deployment timing.