# Root

## Overview

This codebase is a **Java EE web application test and scaffolding project** built around **JavaServer Faces (JSF)** for the presentation layer. It does not represent a single production application; rather, it is an amalgamation of several distinct subsystems cohabiting a single repository:

- **A JSF-based web UI layer** (`eo.web`) that renders pages through a traditional MVC pattern with backing beans, action logic classes, and JSP views, all wired through XML configuration.
- **A JSF integration stub** (`javax.faces`) that declares the `FacesServlet` front controller, bridging the servlet container to the JSF runtime.
- **A Fujitsu-branded application scaffold** (`com.fujitsu.futurity`) that declares servlet lifecycle hooks and a Shift-JIS encoding filter for Japanese-language workflows, but contains only no-op stubs.
- **Test fixtures** (`com.example`) that exist solely to validate a JSP parser's handling of `<%@ page %>` directive attribute ordering.

At a high level, the codebase exercises the full servlet-to-JSF pipeline: HTTP requests enter through servlet filters, pass through `FacesServlet`, and are dispatched to JSF-managed views backed by XML-wired beans and logic classes. The Fujitsu stub sits in the same filter chain as a place-holder for encoding normalization, while the test fixtures ensure the JSP parser correctly resolves imports regardless of directive attribute order.

## Sub-module Guide

The repository is organized into four top-level packages under the root namespace, each serving a distinct role:

### `com` — Fujitsu Application and Test Fixtures

The `com` package contains two entirely separate concerns:

- **`com.fujitsu.futurity`** — A Java EE web application scaffold targeting Japanese-language HTTP workflows. Its `web` sub-package declares two no-op servlet hooks: `X33AppContextListener` (a startup listener stub) and `X33JVRequestEncodingSjisFilter` (a Shift-JIS encoding filter stub). These are registered in `web.xml` and `web-full.xml` but perform no work. This appears to be a reserved extension point awaiting implementation, or potentially a deprecated module.

- **`com.example`** — A collection of minimal test fixtures. Its only child, `com.example.bugca002`, contains a trivial `KnownClass` and a JSP page with deliberately non-standard `<%@ page %>` attribute ordering, designed to reproduce and verify a fix for a parser bug where an `import=` attribute preceded by `language=` gets silently dropped.

These two concerns share a namespace but have no relationship to each other — one is application scaffolding, the other is parser test data.

### `eo` — Web Presentation Layer

The `eo.web` package is the actual **user-facing presentation layer**. It is structured as a JSF MVC application where each screen is a self-contained sub-package under `webview`. The primary indexed screen, `ACA001SF` ("Futurity"), consists of:

- **`ACA001SFBean`** — A JSF managed bean with a single `value` property.
- **`ACA001SFLogic`** — An action handler with an empty `execute()` method.
- **JSP view** (`FULL_ACA001010PJP.jsp`) that renders the page and binds to the bean.

All wiring is XML-based — `faces-config.xml`, `WEBGAMEN_*` files, `x33S_*` files, and `external-refs.xml` define bean scopes, navigation rules, and cross-module references. Screens are independent; they communicate only through JSF navigation outcomes, not Java-level imports.

### `javax` — JSF Framework Integration

The `javax.faces` package provides the **JSF front controller** (`javax.faces.webapp.FacesServlet`). This is a declaration-only stub whose full lifecycle implementation is supplied by the JSF reference implementation (Mojarra or MyFaces) at runtime. `FacesServlet` is the entry point for all JSF-bound HTTP requests, routing them through the six-phase JSF lifecycle (Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, Render Response). It is registered in both `web.xml` and `web-full.xml`, with encoding filters positioned in the servlet filter chain ahead of it.

### How the Sub-modules Relate

The four packages form a **layered servlet pipeline**:

1. **Infrastructure hooks** (`com.fujitsu.futurity`) declare the servlet-level entry points — the `X33JVRequestEncodingSjisFilter` sits in front of `FacesServlet` in the filter chain, intending to normalize character encoding before JSF processing begins.
2. **The JSF front controller** (`javax.faces.webapp.FacesServlet`) receives JSF-bound requests and orchestrates the lifecycle.
3. **The presentation layer** (`eo.web.webview`) provides the actual screens — each screen is a bean, logic class, and JSP view that `FacesServlet` dispatches to.
4. **Test fixtures** (`com.example`) are outside the runtime pipeline entirely; they are consumed only by the JSP parser during test execution.

## Key Patterns and Architecture

### Servlet-to-JSF Pipeline

The central architectural pattern across this codebase is the **Java EE servlet filter chain feeding into FacesServlet**, which drives the JSF lifecycle. HTTP requests pass through encoding filters (intended to set Shift-JIS), then reach `FacesServlet`, which runs through its six phases before returning rendered pages to the client.

```mermaid
flowchart TD
    A["HTTP Request"] --> B["X33JVRequestEncodingSjisFilter"]
    B --> C["FacesServlet"]
    C --> D["JSF Lifecycle"]
    D --> E["eo.web.webview Screen"]
    E --> F["JSP View + Managed Bean"]
    E --> G["Action Logic"]
```

### XML-Driven Bean Wiring

The `eo.web.webview` package follows a **JSF 1.x-style XML wiring** pattern. Beans are not auto-discoverable via annotations; every managed bean must be explicitly registered in `faces-config.xml` or module-specific XML files. Navigation outcomes are string-based result codes defined in XML. This creates a deployment-time contract between the Java source and the configuration layer.

### Screen-Scoped Encapsulation

