# Root

## Overview

This codebase is a **legacy Java EE web application** built around the Fujitsu Futurity product line, with a modular internal architecture organized into three distinct concern areas under the top-level `com` and `eo` package namespaces, plus a `javax` framework root. The system spans from low-level framework integration (JavaServer Faces, servlet container wiring) through batch processing and Start-of-Day (SOD) dispatch coordination, up to browser-rendered JSF views.

A defining characteristic of this codebase is that **much of its content is scaffolding** -- auto-generated fixture classes and no-op stubs designed to exercise tooling (import resolution, static analysis, wiki generation) and to lay architectural groundwork before business logic is implemented. The cross-module wiring that exists (particularly the KOPT batch processing pipeline) is intentional and real, even where method bodies are empty.

The `com` namespace is the primary package, containing three functionally unrelated sub-systems: test fixtures (`com.example`), the Fujitsu web application skeleton (`com.fujitsu`), and the KOPT batch processing and SOD dispatch framework (`com.optage`). The `eo` namespace provides the JSF-based web presentation layer, while `javax` represents the Java EE framework integration point for JSF itself.

## Sub-module Guide

The codebase is organized into three top-level module families, each addressing a different concern:

### com -- Business and Framework Code

The `com` package is the largest and most diverse namespace, containing three functionally independent sub-systems that share a package root but serve different purposes.

#### com.example -- Test Fixtures and Import Resolution Anchors

The `com.example` package is not production code at all. It is a fixture tree whose sole purpose is to provide well-known Java types that JSP views and analysis tools can import, validating that the build pipeline correctly resolves cross-package and cross-language (Java-to-JSP) imports. The canonical example is `com.example.bugca002.KnownClass` -- an empty class with an empty method, referenced directly by JSP pages like `BugCa002Language Before Import.jsp`. This is a leaf module with no outgoing dependencies; it is consumed by other parts of the system but consumes nothing in return.

#### com.fujitsu -- Fujitsu Futurity Web Application Skeleton

The `com.fujitsu.futurity` package is the structural skeleton of the Fujitsu Futurity application. It provides the servlet-container boundary through which all HTTP requests and application lifecycle events enter from the JEE servlet container. Today, this area is best understood as a **registration layer** rather than an active processing layer -- components are wired into the container exclusively through `web.xml` and `web-full.xml` deployment descriptors, but the components themselves are no-op stubs.

The currently documented sub-system is **X33** (`com.fujitsu.futurity.web.x33`), which provides:
- **X33JVRequestEncodingSjisFilter** -- A servlet filter designed to set incoming HTTP request encoding to Shift JIS (Windows-31J) for Japanese-language input. Currently a pure pass-through.
- **X33AppContextListener** -- A servlet context listener registered for application startup and shutdown events. Currently an empty class that does not even implement `ServletContextListener`.

Both components follow a **stub-first, implement-later** approach, suggesting the application may be in a transitional state -- perhaps a greenfield scaffolding effort or a legacy codebase awaiting feature migration.

#### com.optage -- KOPT Batch Processing and SOD Dispatch Framework

The `com.optage.kopt` package implements the **KOPT system**, a modular framework centered around batch processing, dispatch coordination, and contract handling. It orchestrates **Start-of-Day (SOD) operations** for the JKK client or internal system through a four-layer call chain:

1. **`bp` (SOD Dispatch Coordination)** -- The top-level orchestration layer. `JKKHakkoSODCC` acts as the primary facade, accepting SOD dispatch requests and delegating to validation and send layers. `JKKBpServiceBase` provides shared initialization via the Template Method pattern.
2. **`batch` (Batch Processing Infrastructure)** -- Provides execution scaffolding through fixture classes (`KKPRC14901`, `KKPRC24901`, `KKPRC34901`). Only `KKPRC14901` has concrete wiring today -- its `run()` method delegates to `EKK0301A010.process()` in the `ekk` module.
3. **`ekk` (Contract Processing)** -- Where core business processing logic resides (conceptually; currently stubbed). `EKK0301A010` is the primary processor, and its `notify()` method bridges to the `kkw` package.
4. **`kkw` (Batch Trigger Notifications)** -- The notification trigger mechanism. `KKW0100B001.trigger()` is the endpoint called by contract processors to emit events.

