# Getting Started

Welcome to the team! This guide answers the question "I just joined — where do I start reading?" and gets you oriented fast.

## What This Project Does

This repository is a legacy Java EE web application centered around the **KOPT system** — an internal framework for orchestrating Start-of-Day (SOD) batch dispatch operations. It also includes a JSF-based web presentation layer (the Fujitsu Futurity product line) and a collection of test fixture modules used for static analysis, import resolution, and documentation tooling validation. Much of the codebase is scaffolded with real cross-module wiring but stubbed method bodies awaiting production logic.

## Recommended Reading Order

Follow these pages in order for the clearest path to understanding:

1. **[Overview](.codewiki/overview.md)** — High-level map of the codebase, its modules, and technology stack. Start here.
2. **[Root package](.codewiki/root.md)** — The big-picture architecture: how the `com`, `eo`, and `javax` namespaces fit together.
3. **[com package](.codewiki/com.md)** — The three sub-systems under `com`: test fixtures, Fujitsu web tier, and the KOPT batch framework.
4. **[com.optage](.codewiki/com/optage.md)** — Deep dive into the KOPT system: its layered delegation chain (`bp` → `batch` → `ekk` → `kkw`), DTOs, and naming conventions.
5. **[eo.web](.codewiki/eo/web.md)** — The JSF presentation layer: backing beans, logic classes, and JSP view pages.
6. **[javax.faces](.codewiki/javax/faces.md)** — The JSF framework integration point (FacesServlet).

## Key Entry Points

These are the most important classes to understand first, listed in priority order:

### 1. `com.optage.kopt.bp.JKKHakkoSODCC` — The Primary Entry Point

The top-level facade for SOD dispatch operations. Its `dispatch()` and `validate()` methods are the gateways into the KOPT processing chain. If you only read one file, start here.

### 2. `eo.web.webview.ACA001SF.ACA001SFBean` — Most Referenced Class

This backing bean has the most incoming references (6 connections) across the codebase. It exemplifies the view-layer pattern: a lean POJO with read-only getters, exposing properties to JSP view pages via EL expressions.

### 3. `eo.web.webview.ACA001SF.ACA001SFLogic` — The Controller Stub

The logic class that beans delegate to during the JSF lifecycle. Currently an empty `execute()` method, but this is where you add business logic for any view.

### 4. `javax.faces.webapp.FacesServlet` — The Front-Controller

The single servlet that every JSF request passes through. It orchestrates the seven-phase JSF lifecycle (Restore View → Apply Request Values → Process Validations → Update Model Values → Invoke Application → Render Response).

### 5. `com.fujitsu.futurity.web.x33.filter.X33JVRequestEncodingSjisFilter`

A servlet filter designed to set Shift JIS encoding for Japanese-language requests. Currently a pass-through stub registered in `web.xml` / `web-full.xml`.

### 6. `com.optage.kopt.dto.JKKSodRequestDTO` / `JKKSodResponseDTO`

Minimal data transfer objects that define the external API contract for SOD operations. They carry only `tenantId`, `serviceId` (request) and `status`, `message` (response).

## Project Structure

The source code is organized into four package namespaces under `src/main/java`:

```
src/main/java/
├── com/                          <-- Business logic and test fixtures
│   ├── example/                  <-- Test fixtures (import resolution anchors)
│   │   └── bugca002/
│   │       └── KnownClass.java   <-- Empty class consumed by JSP views
│   ├── fujitsu/                  <-- Fujitsu Futurity web tier
│   │   └── futurity/web/x33/     <-- Filters, listeners (no-op stubs)
│   └── optage/                   <-- KOPT batch/SOD framework
│       └── kopt/
│           ├── bp/               <-- SOD dispatch coordination (JKKHakkoSODCC)
│           ├── batch/            <-- Batch execution (KKPRC14901)
│           ├── ekk/              <-- Contract processing (EKK0301A010)
│           ├── kkw/              <-- Batch trigger (KKW0100B001)
│           ├── dto/              <-- Request/Response DTOs
│           ├── esc/              <-- Service control placeholder
│           └── unrelated/        <-- Documentation tooling edge-case fixture
├── eo/                           <-- Web presentation layer
│   └── web/
│       └── webview/              <-- JSF views (beans + logic + JSP)
│           └── ACA001SF/
│               ├── ACA001SFBean.java
│               └── ACA001SFLogic.java
└── javax/                        <-- Framework integration
    └── faces/
        └── webapp/
            └── FacesServlet.java
```

