# Root

## Overview

The root package area represents the top-level namespace of a Java EE web application project. This codebase appears to be a scaffolded enterprise system -- likely named **Futurity** -- built for Japanese-language users, structured across three major technical domains:

- **`com.fujitsu.futurity`** -- The Fujitsu-branded enterprise application, organized around a Java EE servlet stack with a stub-first, scaffolded development approach.
- **`eo.web`** -- The web presentation layer, using Struts 1.x MVC to render HTML views from JSP templates.
- **`javax.faces`** -- The JavaServer Faces (JSF) API surface, providing the servlet bridge (`javax.faces.webapp`) that connects HTTP requests to the JSF request lifecycle.

All three domains share a common characteristic: they are currently in a **greenfield, scaffolded state**. The structural wiring -- deployment descriptors, XML configuration files, class stubs, and JSP references -- is in place, but operational business logic has not yet been implemented. This pattern suggests a deliberate design process where integration touchpoints, component contracts, and request routing were defined before implementation began.

The application targets Japanese-language users, with character encoding (Shift-JIS / CP932) appearing as a recurring requirement across multiple sub-modules. This is a legacy Japanese enterprise system that relies on standard Java EE conventions -- no framework-specific annotations are used -- and everything is wired through XML-based deployment configuration (`web-full.xml`).

## Sub-module Guide

The root area is composed of three independent but complementary sub-packages, each owning a distinct layer of the application:

### com -- Fujitsu Enterprise Application

The `com.fujitsu.futurity` package is the application's umbrella -- it owns the HTTP surface area and the integration touchpoints that the rest of the system will interact with. Within it:

- **`com.fujitsu.futurity.web`** provides the servlet-tier infrastructure (filter chain, context lifecycle, request dispatch). This is where all HTTP traffic enters the application.
- **`com.fujitsu.futurity.web.x33`** is the first concrete feature area, defining a Shift-JIS encoding filter and a servlet context listener -- both currently no-op stubs, registered in `web-full.xml`.

Futurity is the top-level container. Its `web` package defines the external contract (how requests arrive, how encoding is handled, what resources are initialized at startup).

### eo -- Presentation Layer (Struts 1.x)

The `eo.web` package owns the view and request-dispatch responsibilities. It uses Struts 1.x MVC:

- **`eo.web.webview`** implements the full MVC triad (Model beans, Controller logic classes, JSP views).
- **`eo.web.webview.ACA001SF`** is the reference implementation -- a template showing how each view page should be structured: an XML action mapping routes to a `*Logic` controller, which populates a `*Bean` data carrier, which a JSP page renders as HTML.

The `eo.web` module is the "view" layer -- it receives requests (presumably from downstream of the Futurity web layer), runs controller logic, and produces HTML. It is self-contained, with dependencies only on the Struts framework and JSP technology.

### javax -- JSF Framework Integration

The `javax.faces` package area provides the JSF API surface. Its only concrete child in this codebase is:

- **`javax.faces.webapp`** -- Exposes `FacesServlet`, the front-controller servlet that every JSF application registers in `web.xml`. It bridges HTTP requests to the JSF six-phase lifecycle (RestoreView through RenderResponse).

This sub-package is a minimal stub in this codebase; the real implementation comes from an external JSF runtime library (Mojarra or MyClasses). It exists as structural scaffolding -- the wire-up point that tells the servlet container "these URLs go through the JSF lifecycle."

### How They Relate

These three sub-packages operate at different layers and serve different purposes within the same application:

| Layer | Sub-package | Role | Framework |
|-------|-------------|------|-----------|
| Integration entry point | `com.fujitsu.futurity.web` | HTTP surface, encoding, lifecycle | Java EE Servlets |
| View rendering | `eo.web.webview` | MVC controllers, beans, JSP views | Struts 1.x |
| Framework bridge | `javax.faces.webapp` | Servlet-to-lifecycle bridge | JavaServer Faces |

The relationship is **layered and complementary** rather than directly coupled:

