# Getting Started

## What This Project Does

This is the **Optage Mini Fixture** codebase -- a compact test fixture for SPEC-SCOPED-WIKI tooling. It provides a realistic Maven-based Java project structure with auto-generated fixture stubs that mirror the shape of an enterprise batch-processing and SOD (Send-Out-Data) dispatch system. If you're new to the team, think of this repo as a sandbox for understanding how batch orchestration and SOD dispatch workflows are intended to hang together once real business logic is wired in.

---

## Recommended Reading Order

Start with the wiki pages in this order to build a layered understanding:

1. **[Overview](overview.md)** -- The top-level readme: technology stack, high-level architecture, and module guide.
2. **[Root namespace](root.md)** -- How the `com` package organizes everything under `com.optage`.
3. **[com/optage package](com/optage.md)** -- The parent package containing the `kopt` subsystems and their cross-cutting relationships.
4. **Specific module docs** (e.g., `com/optage/kopt/batch`) -- Dive into whichever subsystem you'll be working on.

---

## Key Entry Points

These are the classes you should understand first, in order:

| Class | Location | Why It Matters |
|-------|----------|---------------|
| **KKPRC14901** | `src/main/java/com/optage/kopt/batch/KKPRC14901.java` | The primary batch entry point. Its `run()` method delegates to the `ekk` subsystem, and its `check()` method serves as a shared validation gate for both the batch and SOD pipelines. |
| **JKKHakkoSODCC** | `src/main/java/com/optage/kopt/bp/JKKHakkoSODCC.java` | The SOD (Send-Out-Data) controller. Orchestrates validate --> dispatch --> format, and is the heart of the `bp` subsystem. |
| **EKK0301A010** | `src/main/java/com/optage/kopt/ekk/EKK0301A010.java` | The primary contract processor. Called by `KKPRC14901.run()` and itself triggers downstream handlers via `notify()`. |
| **JKKSodSendCC** | `src/main/java/com/optage/kopt/bp/JKKSodSendCC.java` | The SOD dispatch class that `JKKHakkoSODCC` creates and calls to send data. |
| **JKKHakkoSODHelper** | `src/main/java/com/optage/kopt/bp/JKKHakkoSODHelper.java` | Provides string formatting utilities (`format()`) used for data normalization. |

All other classes are either stubs (e.g. `KKPRC24901`, `KKPRC34901`, `ESC0101B001`) or utility/test classes.

---

## Project Structure

```
.
├── pom.xml                          # Root Maven POM
├── src/
│   ├── main/java/com/optage/kopt/  # Application code
│   │   ├── batch/                   # Batch entry points
│   │   │   ├── KKPRC14901.java      # Primary entry (validation + run)
│   │   │   ├── KKPRC24901.java      # Secondary stub
│   │   │   └── KKPRC34901.java      # Tertiary stub
│   │   ├── bp/                      # SOD processing pipeline
│   │   │   ├── JKKHakkoSODCC.java   # SOD controller
│   │   │   ├── JKKSodSendCC.java    # SOD dispatch
│   │   │   ├── JKKHakkoSODHelper.java # Formatting
│   │   │   └── JKKBpServiceBase.java  # Shared init hook
│   │   ├── dto/                     # Data transfer objects
│   │   │   ├── JKKSodRequestDTO.java
│   │   │   └── JKKSodResponseDTO.java
│   │   ├── ekk/                     # External subsystem
│   │   │   ├── EKK0301A010.java     # Primary contract processor
│   │   │   └── EKK0301A020.java     # Secondary
│   │   ├── esc/                     # ESC service (stub)
│   │   ├── kkw/                     # Trigger module (stub)
│   │   └── unrelated/               # Isolated stub (for testing)
│   └── test/java/
│       └── com/optage/kopt/bp/
│           └── JKKHakkoSODCCTest.java  # JUnit 4 test
├── full-fixture-codebase/           # Larger fixture with web modules
├── xml-build-excluded/              # XML config test fixtures
├── xml-malformed/                   # Malformed XML handling tests
├── xml-dtd-xsd-ref/                 # DTD/XSD reference tests
└── (many xml-* modules)            # Various XML parsing test fixtures
```

**High-level architecture:**

```mermaid
flowchart TD
  subgraph batch["batch (batch entry point)"]
    KKPRC14901["KKPRC14901"]
  end

  subgraph bp["bp (SOD processing)"]
    JKKHakkoSODCC["JKKHakkoSODCC"]
    JKKSodSendCC["JKKSodSendCC"]
    JKKHakkoSODHelper["JKKHakkoSODHelper"]
    JKKBpServiceBase["JKKBpServiceBase"]
  end

  subgraph dto["dto (data transfer)"]
    JKKSodRequestDTO["JKKSodRequestDTO"]
    JKKSodResponseDTO["JKKSodResponseDTO"]
  end

  subgraph ekk["ekk (contract processing)"]
    EKK0301A010["EKK0301A010"]
  end

  subgraph kkw["kkw (trigger module)"]
    KKW0100B001["KKW0100B001"]
  end

  subgraph esc["esc"]
    ESC0101B001["ESC0101B001"]
  end

  KKPRC14901 --> EKK0301A010
  JKKHakkoSODCC --> JKKSodSendCC
  JKKHakkoSODCC --> KKPRC14901
  EKK0301A010 --> KKW0100B001
```