### The Architecture at a Glance

```mermaid
flowchart TD
    subgraph Java["com - Java Packages"]
        EX["com.example
Test Fixtures"]
        FUJ["com.fujitsu
Web Tier"]
        OPT["com.optage
KOPT System"]
    end
    subgraph Web["eo - Web Layer"]
        WEBV["eo.web.webview
JSF Views"]
    end
    subgraph Fwk["javax - Framework"]
        JSF["javax.faces.webapp
FacesServlet"]
    end
    WEBV --> JSF
    FUJ --> JSF
    EX --> EXJSP["JSP consumers"]
```

### The KOPT Active Call Chain

The only significant internal business pipeline runs through four layers:

```mermaid
flowchart TD
    subgraph BP["bp - SOD Dispatch Coordination"]
        BCC["JKKHakkoSODCC"]
    end
    subgraph BATCH["batch - Batch Processing"]
        K14["KKPRC14901"]
    end
    subgraph EKK["ekk - Contract Processing"]
        E01["EKK0301A010"]
    end
    subgraph KKW["kkw - Batch Trigger"]
        KKW01["KKW0100B001"]
    end
    BCC --> validate
    BCC --> dispatch
    validate --> K14
    K14 --> E01
    E01 --> KKW01
```

Calls flow: **dispatch → validation → contract processing → notification**. Each layer delegates to the next without sideways branching.

## Configuration

All components in this project use **XML configuration over annotations**. Changes to beans, servlets, filters, and listeners should be reviewed across all relevant deployment descriptors.

### Key Configuration Files

| File | Controls |
|---|---|
| `full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml` | Servlet filter (`X33JVRequestEncodingSjisFilter`) and `FacesServlet` registration |
| `xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml` | Alternative web deployment descriptor (multi-pattern support) |
| `xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml` | JSF managed-bean registration and navigation rules |
| `xml-futurity-view-def/src/futurity-app/webA/env/view/def/*.xml` | View definition files for JSF pages |
| `xml-build-excluded/src/config/real-config.xml` | Application-level configuration (build-excluded fixture) |
| `xml-sun-ejb-jar/koptBp/ejbModule/META-INF/sun-ejb-jar.xml` | Sun/Oracle EJB-specific JNDI mappings |
| `xml-japanese-elements/src/futurity-app/webA/env/def/x33S_ACA001.xml` | Japanese-character encoding configuration for views |
| `full-fixture-codebase/src/config/external-refs.xml` | External reference resolution for XML entities |
| `pom.xml` (root) | Maven project coordinates: `com.optage.kopt:optage-mini-fixture:1.0.0-SPEC-SCOPED-WIKI` |

### Important Configuration Notes

- **Two source trees exist.** Some logic classes appear in both `full-fixture-codebase` and `xml-unresolved-fqn` with identical signatures. The canonical version is in `full-fixture-codebase`.
- **Components are registered in two descriptors.** The X33 filter and listener are defined in both `web.xml` and `web-full.xml`. Changes to one may need to be mirrored in the other depending on your deployment profile.
- **Configuration is pervasive.** A single component's configuration may be spread across `web.xml`, `faces-config.xml`, `WEBGAMEN_*.xml`, and `x33S_*.xml`. Always review all four files when modifying behavior.
- **Shift JIS encoding is planned but not implemented.** The filter is registered but currently does nothing. Activating it requires setting `setCharacterEncoding("Windows-31J")` in the `doFilter()` method.