Two additional sub-packages exist but are disconnected from the active chain: **`dto`** (defines the external API contract with `JKKSodRequestDTO` and `JKKSodResponseDTO`, but not yet consumed by internal classes), and **`esc`** (a service control placeholder with no wiring). The **`unrelated`** package is a deliberately isolated test fixture for documentation tooling validation.

### eo -- Web Presentation Layer

The `eo.web` package is the web presentation layer of the application, responsible for rendering business-focused views to end users through the classic JSF MVC pattern. Its sole sub-module is **`eo.web.webview`**, which implements individual business views as self-contained units.

Each view (e.g., **ACA001SF** -- the "Futurity" view) consists of:
- **A backing bean** (e.g., `ACA001SFBean`) -- A JSF-managed POJO exposing properties via getters. Beans are lean and tend to be read-only (getters without setters), preventing two-way data binding.
- **A logic class** (e.g., `ACA001SFLogic`) -- A dedicated class with an `execute()` method that the bean delegates to during the JSF lifecycle. These methods are currently no-op stubs serving as extension points.
- **A JSP view page** (e.g., `FULL_ACA001010PJP.jsp`) -- The rendered UI using EL expressions to read bean properties.
- **XML configuration files** (e.g., `faces-config.xml`, `WEBGAMEN_*.xml`, `x33S_*.xml`) -- Multiple XML files manage managed-bean registration, action mappings, and external wiring.

Views operate as independent units within the JSF request lifecycle. They do not communicate directly; navigation between them is handled by JSF's navigation outcome mechanism (though current `void` return types on `execute()` methods limit this capability). The module follows a configuration-driven approach rather than a fully annotation-based one, with JSF managed beans registered across multiple XML files.

Some logic classes appear in two source trees (`full-fixture-codebase` and `xml-unresolved-fqn`) with identical signatures but varying Javadoc coverage; the canonical version is the full-fixture variant.

### javax -- JSF Framework Integration

The `javax.faces` package is the root of the **JavaServer Faces (JSF)** API -- the server-side MVC framework defined by the Java EE / Jakarta EE specification for building component-based user interfaces. It does not contain a rich internal sub-module hierarchy itself; its primary sub-package is **`javax.faces.webapp`**, which provides the bridge between the JSF lifecycle and the Java Servlet specification.

The sole class in `javax.faces.webapp` is **`FacesServlet`**, the front-controller servlet for every JSF application. It is the single servlet declared in `web.xml` that receives all requests mapped to JSF URL patterns (e.g., `*.faces` or `/faces/*`) and translates incoming HTTP requests into the standardized seven-phase JSF lifecycle:

1. **Restore View** -- Reconstructs the component tree or creates a fresh one.
2. **Apply Request Values** -- Populates UI component values from HTTP request parameters.
3. **Process Validations** -- Runs converter and validator logic.
4. **Update Model Values** -- Syncs validated values into backend beans.
5. **Invoke Application** -- Executes action listeners and business logic.
6. **Render Response** -- Builds and writes the response markup.

In this fixture, `FacesServlet` is declared as an empty class body -- a deployment descriptor target rather than a full implementation. The actual lifecycle orchestration logic is provided by the JSF reference implementation (e.g., Apache MyFaces or Mojarra).

## How the Sub-modules Interact

The three module families form a layered architecture where the `javax` and `com.fujitsu` packages sit at the framework boundary, `com.optage` and `eo` sit in the business/presentation layer, and `com.example` sits at the bottom as a pure infrastructure fixture.

```mermaid
flowchart TD
    subgraph Biz["Business Layer - com"]
        subgraph Fix["com.example - Test Fixtures"]
            FIX["KnownClass
Import resolution anchor"]
        end
        subgraph Fut["com.fujitsu - Java EE Web Tier"]
            FU["Futurity App
web.xml + no-op stubs"]
        end
        subgraph Kopt["com.optage - KOPT System"]
            K["Batch + SOD dispatch
bp to batch to ekk to kkw"]
        end
    end

    subgraph Web["Presentation Layer - eo"]
        EO["JSF Views
Bean + Logic + JSP"]
    end

    subgraph Framework["Framework Layer - javax"]
        JSF["JavaServer Faces API
FacesServlet + lifecycle"]
    end

    FIX --> JSP["JSP consumers
Import targets"]
    FU --> JSP
    K --> JSP
    EO --> JSF
    JSP --> JSF
    JSP --> FU
```