Each screen in `eo.web.webview` (e.g., `ACA001SF`) is a **self-contained unit** owning its bean, logic class, JSP view, and configuration files. There are no inter-screen Java imports. Screens communicate exclusively through JSF navigation outcomes, making them independently deployable and loosely coupled.

### Scaffold-Then-Implement

The `com.fujitsu.futurity` package demonstrates a **"declare the hook, leave the body empty"** pattern. The listener and filter exist in `web.xml` but have no operational code. This allows deployment-time validation of descriptors and ensures the container won't error on missing classes, while deferring implementation to a later phase.

### Attribute-Set Parsing

The `com.example.bugca002` fixture validates that the JSP parser treats `<%@ page %>` directive attributes as an **unordered set** rather than a positional sequence. The fix ensures that `import=` is recognized regardless of whether `language=` appears before or after it in the directive.

### Shared Filter Chain

Notably, both the Fujitu encoding filter (`X33JVRequestEncodingSjisFilter`) and `FacesServlet` are registered in the same deployment descriptors. This means the filter sits in the servlet filter chain and intercepts requests **before** they reach the JSF lifecycle — the intended (but currently unimplemented) point for setting request character encoding to Shift-JIS.

## Dependencies and Integration

### External Dependencies

| Dependency | Used By | Purpose |
|---|---|---|
| `javax.servlet.*` | `com.fujitsu.futurity`, `javax.faces.webapp` | Servlet API for HTTP request/response handling |
| `javax.faces.*` (runtime) | `javax.faces.webapp`, `eo.web` | JSF framework classes provided by the application server |
| `javax.faces.webapp` | `eo.web` (indirectly) | FacesServlet front controller wired via `faces-config.xml` |

### Inbound Integration

- **`web.xml` / `web-full.xml`** — Register `FacesServlet`, the `X33AppContextListener`, and the `X33JVRequestEncodingSjisFilter`. These deployment descriptors are the single source of truth for runtime wiring of servlet-level components.
- **`faces-config.xml` / `external-refs.xml` / `WEBGAMEN_*`** — Wire `eo.web.webview` beans, define navigation rules, and declare page-scoped properties.

### Outbound Integration

- The `eo.web.webview` screens reference external logic classes through `external-refs.xml`, but do not import Java packages from other modules.
- The `com.fujitsu.futurity` and `com.example` packages are **leaf modules** — nothing in this codebase imports from them, and they depend only on `javax.servlet`.

### Package Dependency Graph

```mermaid
flowchart TD
    subgraph INFRA["javax.faces"]
        FS["FacesServlet"]
    end

    subgraph PRESENTATION["eo.web"]
        subgraph WEBVIEW["webview"]
            SCREENS["Screen Renderers
(e.g. ACA001SF)"]
        end
    end

    subgraph STUBS["com"]
        FUTURE["Futurity Scaffolding
(X33 filters/listeners)"]
        TESTS["Test Fixtures
(com.example)"]
    end

    subgraph CONFIG["Deployment"]
        WEBXML["web.xml
web-full.xml"]
        FACESXML["faces-config.xml
external-refs.xml"]
    end

    WEBXML -->|"registers"| FS
    WEBXML -->|"registers"| FUTURE
    FACESXML -->|"wires"| SCREENS
    FS -->|"lifecycle"| SCREENS
    FUTURE -->|"filter chain"| FS
    SCREENS -->|"uses"| FS
```

## Notes for Developers

### Deployment Descriptor Consistency

All servlet-level components (`FacesServlet`, `X33AppContextListener`, `X33JVRequestEncodingSjisFilter`) are registered in **both** `web.xml` (servlet profile) and `web-full.xml` (full Jakarta EE profile). Changes must be made in both files to avoid environment-specific behavior differences.

### The Fujitsu Module Is Unimplemented

All classes in `com.fujitsu.futurity` are no-op stubs. The Shift-JIS encoding filter currently passes all requests through unmodified, which means Japanese-language input will produce garbled output if the server's default encoding is not SJIS-compatible. Before implementing this module, decide whether to:
- Set `request.setCharacterEncoding("cp932")` in the filter's `doFilter` method.
- Wrap the request in a custom `HttpServletRequestWrapper` to make `getParameter` calls encoding-aware.
- Implement `X33AppContextListener` as a `ServletContextListener` or Spring `ContextLoaderListener`.

Verify with the team whether this module is still in scope, as it may be a candidate for cleanup.

### Test Fixtures Are Not Production Code

The `com.example` packages are **test fixtures only**. Do not refactor or extend them with business logic. They exist to exercise the JSP parser and should remain minimal. New test cases should be added as new classes, not by modifying existing ones.

### Bean Scope Is Configurable

In `eo.web.webview`, bean scope (request, session, view, application) is defined in `faces-config.xml`, not in Java annotations. Changing a bean's scope requires XML updates. If a bean needs to persist across requests, verify the scope is set appropriately.

### Dual Source Trees

Some classes (notably `ACA001SFLogic`) exist in multiple source trees (`full-fixture-codebase` and `xml-unresolved-fqn`). Changes must be applied consistently, or behavior may diverge between fixture variants.

### FacesServlet Mapping Has Consequences

The URL pattern used to map `FacesServlet` affects which requests enter the JSF lifecycle. Using `/*` intercepts all requests including static resources, which can cause errors without a resource handler. Prefer `*.jsf` or `/faces/*` unless all requests should go through JSF.

### Module Isolation

The `com.fujitsu.futurity` and `com.example` packages are leaf nodes with no inbound dependencies. Changes here are low-risk and have no downstream ripple effects. The `eo.web` module is similarly isolated — it communicates with the rest of the application through XML configuration and JSF navigation, not Java-level imports.