- `com.fujitsu.futurity.web` defines the raw HTTP contract -- how requests enter, how encoding is set, what gets initialized at startup. It is the outermost wrapper.
- `eo.web.webview` operates as the view/rendering layer downstream of that contract. It receives requests (via Struts action dispatch), runs controller logic, and produces JSP-based HTML output.
- `javax.faces.webapp` provides an alternative (or parallel) JSF-based entry point. It does not directly interact with the other two sub-packages -- it is its own self-contained servlet bridge.

No cross-module relationships were detected between these sub-packages in the codebase index. Each operates independently, wired through the shared deployment descriptor (`web-full.xml`) rather than through Java-level imports or references. This is consistent with a scaffolded architecture where the deployment configuration binds the layers together before implementation code exists.

## Key Patterns and Architecture

### Shared Development Philosophy: Stub-First Scaffolding

All three sub-packages share a common development pattern: **structural scaffolding precedes implementation**. Classes exist as method stubs, beans expose minimal fields, and the wiring (XML mappings, deployment descriptors, JSP references) is in place while business logic is empty. This pattern is deliberate -- it identifies integration touchpoints and contracts before implementation, allowing frontend, integration, and business logic work to proceed in parallel.

### XML-Driven Configuration

Every sub-module relies on XML configuration as the canonical wire-up mechanism:

- **`web-full.xml`** registers servlets, filters, and listeners for `com.fujitsu.futurity.web` and `javax.faces.webapp`.
- **Struts action XML files** (e.g., `WEBGAMEN_FULL_ACA001.xml`) route requests to `*Logic` controllers and instantiate `*Bean` models for `eo.web.webview`.

There are no framework-specific annotations. Everything is container-managed and XML-wired, making the configuration the single point of truth for component relationships.

### Three MVC Architectures, One Project

The codebase employs three distinct MVC or request-handling architectures simultaneously:

1. **Java EE Servlet/Filter architecture** (`com.fujitsu.futurity.web`) -- The raw HTTP entry point with container-managed filters and listeners.
2. **Struts 1.x MVC** (`eo.web.webview`) -- A classic action-bean-view triad for rendering JSP-based HTML.
3. **JSF component-based MVC** (`javax.faces.webapp`) -- A six-phase lifecycle framework for building component-based user interfaces.

This suggests the application is either in an evaluation/migration phase (adopting one framework while retaining others) or is designed to support multiple view technologies within the same deployment.

### Request Encoding for Japanese Locales

A cross-cutting concern across multiple sub-modules is Japanese character encoding. The `X33JVRequestEncodingSjisFilter` in `com.fujitsu.futurity.web.x33` intercepts incoming requests to set Shift-JIS (CP932) encoding before downstream consumers read request data. Similarly, the JSP file `ShiftJis001.jsp` in `eo.web.webview` indicates at least one view page serves Japanese locale content. If the encoding filter is not implemented and ordered correctly in the filter chain, Japanese input will be garbled -- making filter ordering in `web-full.xml` a critical configuration concern.

### Module Interactions

```mermaid
flowchart TD
    ROOT["Root
Package Descriptor"]

    subgraph FUT["Fujitsu Application"]
        SRC["com.fujitsu.futurity
Enterprise App"]
        WEB["com.fujitsu.futurity.web
HTTP Surface Area"]
        X33["com.fujitsu.futurity.web.x33
X33 Feature Area"]
        FILTER["X33JVRequestEncodingSjisFilter
Shift-JIS encoding"]
        LST["X33AppContextListener
Lifecycle management"]
        DESC["web-full.xml
Deployment Descriptor"]
    end

    subgraph EO["Presentation Layer"]
        EOWEB["eo.web
Web Presentation"]
        WV["eo.web.webview
Struts 1.x MVC"]
        ACAA["eo.web.webview.ACA001SF
View Page Scaffold"]
        LOGIC["*Logic classes
Controllers"]
        BEAN["*Bean classes
Data models"]
        JSP["JSP View Pages"]
    end

    subgraph JSF["JSF Framework Integration"]
        JAVAX["javax.faces
JSF API Surface"]
        WEAPP["javax.faces.webapp
Servlet Bridge"]
        FACES_SERV["FacesServlet
Request Entry Point"]
    end

    ROOT --> FUT
    ROOT --> EO
    ROOT --> JSF

    SRC --> WEB
    WEB --> X33
    X33 --> FILTER
    X33 --> LST
    WEB --> DESC
    X33 --> DESC
    DESC --> WEB

    EOWEB --> WV
    WV --> ACAA
    ACAA --> LOGIC
    ACAA --> BEAN
    BEAN --> JSP
    LOGIC --> BEAN

    JAVAX --> WEAPP
    WEAPP --> FACES_SERV
```

