# Root

## Overview

This repository represents a Java EE web application built on the Jakarta EE / J2EE platform. It follows a classic multi-tier web architecture where the servlet container handles HTTP transport, the JSF framework manages the presentation lifecycle, and business subsystems process domain-specific operations.

At a high level, incoming HTTP requests enter through the servlet layer (`com.fujitsu`), flow into the JSF runtime (`javax.faces.webapp.FacesServlet`), are rendered by the JSF-based presentation layer (`eo.web`), and delegate business operations to the KOPT application subsystem (`com.optage.kopt`). A separate fixture area (`com.example`) supports tooling validation and import resolution testing.

This appears to be a legacy Java EE application targeting the Japanese market (evidenced by the X33 Shift-JIS encoding module), with a modular package structure organized around functional domains rather than technical layers.

## Sub-module Guide

The root package contains three top-level sub-modules, each occupying a distinct architectural layer:

### `com` -- Application Code Namespace

The `com` namespace holds the application's own Java packages, organized into three sub-packages:

- **`com.fujitsu`** is the servlet-level integration layer. It provides infrastructure scaffolding (listeners, filters, XML descriptors) that sits at the very bottom of the HTTP request pipeline. Its primary role is the X33 Japanese-market deployment profile, which handles Shift-JIS character encoding through a listener/filter pair. This module is intentionally lightweight -- every class is a no-op extension point, and the only dependency is the Servlet API. It does not call into any other module.

- **`com.optage`** contains the KOPT application subsystem -- the business logic tier. It is organized into feature-oriented subpackages: `batch` for scheduled jobs, `bp` for SOD (Send-Off-Dispatch) workflow orchestration, `dto` for data transfer objects, `ekk` for contract processing, `esc` for emergency shutdown control, `kkw` for batch triggering, and `unrelated` for test fixtures. Most classes are auto-generated scaffolding stubs with placeholder comments, but `KKPRC14901` (batch -> ekk delegation) and `EKK0301A010` (ekk -> kkw notification) are the only classes with real cross-package wiring. `bp` serves as the coordination hub, connecting to `batch` for validation and `dto` for data transport.

- **`com.example`** is a test-harness area. It contains minimal fixture classes (like `KnownClass` in `com.example.bugca002`) used exclusively to validate import resolution and language tooling behavior. This is a leaf dependency -- other code depends on it, but it depends on nothing else.

**Relationship:** `com.fujitsu` sits at the entry point (servlet infrastructure), `com.optage` sits at the business layer (domain logic), and `com.example` is an external test utility. These three do not directly depend on each other -- they are independent namespaces serving different purposes within the application.

### `eo` -- JSF Presentation Layer

The `eo` package is the application's web presentation tier, built on JavaServer Faces (JSF). It follows a clean MVC pattern:

- **`eo.web`** is the top-level grouping for all web-facing components. It does not contain standalone source files itself; instead, it organizes functionality through child sub-modules.

- **`eo.web.webview`** is the core of `eo.web`. Each named sub-package (currently `ACA001SF`) corresponds to a distinct view or feature area. Each sub-module follows a consistent triad: a backing bean (e.g., `ACA001SFBean`) exposes data properties via getters for JSP EL binding, a logic class (e.g., `ACA001SFLogic`) handles form submissions, and JSP/JSF view pages bind to the bean via EL expressions.

- Components are registered across multiple XML configuration files (`faces-config.xml`, `WEBGAMEN_FULL_ACA001.xml`, `x33S_ACA001.xml`, `external-refs.xml`), suggesting the same views can operate under different scopes or initialization profiles.

**Relationship:** `eo.web` sits above the JSF framework (`javax.faces.webapp`) in the request pipeline. It consumes the JSF lifecycle provided by `javax.faces.webapp.FacesServlet` and delegates business logic calls into `com.optage.kopt.bp`. This is the middle tier where HTTP requests become view models and back.

### `javax` -- JSF Framework Integration

The `javax` package is not application code but rather the integration point with the JavaServer Faces framework:

- **`javax.faces`** is the root namespace for the JSF web framework. It provides the component-based server-side UI infrastructure -- the six-phase request lifecycle (Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, Render Response), managed beans, converters, and validators.

- **`javax.faces.webapp`** exposes the sole public type: `FacesServlet`. This is the gateway servlet through which all JSF-related HTTP requests flow. It is configured in `web.xml` and `web-full.xml` to intercept matching URL patterns. `FacesServlet` does not implement the lifecycle itself -- it delegates to a `Lifecycle` instance from the JSF `Application`.

**Relationship:** `javax.faces.webapp` is the structural bridge between the servlet container (where `com.fujitsu` operates) and the application's JSF presentation layer (`eo.web`). Without `FacesServlet`, the rest of the JSF runtime has no entry point from the web container.

## How the Sub-modules Work Together

The system follows a clear top-down request flow, with the web layer (`com.fujitsu` + `javax.faces.webapp`) at the bottom, the JSF presentation layer (`eo.web`) in the middle, and the business logic layer (`com.optage`) at the top:

