# Root

## Overview

The root of this codebase is a **Java EE web application platform** originally built for the Fujitsu Futurity / X33 product line, targeting Japanese-language enterprise use cases. It represents a traditional mid-tier web application architecture characteristic of the mid-to-late 2000s, built around the Java Servlet API, JavaServer Faces (JSF), and a custom MVC framework.

At the highest level, the codebase is organized into three top-level namespaces, each representing a distinct layer of the web stack:

- **`com`** — The Fujitsu Futurity X33 infrastructure, providing servlet-level lifecycle hooks and request preprocessing.
- **`eo`** — The EO web application's MVC presentation layer, delivering view logic through a Bean-Logic-XML-JSP pattern.
- **`javax`** — The JavaServer Faces (JSF) framework components, providing the standard JSF request processing lifecycle.

These namespaces work together to form a complete web request pipeline: the `com` layer intercepts and preprocesses HTTP traffic at the servlet container level, `javax` (JSF) manages the structured request lifecycle and component tree, and `eo` delivers the actual business-facing views and presentation logic.

This appears to be an enterprise application designed for the Japanese market (evidenced by Shift JIS encoding filters and `X33JV` naming), built with explicit XML configuration rather than annotation-based discovery. The overall architecture follows Java EE best practices for the era, with a layered separation between infrastructure (servlet lifecycle), framework (JSF), and application (MVC webviews).

## Sub-module Guide

### com — Fujitsu Futurity X33 Infrastructure

The `com` package namespace (specifically `com.fujitsu.futurity.web.x33`) provides the outermost entry point of the X33 web layer. It contains two complementary components:

- **`X33AppContextListener`** — A `ServletContextListener` stub intended for one-time application startup and shutdown tasks (configuration loading, bean registration, shared state initialization). Currently an empty class body with no methods.
- **`X33JVRequestEncodingSjisFilter`** — A `javax.servlet.Filter` designed to set character encoding to Shift JIS (SJIS) on incoming requests before they reach target servlets. Structurally complete but functionally a no-op — its `doFilter()` method immediately delegates to the chain without modifying the request.

Both components are registered (or intended to be registered) via `web-full.xml`, the centralized deployment descriptor. The `X33JV` prefix indicates Japanese build scoping, suggesting this filter may be a relic of a Japanese-specific deployment no longer actively maintained.

### eo — EO Web Application (MVC Presentation Layer)

The `eo.web` package is the presentation layer of the EO application. It sits at the intersection of business logic and the browser, translating internal domain data into HTML served to end users.

The `eo.web.webview` subpackage implements a classic MVC pattern where each web feature is a standalone sub-package containing four artifacts:

| Artifact | Role |
|----------|------|
| **Bean** | A minimal POJO carrying view-scoped data (e.g., `ACA001SFBean` with a `String value`). |
| **Logic** | The controller class (`ACA001SFLogic`) with an `execute()` method that prepares data before rendering. |
| **XML Config** | Declarative wiring file (`WEBGAMEN_FULL_ACA001.xml`) mapping URL patterns to the controller. |
| **JSP View** | The HTML template (`FULL_ACA001010PJP.jsp`) rendering the response using JSP EL. |

The documented `ACA001SF` webview serves as the representative example. Its `execute()` method is currently empty, which may indicate a stub awaiting business logic, a no-op for a static display view, or a template base class for extension.

### javax — JavaServer Faces Framework

The `javax` package namespace provides the JavaServer Faces (JSF) specification API layer. Its `javax.faces.webapp` subpackage exposes `FacesServlet`, the front controller servlet that dispatches every JSF-managed request through the standardized six-phase JSF request processing lifecycle:

1. **Restore View** — Rebuilds or creates the component tree.
2. **Apply Request Values** — Reads submitted values from UI components.
3. **Process Validation** — Validates converted values.
4. **Update Model Values** — Copies validated data into backing beans.
5. **Invoke Application** — Handles application logic (button actions, navigation).
6. **Render Response** — Renders the component tree as HTML output.

`FacesServlet` is registered in the deployment descriptor and mapped to URL patterns (typically `*.jsf` or `/faces/*`). The indexed file contains only the class declaration — the actual lifecycle logic is implemented by the JSF reference implementation (e.g., Mojarra or MyFaces) and is not present in this source fixture.