## Common Patterns

### Stub-First, Implement-Later

Both `com.fujitsu` (web tier) and `com.optage` (KOPT system) follow this pattern: components are registered in deployment descriptors or cross-module wiring upfront, with placeholder implementations that are incrementally filled in. The cross-module dependencies are real and intentional; the internal method bodies are mostly stubs.

### Layered Delegation (com.optage)

The KOPT system follows a strict top-down delegation model:

```
caller → bp (dispatch) → batch (validation) → ekk (contract processing) → kkw (notification)
```

No layer depends on its peers. New code should follow this same pattern: each class has one responsibility, calls flow strictly top-down, and validation is centralized in the `bp` layer.

### Systematic Class Naming

Classes in `com.optage` follow a **3-letter prefix + 6-digit code** pattern:

| Prefix | Module | Example |
|---|---|---|
| `KKP` | Batch processing | `KKPRC14901` |
| `EKK` | Contract processing | `EKK0301A010` |
| `KKW` | Batch triggers | `KKW0100B001` |
| `ESC` | Service control | `ESC0101B001` |

Views in `eo.web.webview` follow an `ACA + N + SF` pattern (e.g., `ACA001SF`). Maintain these conventions when adding new classes.

### MVC via JSF Backing Beans

Each view in `eo.web.webview` follows a clean MVC separation:

- **Bean (Model)** — Exposes properties via getters. Read-only by design (no setters).
- **Logic class (Controller)** — The `execute()` method is where business logic goes. Currently a no-op stub.
- **JSP page (View)** — Renders HTML using EL expressions to read bean properties.

```
JSP (view) --EL reads--> Bean (model)
JSP (view) --invokes--> Logic (controller)
Bean --delegates to--> Logic
```

### DTO-First Design

Data transfer objects in `com.optage.kopt.dto` are minimal plain objects with no validation, no builders, and no business logic. They are the source of truth for the external API contract. If new fields are needed, add them as `String` fields following existing naming conventions. Input validation belongs in the consuming service, not in the DTOs.

### Read-Only Bean Properties

Beans like `ACA001SFBean` expose getters without setters to prevent two-way data binding from user input. This is deliberate. If two-way binding is needed, add setter methods following standard JSF conventions.

### Shared Initialization via Template Method

`JKKBpServiceBase` provides shared `baseInit()` logic for new service classes in the `bp` layer. New services in the `bp` area should extend this base class.

## Quick Reference

| Question | Where to Look |
|---|---|
| "How does SOD dispatch work?" | `com.optage.kopt.bp.JKKHakkoSODCC` |
| "Where do I add view logic?" | `eo.web.webview.<ViewName>.<ViewName>Logic.execute()` |
| "How are beans configured?" | `faces-config.xml`, `WEBGAMEN_*.xml`, `x33S_*.xml` |
| "How are filters/servlets registered?" | `web.xml`, `web-full.xml` |
| "What are the test fixtures?" | `com.example.*` (do not treat as production code) |
| "What is the batch processing entry?" | `com.optage.kopt.batch.KKPRC14901` |
| "Where do I add new DTO fields?" | `com.optage.kopt.dto.JKKSodRequestDTO` or `JKKSodResponseDTO` |

## Notes

- **Most code is scaffolding.** The majority of classes are auto-generated fixtures or no-op stubs. The cross-module wiring is real and intentional, but the internal method bodies are largely empty.
- **`com.example` is not production code.** It is a fixture tree whose sole purpose is to exercise import resolution and static analysis tooling. Do not remove or modify classes here without verifying downstream consumers.
- **Navigation limitation.** `execute()` methods in logic classes return `void`, so they cannot produce JSF navigation outcome strings directly. Navigation must be handled by modifying bean state that JSF reads, or by calling `ExternalContext.redirect()` from within the logic method.
- **Thread safety.** Any initialization logic in listeners must account for the fact that `contextInitialized` runs on the container's startup thread -- heavy blocking work will delay application startup.