1. An HTTP request arrives at the servlet container.
2. The X33 encoding filter (`com.fujitsu`) runs first, potentially setting Shift-JIS encoding on the request.
3. The request passes through `FacesServlet` (`javax.faces.webapp`), which creates a request-scoped `FacesContext` and delegates to the JSF lifecycle.
4. During the Invoke Application phase, JSF resolves the backing bean (`eo.web.webview.ACA001SFBean`) and triggers the logic class (`ACA001SFLogic.execute()`).
5. The logic class delegates business operations to `com.optage.kopt.bp` (SOD workflow), which in turn may call into `batch`, `ekk`, or `kkw`.

The `com.example` package sits outside this flow entirely -- it is a test fixture consumed by JSP views only during import resolution validation, not during runtime request processing.

### System Interaction Diagram

```mermaid
flowchart TD
    subgraph Inbound["Inbound Entry"]
        HTTP["HTTP Request"] -->|URL pattern| FacesServlet["FacesServlet
javax.faces.webapp"]
    end

    subgraph Servlet["com.fujitsu Servlet Layer"]
        Filter["X33 Encoding Filter"]
        Listener["X33 App Context Listener"]
    end

    subgraph JSF["JSF Runtime"]
        FacesContext["FacesContext"]
        Lifecycle["Lifecycle
6-phase pipeline"]
    end

    subgraph Presentation["eo.web JSF Presentation"]
        Bean["Backing Bean
(e.g. ACA001SFBean)"]
        Logic["Logic Class
(e.g. ACA001SFLogic)"]
        Views["JSP Views"]
    end

    subgraph Business["com.optage KOPT"]
        SOD["SOD Workflow
bp"]
        Batch["Batch Processing
batch"]
        Contract["Contract Processing
ekk"]
    end

    HTTP --> Filter
    Filter --> FacesServlet
    FacesServlet --> FacesContext
    FacesContext --> Lifecycle
    Lifecycle --> Bean
    Bean --> Views
    Views --> Logic
    Logic --> SOD
    SOD --> Batch
    Batch --> Contract
```

### KOPT Internal Data Flow

Within `com.optage.kopt`, the primary data flow (when fully implemented) follows this chain:

```
bp (orchestrates) -> dto (carries request) -> batch (validates) -> ekk (contracts) -> kkw (notifications)
```

The remaining subpackages (`esc`, `unrelated`) are isolated with no dependencies.

## Key Patterns and Architecture

### Extension-Point Scaffolding (com.fujitsu)

Every class across `com.fujitsu` follows the same extension-point pattern: declare a descriptively named class in the correct package, register it in XML deployment descriptors, and leave the implementation empty. This is intentional -- these are extension points designed to absorb future logic without requiring deployment descriptor rework. The pattern yields three benefits: migration safety (the deployment contract is preserved), deployment-first (the container knows about components before they have behavior), and low coupling (stubs have no imports beyond the Servlet API).

### Dual-Descriptor Deployment (com.fujitsu)

The X33 filter is declared in both `web.xml` and `web-full.xml`, suggesting conditional deployment profiles -- a "full" WAR that includes all X33 features and a "lite" WAR that omits them. Any change to X33 registration must be reflected in both descriptors.

### JSF MVC Triad (eo.web)

Every view sub-module under `eo.web.webview` adheres to a three-part structure: a backing bean exposing properties via getters/setters, a logic/action class processing server-side actions, and JSP/JSF view pages binding to the bean via EL expressions. This keeps presentation, data, and action logic cleanly separated within each sub-module's namespace.

### Fixture / Stub Pattern (com.optage, com.example)

Almost every class across `com.optage.kopt` and `com.example` is an auto-generated fixture for test scaffolding. Method bodies contain inline comments like `/* SOD dispatch logic */` or `/* Contract processing */` indicating intended but unimplemented business logic. Developers should treat these as scaffolding, not production code. `com.example` is a leaf dependency consumed only for import resolution validation; `com.optage` is the business layer awaiting real implementation.

### Delegation over Composition (com.optage)

The few classes with active code use a simple delegation pattern -- creating target classes inline and calling methods on them, without factories or dependency injection. For example, `KKPRC14901.run()` instantiates `EKK0301A010`, `JKKHakkoSODCC.dispatch()` creates `JKKSodSendCC` inline, and `EKK0301A010.notify()` creates `KKW0100B001` inline.

### Servlet-as-Lifecycle-Gateway (javax.faces.webapp)

`FacesServlet` delegates the HTTP entry point to a single servlet class. It does not implement the JSF lifecycle itself -- it obtains a `Lifecycle` instance from the `Application` and delegates phase execution to it. This decouples request dispatch from phase execution, allowing implementations to swap lifecycle behavior without touching the servlet.

### Request-Scoped Context Isolation (javax.faces)

Each HTTP request produces its own `FacesContext` instance, wrapped by an `ExternalContext` that bridges servlet types to the JSF abstraction. The `FacesContext` is accessed via `FacesContext.getCurrentInstance()` on a `ThreadLocal`, ensuring lifecycle data is isolated per-request and does not leak across threads.