### How They Relate

These three namespaces form a **layered web request pipeline** operating at different levels of abstraction:

- **`com`** operates at the **servlet container** level. Its filter sits at the very front of the request pipeline, before any application framework processes the request. It operates once at startup (listener) and on every request (filter), but currently performs no actionable logic.
- **`javax`** operates at the **framework** level. It provides the structured JSF lifecycle that coordinates view management, validation, and rendering. It serves as the bridge between raw HTTP and application-level MVC views.
- **`eo`** operates at the **application** level. Its webviews contain the business-facing presentation logic. Each webview is self-contained and independent, with no cross-view communication.

The request typically flows through all three layers: the X33 filter preprocesses the raw HTTP request (potentially setting encoding), JSF's `FacesServlet` manages the request lifecycle and component tree, and the EO MVC webview delivers the specific business view.

The `com` and `javax` layers are framework-level infrastructure, while `eo` is the application-specific logic built on top of that infrastructure.

## Key Patterns and Architecture

### Servlet Lifecycle Pattern

All three namespaces adhere to the standard Java Servlet API lifecycle, which provides container-managed hooks for application-scoped and request-scoped operations:

- **`ServletContextListener`** — Used by the `listener` sub-package for one-time application start and stop.
- **`javax.servlet.Filter`** — Used by the `filter` sub-package for per-request interception.
- **`FacesServlet`** — Used by the `javax.faces.webapp` sub-package as the front controller for all JSF requests.

### Front Controller Pattern

`FacesServlet` is a textbook implementation of the **Front Controller** design pattern. All JSF requests are funneled through a single entry point, which normalizes the request into a structured `FacesContext`, coordinates the six lifecycle phases, and ensures consistent error handling and response formatting.

### MVC Pattern (EO Webview)

Every webview in `eo.web.webview` follows the same request lifecycle:

```
Request -> XML Config -> Logic.execute() -> Bean population -> JSP render
```

Each webview is self-contained with four artifacts (Bean, Logic, XML, JSP). There is no shared logic base class, no cross-view bean composition, and no direct communication between views. The only integration point is the shared XML configuration framework.

This design keeps each view easy to understand in isolation but means there is no reusable abstraction layer for common view logic — if multiple views need the same data preparation, the Logic classes are duplicated rather than shared.

### Configuration-Driven Registration

All servlet components (listeners, filters, `FacesServlet`) are registered via `web-full.xml`, the centralized deployment descriptor. This XML-based approach (as opposed to `@WebListener` and `@WebFilter` annotations) provides explicit, order-controllable registration typical of enterprise Java deployments. However, it also means that adding new servlet components requires XML changes rather than being a purely code-level operation.

### Stub-First Development

A notable architectural pattern across the codebase is the use of structural scaffolding. Both the X33 listener and filter in `com` exist as placeholder implementations — one is an empty class body, the other is a no-op filter. The `eo.web.webview.ACA001SFLogic.execute()` method is also empty.

This pattern suggests one or more of the following:

1. **Framework migration** — Original logic may have been removed during a migration (e.g., from Struts to Spring) and delegated to framework-level equivalents.
2. **Incremental development** — Stubs were left intentionally for developers to populate as features are implemented.
3. **Build differentiation** — The `X33JV` prefix indicates Japanese build scoping; if that build is no longer supported, these components may be relics.

### Request Processing Pipeline

The complete request pipeline, from HTTP client to HTML response, flows through all three layers:

```mermaid
flowchart TD
    subgraph FilterChain["Servlet Filter Chain"]
        Filter["X33JVRequestEncodingSjisFilter
(no-op, passes through)"]
    end

    subgraph JSFLifecycle["JSF Request Lifecycle"]
        RestoreView["1. Restore View"]
        ApplyRequest["2. Apply Request Values"]
        ProcessValidation["3. Process Validation"]
        UpdateModel["4. Update Model Values"]
        InvokeApp["5. Invoke Application"]
        RenderResponse["6. Render Response"]

        RestoreView --> ApplyRequest
        ApplyRequest --> ProcessValidation
        ProcessValidation --> UpdateModel
        UpdateModel --> InvokeApp
        InvokeApp --> RenderResponse
    end

    subgraph MVC["EO MVC Webview"]
        Logic["ACA001SFLogic.execute()
(data preparation)"]
        Bean["ACA001SFBean
(data carrier)"]
        JSP["FULL_ACA001010PJP.jsp
(view rendering)"]
        XML["WEBGAMEN_FULL_ACA001.xml
(routing config)"]

        Logic --> Bean
        Logic --> JSP
        XML -->|wires to| Logic
        XML -->|routes to| JSP
    end

    Filter -->|"dispatches"| JSFLifecycle
    JSFLifecycle -->|"invokes"| MVC
```