**Source layout:**

```mermaid
flowchart TD
  subgraph main["src/main/java (application code)"]
    Batch["batch
entry points"]
    Bp["bp
SOD processing"]
    Dto["dto
data objects"]
    Ekk["ekk
external handler"]
  end
  subgraph test["src/test/java (tests)"]
    TestClass["bp test class"]
  end
  Bp --> KKPRC["KKPRC14901.batch"]
  Batch --> EKK["EKK0301A010"]
  TestClass --> Bp
```

---

## Configuration

### Build Configuration

- **`pom.xml`** -- Root Maven POM. The project is `com.optage.kopt:optage-mini-fixture:1.0.0-SPEC-SCOPED-WIKI`, packaged as a JAR. No external dependencies are declared -- this is a deliberately lightweight fixture.

### XML Config Modules (Test Fixtures)

The repository includes multiple `xml-*` sub-projects used for testing XML parsing and configuration handling:

| Module | Purpose |
|--------|---------|
| `xml-build-excluded/` | Config files that should be excluded from build (`real-config.xml`, `real-config-screen-root.xml`). Has its own `pom.xml` and `.settings/org.eclipse.jdt.core.prefs`. |
| `xml-malformed/` | Intentionally broken XML (`broken.xml` with unclosed tags, malformed end tags) to test graceful error handling. |
| `xml-dtd-xsd-ref/` | XML files referencing DTD and XSD schemas. |
| `xml-web-xml-multi-pattern/` | Web application `web.xml` configurations for multi-pattern matching. |
| `xml-japanese-elements/` | XML with Japanese element names for encoding tests. |
| `xml-sun-ejb-jar/` | Sun/EJB-specific deployment descriptors (`sun-ejb-jar.xml`). |
| `xml-probe/`, `xml-shift-jis/`, `xml-unresolved-fqn/` | Additional parsing edge-case fixtures. |

### Web Configuration (full-fixture-codebase)

The `full-fixture-codebase` module contains a larger fixture with web-layer files:

- `WebContent/WEB-INF/web.xml`, `web-full.xml` -- Standard servlet deployment descriptors.
- `src/futurity-app/` -- JSP/view layer with Futurity web framework conventions.

---

## Common Patterns

### 1. Delegation Over Implementation

Every class in the `com.optage.kopt` hierarchy follows a delegation pattern. Classes create instances of downstream components and call their methods, rather than implementing logic directly. This makes each class a coordinator/facade. When writing new code, follow this pattern:

```java
public void doWork() {
    new DownstreamComponent().work();
}
```

### 2. Shared Validation Gate

`KKPRC14901.check()` is the shared validation primitive. Both the `batch` pipeline and the `SOD` pipeline (`bp`) depend on it. When adding or modifying validation logic, always route it through this class to keep both pipelines in sync.

### 3. Fixture Stub Convention

All classes carry Javadoc stating they are "auto-generated fixture class for SPEC-SCOPED-WIKI tests." When replacing stubs with real code:

- Preserve the declared method signatures and class relationships.
- The public API is defined by the stub signatures -- the implementation bodies are placeholders.
- Keep Javadoc intact so tooling can still classify the classes.

### 4. Package Naming

All application code lives under `com.optage.kopt`. Sub-packages represent sub-systems:

- `batch` -- Top-level batch orchestration
- `bp` -- SOD (Send-Out-Data) processing
- `dto` -- Data transfer objects
- `ekk` -- External subsystem integration
- `esc`, `kkw` -- Additional service/trigger modules

### 5. Build and Test

```bash
# Build the project
mvn clean package

# Run tests
mvn test
```

The only test in the repo is `JKKHakkoSODCCTest` in `src/test/java`. It uses JUnit 4 (`@Test`, `org.junit.Assert`) and is currently a placeholder (`assertTrue(true)`).

---

## What to Do Next

1. Read the **[Overview](overview.md)** for the full technology stack and module descriptions.
2. Pick a subsystem to work on and read its module page in the wiki.
3. Look at the corresponding Java class in `src/main/java` -- start with `KKPRC14901` and `JKKHakkoSODCC` if you're not sure where to begin.
4. Replace a stub with real logic, then run `mvn test` to verify nothing broke.