## Dependencies and Integration

### External Dependencies

| Dependency | Used By | Purpose |
|---|---|---|
| `javax.servlet.*` | `com.fujitsu` classes | Servlet lifecycle and filter handling |
| `javax.servlet.*` | `javax.faces.webapp.FacesServlet` | HTTP request/response handling |
| `javax.faces.*` | `javax.faces.webapp.FacesServlet` | JSF runtime types (`FacesContext`, `Lifecycle`, `Application`) |
| JUnit (test-scope) | `com.optage.kopt.bp` | Test for `JKKHakkoSODCCTest` |

### Internal Dependencies

| Source | Target | Nature |
|---|---|---|
| `com.fujitsu.futurity.web` | `javax.faces.webapp` | X33 filter intercepts requests before JSF lifecycle |
| `javax.faces.webapp` | `eo.web` | JSF lifecycle dispatches to backing beans |
| `eo.web.webview.ACA001SF` | `com.optage.kopt.bp` | JSF logic class delegates to SOD workflow |
| `com.optage.kopt.bp` | `com.optage.kopt.batch` | SOD validation calls batch procedure |
| `com.optage.kopt.batch` | `com.optage.kopt.ekk` | Batch procedure delegates to contract processing |
| `com.optage.kopt.ekk` | `com.optage.kopt.kkw` | Contract processing triggers notification |
| `com.optage.kopt.bp` | `com.optage.kopt.dto` | SOD workflow uses request/response DTOs |
| JSP views | `com.example.bugca002` | Import resolution test fixture |

### Cross-Module Relationships

The application forms a single, linear dependency chain from HTTP entry to business logic:

```
Servlet Container -> com.fujitsu -> javax.faces.webapp -> eo.web -> com.optage
```

`com.example` is the sole exception -- it is a leaf fixture consumed only by JSP views during import validation, not during runtime request processing.

## Notes for Developers

- **Most business code is scaffolding.** The vast majority of classes in `com.optage.kopt` and `eo.web.webview` are auto-generated fixtures or no-op stubs. Do not assume any non-stub class represents finished business logic. Always check method bodies for placeholder comments before relying on behavior.

- **`com.fujitsu` is infrastructure, not business logic.** The listener and filter in `com.fujitsu.futurity.web.x33` are extension points with no runtime behavior. If you are tasked with implementing X33 initialization or encoding logic, these are your entry points.

- **Shift-JIS is a legacy concern.** The X33 module's focus on Japanese-market character encoding suggests backward compatibility requirements with legacy Japanese clients. Consider whether UTF-8 migration is viable for modern deployments, which could eliminate the encoding filter entirely.

- **Update both XML descriptors.** Changes to `com.fujitsu` listener or filter registration must be reflected in both `web.xml` and `web-full.xml`. Failure to do so may cause environment-specific failures.

- **Use XML, not annotations.** To maintain consistency, new listeners and filters for `com.fujitsu` should be declared in XML deployment descriptors rather than using `@WebListener` or `@WebFilter` annotations.

- **FacesServlet should not be subclassed.** If you need to intercept requests before or after the JSF lifecycle, use a servlet Filter placed before or after `FacesServlet` in the filter chain.

- **`FacesContext` is strictly request-scoped.** Never store it as an instance field. Access it via `FacesContext.getCurrentInstance()` within the request thread.

- **DTOs need augmentation.** The `dto` classes in `com.optage.kopt.dto` are plain field containers with no accessors, constructors, or serialization annotations. Production use will require generating or adding these.

- **Only two classes in KOPT have meaningful wiring.** `KKPRC14901` (batch -> ekk delegation) and `EKK0301A010` (ekk -> kkw notification) are the only classes with actual cross-package references beyond stubs. If you are tracing the SOD workflow, start in `bp`.

- **Watch dual source paths.** Some classes in `eo.web.webview` exist in dual source paths (full-fixture and xml-unresolved-fqn). If you modify a shared logic class, check whether a corresponding file exists in the alternate source path and keep both in sync.

- **`com.example` is a test utility.** Classes here are fixtures with intentionally empty implementations. They exist to exercise tooling, not to implement business logic. When adding new fixtures, follow the `com.example.bugcaXXX` pattern with a class containing a public, resolvable method -- keep it minimal with no fields and no side effects.

- **No source files are indexed for com.fujitsu.** Static analysis tools may not currently recognize the source files for this package. Ensure the source path is included in the analysis configuration if you rely on tooling for this module.

## Summary

This root area of the codebase represents a Java EE web application with a classic layered architecture. The servlet infrastructure (`com.fujitsu`) handles HTTP transport and Japanese-market encoding, the JSF framework (`javax.faces.webapp`) provides the presentation lifecycle, the JSF presentation layer (`eo.web`) renders views through a clean MVC pattern, and the business logic subsystem (`com.optage.kopt`) processes domain operations -- though most of it remains unimplemented scaffolding. The system is held together by XML deployment descriptors and follows consistent patterns across its modules, from extension-point scaffolding to fixture-based testing.