1. An HTTP request arrives at the servlet container.
2. The `X33JVRequestEncodingSjisFilter` intercepts it (currently as a no-op pass-through).
3. `FacesServlet` creates a `FacesContext` and routes the request through the JSF lifecycle.
4. During the Invoke Application phase, the framework delegates to the appropriate EO MVC webview Logic class.
5. The Logic class populates the Bean, which the JSP renders as HTML.
6. The HTML response is returned to the client.

### Data Flow

Within the MVC webview layer, data flows through a strict separation of concerns:

```mermaid
flowchart LR
    XML["WEBGAMEN_FULL_ACA001.xml
request wiring"] -->|dispatches| LOGIC["ACA001SFLogic.execute()"]
    LOGIC -->|populates| BEAN["ACA001SFBean
String value"]
    LOGIC -->|forwards to| JSP["FULL_ACA001010PJP.jsp"]
    BEAN -->|exposes via JSP EL| JSP
```

### Design Decisions

- **Minimal beans.** Each Bean carries only the fields the JSP needs, reducing coupling to upstream logic. However, the meaning of generic fields (like `String value`) cannot be inferred from the Bean alone — you must read the consuming JSP or XML config.

- **JavaBeans naming is a hard contract.** JSP EL resolution depends on exact JavaBeans getter conventions (e.g., `getValue()` resolves to `${value}`). Changing a getter signature without updating all consumers will silently break the view with no compile-time error.

- **No shared abstractions.** Views deliberately avoid inheritance or shared utility classes. This keeps each view self-documenting and isolated but means common patterns are likely duplicated across views rather than abstracted.

