# Com

## Overview

The `com` package serves as the top-level namespace for the project's Java code. Under it, three distinct sub-packages coexist as independent business domains — each with its own architecture, deployment model, and purpose. They are siblings, not components that directly interact with each other.

| Sub-package | Role |
|---|---|
| `com.example` | Test scaffolding and import-resolution fixtures for tooling validation |
| `com.fujitsu` | Servlet-level web entry point for the Fujitsu / Futurity platform |
| `com.optage` | Enterprise application with batch processing, SOD workflow orchestration, and contract handling |

These packages share a namespace but do not depend on each other. Understanding `com` as a whole means understanding the three parallel concerns it houses: testing infrastructure, web-layer scaffolding, and application logic stubs.

## Sub-module Guide

### `com.example` — Test Fixtures

`com.example` is the project's fixture factory. Its classes are intentionally empty — no fields, no side effects — designed solely to be imported and resolved by other modules. The most concrete usage is the `bugca002` sub-package, which provides `KnownClass` as a known-good import target for JSP views in other modules. When those JSPs compile and the IDE can resolve the class, tooling validation passes.

This is a **leaf dependency**: nothing in `com.example` depends on anything outside `java.lang`, but many modules depend on it for validation. Adding new fixtures follows the `com.example.bugcaXXX` naming convention, one per regression test case.

### `com.fujitsu` — Web Entry Point Scaffolding

`com.fujitsu` declares the HTTP-level deployment contract for the Fujitsu platform. Its classes (`X33AppContextListener`, `X33JVRequestEncodingSjisFilter`) are registered in `web.xml` and `web-full.xml` as servlet context listeners and request filters. The classes themselves are no-op stubs — the extension-point pattern — so the container knows about them before their implementations are written.

The X33 profile within `futurity.web` handles Japanese market concerns (Shift-JIS encoding) through a listener/filter pair. The listener fires at startup to populate `ServletContext` state; the filter runs per-request to handle encoding. They communicate through the servlet context scope but do not currently invoke each other.

This package is architecturally **isolated** — it depends only on `javax.servlet` and pulls in no application classes. It is a deployment contract waiting for behavior.

### `com.optage` — Enterprise Application Stub

`com.optage` contains the bulk of the observable code in the project. Its `kopt` sub-package organizes capabilities into feature-oriented subpackages: `batch` for batch job processing, `bp` for SOD workflow orchestration, `ekk` for contract processing, `esc` for emergency shutdown, and `kkw` as a batch trigger.

The critical distinction is that **almost all of this code is auto-generated scaffolding**. Method bodies contain inline comments like `/* SOD dispatch logic */` or `/* Contract processing */` rather than real implementations. Only two classes have meaningful cross-package wiring: `KKPRC14901` (batch delegates to `ekk`) and `EKK0301A010` (ekk delegates to `kkw`). The `bp` package is the conceptual coordination hub for SOD workflows, connecting to `dto` for data shapes and `batch` for validation.

`com.optage` is a **future-state module** — the package structure and class names document intended capabilities; the actual logic still needs to be written.

## How These Sub-modules Relate

The three packages under `com` represent three different stages of maturity and three different concerns:

```mermaid
flowchart LR
    A["com.example
Test Fixtures

Lowest maturity: all stubs
No outbound deps
Consumed by: other modules"] -->|"provides targets for"| B["Tooling Validation
in other modules"]
    C["com.fujitsu
Servlet Entry

Medium maturity: deployed
but unimplemented
Servlet API only"] -->|"routes HTTP traffic to"| D["Application Layers
(business logic)"]
    E["com.optage
Enterprise App

High maturity: classes exist
with real package structure
Mostly auto-generated stubs"] -->|"depends on"| F["External systems
(batch, contracts, etc.)"]
    subgraph "com namespace — no inter-dependencies"
        A
        C
        E
    end
```

- **No cross-package dependencies exist** between `com.example`, `com.fujitsu`, and `com.optage`. Each is independently built, deployed, and maintained.
- `com.example` is consumed **by** other modules (it is a dependency target), not a consumer itself.
- `com.fujitsu` acts as the **entry point** to the application — it sits in the HTTP request pipeline but does not call into `com.optage` directly. Any connection would be indirect through shared `ServletContext` attributes or downstream servlet filters.
- `com.optage` is the **application logic** — currently scaffolding, but intended to be the operational backbone. Its internal subpackages (`batch`, `bp`, `ekk`, etc.) have interdependencies among themselves.
- `com.fujitsu` and `com.optage` share a lifecycle pattern: both are designed as extension points with real structure but empty implementations. The difference is `com.fujitsu` is deployed now (as servlet config), while `com.optage` is still being built out.