## Dependencies and Integration

### External Framework Dependencies

| Sub-package | Primary Dependencies |
|-------------|---------------------|
| `com.fujitsu.futurity.web` | `javax.servlet.Filter`, `javax.servlet.ServletContextListener`, `web-full.xml` |
| `eo.web.webview` | Struts 1.x framework, JSP view technology |
| `javax.faces.webapp` | `javax.servlet` (Servlet API), `javax.faces` (JSF API), external JSF runtime (Mojarra/MyFaces) |

### Cross-Module Integration

No direct Java-level imports or references were detected between the three sub-packages. Integration is achieved through the shared deployment descriptor (`web-full.xml`), which wires together servlets, filters, and listeners from all three areas into a single web application deployment. This means:

- Components from different sub-packages communicate through the **servlet container's request dispatch** and **`ServletContext`** shared state, not through direct method calls.
- The filter chain defined in `web-full.xml` determines the order in which components from different sub-packages execute for a given request.
- Changes to one sub-package (e.g., renaming a filter class in `com.fujitsu.futurity.web`) require updating the XML configuration but do not propagate as compile-time errors to other sub-packages.

### Integration with the Broader System (Planned)

When fully implemented:

- The **Futurity web layer** will delegate through its filter chain to downstream controllers, servlets, or Struts actions.
- The **Struts presentation layer** (`eo.web`) will be populated with real business logic in its `*Logic` classes, integrating with backend services and data access layers.
- The **JSF bridge** (`javax.faces.webapp`) will connect to a full JSF runtime, enabling component-based UI development alongside or as an evolution of the Struts-based views.

## Notes for Developers

1. **Everything is a scaffold.** None of the three sub-packages contain production-ready business logic. Stub classes, empty `execute()` methods, and minimal beans are intentional -- not bugs. The structural wiring (XML mappings, deployment descriptors, JSP references) is the foundation; implementation code is yet to come.

2. **XML configuration is the single point of truth.** Every component relationship -- filter ordering, servlet mappings, Struts action dispatch -- is defined in XML files. Changes to class names, method signatures, or bean references require updating the corresponding XML. The XML is the architectural contract.

3. **Thread safety is critical.** All servlet-tier components (filters, listeners, Struts action classes) are singleton instances managed by the container. Any state added in future implementation must be read-only after initialization or protected by synchronization.

4. **Filter ordering matters for Japanese encoding.** The `X33JVRequestEncodingSjisFilter` must appear early in the `<filter-mapping>` order in `web-full.xml`, before any component that reads request parameters. If it does not, Japanese input will be garbled.

5. **Multiple MVC frameworks coexist.** The application uses Java EE Servlets, Struts 1.x, and JSF simultaneously. When working on a feature, determine which framework's component handles the request path. The Struts MVC triad (Bean-Logic-JSP) is the most concrete implementation pattern so far and serves as the template for future view pages.

6. **No other module depends on these packages.** The sub-packages operate in isolation -- no other Java packages import or reference classes from them. This limits the blast radius of changes but also means these packages are the starting point for any external integration.

7. **Character encoding verification.** When adding new view pages or filters for international markets, verify whether Shift-JIS (`"SJIS"` / `"CP932"`) or UTF-8 is appropriate. Modern applications typically use UTF-8, but legacy Japanese enterprise systems often require Shift-JIS for form data compatibility with existing systems.

8. **The deployment descriptor binds everything.** `web-full.xml` is the canonical configuration file that ties together the servlet container, the JSF lifecycle, and the Struts action dispatcher. Understanding its contents is essential for understanding how requests flow through the application.