- **XML-driven configuration.** Routing, bean scoping, and component registration are declarative rather than code-based. This allows configuration changes (e.g., changing a bean's scope from request to session) without recompilation.

## Dependencies and Integration

### External Dependencies

| Dependency | Used By | Reason |
|------------|---------|--------|
| `javax.servlet.*` | `com.fujitsu.futurity.web.x33.*` | Servlet container APIs (Filter, ServletContextListener) |
| `javax.faces.*` | `javax.faces.webapp` | JSF framework specification (FacesServlet, FacesContext) |
| `javax.servlet.*` | `javax.faces.webapp` | HTTP request/response handling, filter chain integration |
| Servlet API | All web packages | Container-managed lifecycle (filters, listeners, servlets) |

### Inbound Dependencies

| Source | Used By | What it does |
|--------|---------|-------------|
| `web-full.xml` | `com.*`, `javax.*` | Registers `X33AppContextListener`, `X33JVRequestEncodingSjisFilter`, and `FacesServlet` in the servlet container. |
| JSF Implementation (Mojarra / MyFaces) | `javax.faces.webapp` | Provides the actual lifecycle execution logic delegated by `FacesServlet`. |

### Integration with the Rest of the System

This codebase forms the complete web tier of a Java EE application. The `com` namespace occupies the outermost boundary (first point of contact for every HTTP request), `javax` provides the framework-level request processing (JSF lifecycle), and `eo` delivers the application-specific presentation layer.

Changes to components in the `com` namespace (listener or filter) affect every request handled by the application. Changes to `eo` webviews are scoped to individual views but may share beans across multiple JSP views. Changes to `javax` would require modifying the JSF framework itself, which is typically provided as a container library.

### Module Interaction Diagram

The following diagram shows how the top-level namespaces interact as a system:

```mermaid
flowchart TD
    subgraph Container["Servlet Container"]
        XML["web-full.xml
Deployment Descriptor"]
        XML --> Listener
        XML --> Filter
        XML --> FacesServlet
    end

    subgraph ComLayer["com (Infrastructure)"]
        Listener["X33AppContextListener
ServletContextListener
(app lifecycle)"]
        Filter["X33JVRequestEncodingSjisFilter
javax.servlet.Filter
(request preprocessing)"]
    end

    subgraph JavaxLayer["javax (JSF Framework)"]
        FacesServlet["FacesServlet
front controller"]
    end

    subgraph EoLayer["eo (MVC Application)"]
        ACA001SF["ACA001SF webview
Bean + Logic + XML + JSP"]
    end

    XML -->|"initializes"| ComLayer
    Filter -->|"chain.doFilter"| FacesServlet
    FacesServlet -->|"lifecycle phases"| EoLayer
    FacesServlet -->|"invoke action"| ACA001SF
    Listener -->|"establishes"| Context["ServletContext"]
    Context --> Filter
```

## Notes for Developers

### Current State: Stub Components

The `com` namespace components are currently non-functional stubs:

- **Verify registration** — Check `web-full.xml` to confirm whether `X33AppContextListener` and `X33JVRequestEncodingSjisFilter` are still referenced. If not, they are dead code.
- **Verify logic delegation** — If the application needs character encoding handling or application-scoped initialization, confirm whether that logic has been moved to another component (e.g., a Spring filter or `@Configuration` class). Do not assume the stubs are the only place this logic exists.
- **Verify build scope** — The `X33JV` prefix strongly suggests Japanese build scoping. If the Japanese build is no longer supported, these components may be safe to remove.

### Implementing the X33 Filter

If the SJIS encoding behavior is still required, a minimal implementation of `X33JVRequestEncodingSjisFilter` would look like:

```java
public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
        throws IOException, ServletException {
    req.setCharacterEncoding("SJIS");
    chain.doFilter(req, res);
}
```

For a configurable approach (reading encoding from XML init-params):

```java
private String encoding;

public void init(FilterConfig config) {
    encoding = config.getInitParameter("encoding");
    if (encoding == null) encoding = "SJIS";
}

public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
        throws IOException, ServletException {
    req.setCharacterEncoding(encoding);
    chain.doFilter(req, res);
}
```

### Implementing the X33 Listener

If `X33AppContextListener` is still the intended initialization entry point, it should:

1. Implement `javax.servlet.ServletContextListener`.
2. Override `contextInitialized()` to perform startup tasks (load configuration, register beans, etc.).
3. Override `contextDestroyed()` to clean up resources on shutdown.
4. Be registered in `web-full.xml` via a `<listener>` element, or annotated with `@WebListener`.

### Working with EO Webviews

- **Implementing logic.** Start in the `execute()` method of the Logic class. Populate the Bean's fields there before the JSP renders. The JSP has no server-side logic of its own — all computation should happen in the Logic class.
- **JavaBeans naming is non-negotiable.** The getter must follow `get` + capitalized field name exactly. Renaming without updating the JSP EL will silently break the view with no compile-time diagnostic.
- **Multiple JSP consumers.** A Bean like `ACA001SFBean` may be referenced by multiple JSP views. Any changes to its shape (fields, getters, type) must be backward-compatible with all consumers.
- **Adding new views.** New webviews should follow the existing four-artifact pattern: a Bean POJO, a Logic class with `execute()`, a corresponding XML config entry, and a JSP view.
- **Domain knowledge matters.** The meaning of generic Bean fields and the purpose of a webview can only be determined by reading the consuming JSP, the XML config, and any surrounding business-domain documentation.

### JSF Development Notes

- The indexed `FacesServlet.java` file contains only the class declaration without method bodies. The actual lifecycle logic is implemented by the JSF reference implementation (Mojarra or MyFaces) and is not present in this source fixture.
- URL mapping in the deployment descriptor is critical — it determines which requests enter the JSF lifecycle. Common patterns include `*.jsf`, `*.faces`, or `/faces/*`.
- `FacesServlet` participates in the Servlet Filter chain. Pre-filters (encoding, security, compression) can modify the request before JSF processing begins.

### Package Structure Conventions

- New web-related components for X33 (filters, listeners) should be added to the appropriate sub-package (`filter` or `listener`) within `com.fujitsu.futurity.web.x33`.
- New EO MVC webviews should be added to `eo.web.webview` as a new sub-package following the Bean-Logic-XML-JSP convention.
- The `javax` package should not be modified directly — it is the JSF framework specification layer provided by the container.