### Cross-module relationships explained

- **`javax.faces` serves as the foundation.** All JSF-powered modules (`eo.web`, and potentially `com.fujitsu` views) depend on the JSF framework. `FacesServlet` is the single entry point that every JSF request passes through, orchestrating the seven-phase lifecycle.

- **`eo.web` is the view layer built on JSF.** The `eo.web.webview` views consume `javax.faces` directly -- their JSP pages and backing beans are wired into the JSF lifecycle via `FacesServlet`. This is the primary business-facing web layer.

- **`com.fujitsu` and `com.optage` are the business logic layers.** `com.fujitsu` provides the servlet-container boundary for the Futurity application (filters, listeners), while `com.optage` provides the KOPT batch processing pipeline. Both operate independently -- `com.fujitsu` handles HTTP request routing and encoding, while `com.optage` handles SOD dispatch coordination and contract processing. They share a common infrastructure pattern: registration through deployment descriptors with stub implementations awaiting real logic.

- **`com.example` is the infrastructure layer.** It is consumed by JSP pages and analysis tools to validate import resolution. It is not used by any business logic -- it exists purely to ensure the build pipeline works correctly.

- **The active KOPT call chain is the only significant internal business pipeline.** The path `bp -> batch -> ekk -> kkw` forms a clean four-layer delegation chain: dispatch coordination, batch execution, contract processing, and notification. The `dto` and `esc` sub-packages exist as planned extensions but are not yet wired into this chain.

### Key architectural patterns across modules

#### Stub-first, implement-later

Both `com.fujitsu` and `com.optage` follow this pattern: components are registered in deployment descriptors or cross-module call chains upfront, with placeholder implementations that are incrementally filled in. This minimizes merge conflicts and deployment risk when adding new functionality.

#### Configuration-over-code

All modules prefer explicit XML configuration (`web.xml`, `web-full.xml`, `faces-config.xml`, `WEBGAMEN_*.xml`) over annotations. This is characteristic of legacy Java EE applications and enterprise deployments that favor auditable, version-controlled configuration.

#### Layered delegation

`com.optage.kopt` is the clearest example: each sub-module (`bp`, `batch`, `ekk`, `kkw`) has a single, well-defined responsibility and calls flow strictly top-down without sideways branching. No layer depends on its peers.

## Dependencies and Integration

### Framework dependencies

| Dependency | Used By | Purpose |
|------------|---------|---------|
| `javax.servlet` (Servlet API) | `com.fujitsu.futurity.web`, `javax.faces.webapp` | Servlet container integration |
| `javax.faces` (JSF API) | `eo.web.webview` | View framework backing beans, lifecycle, EL |
| `javax.faces.webapp.FacesServlet` | All JSF modules | Front-controller servlet registration |

### Internal dependencies (com.optage.kopt active chain)

| From | To | Mechanism |
|------|----|-----------|
| `bp.JKKHakkoSODCC` | `batch.KKPRC14901` | `validate()` instantiates and calls `check()` |
| `batch.KKPRC14901` | `ekk.EKK0301A010` | `run()` instantiates and calls `process()` |
| `ekk.EKK0301A010` | `kkw.KKW0100B001` | `notify()` instantiates and calls `trigger()` |

### External integration points

- **`com.example`** is consumed by JSP views for import resolution testing. It does not consume anything.
- **`com.fujitsu`** is consumed by the servlet container via `web.xml` / `web-full.xml`. It delegates all request handling to downstream modules.
- **`com.optage`** appears to integrate as a consumer and provider -- receiving SOD dispatch requests (likely via API endpoints) and producing dispatch results back to callers. The `dto` classes define the external contract, though internal classes do not yet reference them.
- **`eo.web`** is the presentation layer, consumed by browser clients via JSF-rendered JSP pages. Configuration spans multiple XML files that also define the bean lifecycle and navigation outcomes.
- **`javax.faces`** is consumed by all JSF-enabled modules and is registered in `web.xml` as the front-controller servlet.