## Key Patterns and Architecture

### Universal Stub / Fixture Pattern

All three packages share a common theme: **declare first, implement later**. Every class across `com.example`, `com.fujitsu`, and `com.optage.kopt` follows the fixture or stub pattern:

| Package | Stub Mechanism | Deployment Contract |
|---|---|---|
| `com.example` | Empty classes with no-ops methods | Classpath presence — import resolution |
| `com.fujitsu` | No-op `ServletContextListener` and `Filter` | XML descriptor (`web.xml`, `web-full.xml`) |
| `com.optage` | Auto-generated classes with placeholder comments | Package structure + naming convention |

This approach allows the project to lock in architecture (package structure, class names, deployment descriptors) before writing business logic. It also means developers must be careful not to treat stub behavior as real.

### Delegation Architecture (Optage Only)

Within `com.optage.kopt`, the classes that do have active wiring follow simple delegation: create a target class inline and call its method. There is no dependency injection framework, no factory pattern — just direct instantiation. The chain `bp` -> `batch` -> `ekk` -> `kkw` represents the primary data flow, with `dto` carrying request/response shapes through the `bp` workflow.

### Extension-Point Deployment (Fujitsu Only)

`com.fujitsu` uses the deployment descriptor as its interface contract. Classes are declared, registered in XML, and left as stubs. New features follow the same three-step pattern: create class in the right package, add entry to the XML descriptor, leave implementation as no-op. This ensures the container configuration is always valid, even when implementations are missing.

## Dependencies and Integration

### Internal Dependency Graph (com.optage only)

Since `com.example`, `com.fujitsu`, and `com.optage` are independent, the only meaningful internal dependency graph lives within `com.optage.kopt`:

| Source | Target | Nature |
|---|---|---|
| `batch` | `ekk` | `KKPRC14901.run()` instantiates `EKK0301A010` |
| `bp` | `batch` | `JKKHakkoSODCC.validate()` calls `KKPRC14901.check()` |
| `ekk` | `kkw` | `EKK0301A010.notify()` instantiates `KKW0100B001` |
| `bp` | `dto` | SOD workflow uses request/response DTOs |

### External Dependencies

| Package | External Dependencies |
|---|---|
| `com.example` | None (only `java.lang`) |
| `com.fujitsu` | `javax.servlet.*` (Servlet API only) |
| `com.optage` | JUnit (test scope only) |

### Integration with the Rest of the System

- `com.fujitsu` is the **HTTP entry point**. When implemented, it will receive requests from the servlet container and forward them downstream. It does not directly call any `com.optage` class but would pass requests to controllers and services in other packages.
- `com.optage` is the **application core**. Once its stubs are replaced with real implementations, it will handle the actual business operations — batch processing, SOD workflows, contract handling, and emergency shutdown control.
- `com.example` is **invisible at runtime**. It only matters during compilation and IDE analysis, providing import resolution targets for other modules.

## Notes for Developers

- **Nothing is production-ready**. Every class in `com.example` is a fixture, every class in `com.fujitsu` is a no-op stub, and almost every class in `com.optage` is an auto-generated scaffold with placeholder comments. Treat all code in this namespace as structure, not behavior.
- **Do not assume empty methods are intentional**. In `com.optage`, empty methods with comments like `/* SOD dispatch logic */` indicate planned but unimplemented logic. In `com.fujitsu`, no-op methods in a `ServletContextListener` indicate a deployment contract that needs implementation.
- **Follow naming conventions**. New classes in `com.example` should use the `bugcaXXX` pattern. New classes in `com.optage` should follow the `KKPRC` (batch), `JKK` (workflow), `ESC` (shutdown) prefix patterns with numeric codes.
- **Update both XML descriptors**. If you add listeners or filters to `com.fujitsu`, reflect changes in both `web.xml` and `web-full.xml` to avoid environment-specific failures.
- **`com.optage` DTOs need augmentation**. The `dto` classes are plain field containers with no accessors, constructors, or serialization annotations. Production use will require generating or adding these.
- **`com.example` is for tooling work only**. If you are working on import resolution, language support, IDE features, or compiler diagnostics, `com.example` is the package to modify. If you are writing application code, this package is not the place.
- **Consider Shift-JIS modernization**. The `com.fujitsu` encoding filter targets Japanese market clients with legacy Shift-JIS requirements. Evaluate whether UTF-8 migration would eliminate this entire module over time.
- **Only two classes have real wiring**. In the entire `com.optage` package, `KKPRC14901` and `EKK0301A010` are the only classes with meaningful cross-package references. Everything else is scaffolding.