### Not wired (intentionally or otherwise)

- **`com.optage.dto`** -- The DTO classes are not consumed by any internal processing classes. They are likely intended for API endpoints that wrap KOPT operations but have not yet been integrated.
- **`com.optage.esc`** -- An entirely isolated service control placeholder with no wiring to other modules.
- **`com.optage.unrelated`** -- A deliberately isolated test fixture for documentation tooling edge-case testing.
- **`batch.KKPRC24901` and `batch.KKPRC34901`** -- Stub batch profiles awaiting implementation.
- **`ekk.EKK0301A020`** -- A secondary contract processor not referenced by any other class.

## Notes for Developers

- **Large portions of this codebase are scaffolding.** The majority of classes across `com.optage`, `com.fujitsu`, and `com.example` are auto-generated fixtures or no-op stubs. Do not treat them as production-ready. The cross-module wiring is real and intentional, but the internal method bodies are largely empty.

- **XML configuration is pervasive.** Changes to beans, servlets, filters, and listeners should be reviewed across all relevant deployment descriptors (`web.xml`, `web-full.xml`, `faces-config.xml`, `WEBGAMEN_*.xml`, `x33S_*.xml`). Configuration for a single component may be spread across multiple files.

- **Follow the existing delegation pattern.** When adding new functionality to `com.optage`, follow the top-down layered pattern: dispatch coordination (`bp`) -> batch execution (`batch`) -> contract processing (`ekk`) -> notification (`kkw`). No layer should depend on its peers.

- **Naming conventions are systematic.** Classes in `com.optage` follow a 3-letter prefix + 6-digit code pattern: `KKP` for batch, `EKK` for contract processing, `KKW` for triggers, `ESC` for service control. Views in `eo.web.webview` follow an `ACA + N + SF` pattern. Maintain these conventions when adding new classes.

- **The KOPT DTO-first design is intentional.** `JKKSodRequestDTO` and `JKKSodResponseDTO` are minimal plain objects with no validation, no builders, and no business logic. If new fields are needed, add them as new `String` fields following the existing naming conventions. Input validation should be handled by the consuming service layer.

- **Read-only bean properties in `eo.web.webview` are deliberate.** Beans like `ACA001SFBean` expose getters without setters to prevent two-way binding from user input. If two-way binding is needed, add setter methods following standard JSF conventions.

- **`com.example` fixtures must not be removed.** Removing `KnownClass` or adding new sub-packages without verifying consumers can break JSP imports and code-quality checks. These classes are referenced directly by downstream consumers.

- **`com.fujitsu` filters and listeners need implementation.** The X33 filter needs `setCharacterEncoding("Windows-31J")` in `doFilter()` before `chain.doFilter()`. The X33 listener needs `implements javax.servlet.ServletContextListener` to become functional. Both are registered in two descriptors -- changes to one (`web.xml`) may need to be mirrored in the other (`web-full.xml`).

- **Thread safety considerations.** `FacesServlet` is thread-safe by design (per-request state in `ThreadLocal`). Any future initialization logic in `com.fujitsu` listeners must account for the fact that `contextInitialized` runs on the container's startup thread -- heavy blocking work will delay application startup.

- **Two source trees exist for some `eo.web.webview` classes.** Logic classes appear in both `full-fixture-codebase` and `xml-unresolved-fqn` with identical signatures but varying Javadoc. Update the canonical version in `full-fixture-codebase`.

- **JSF navigation limitation.** `execute()` methods return `void`, so they cannot produce JSF navigation outcome strings directly. Navigation must instead be handled by modifying bean state that JSF reads, or by calling `ExternalContext.redirect()` from within the logic method.

- **Shift JIS encoding is planned but not implemented.** The `X33JVRequestEncodingSjisFilter` name implies an intended strategy to set request encoding to Windows-31J, but the filter currently does nothing. This is likely relevant for Japanese-language enterprise deployments.