# Getting Started

Welcome to the **Optage Mini Fixture** codebase — a multi-module Java project used as a testbed for the SPEC-SCOPED-WIKI analysis tooling. This project simulates a real-world Java EE application that combines batch processing, web pages (JSP), JavaServer Faces, and EJBs.

## What This Project Does

This is a **fixture codebase** designed to exercise code analysis, indexing, and documentation tooling across a realistic Java EE codebase. It contains:

- **Core Java service classes** in `src/main/java/com/optage/kopt/` — a compact domain covering batch processing, business processing, DTOs, and various service packages.
- **Web-layer fixture** in `full-fixture-codebase/` — a full Java EE web app with JSP pages, JSF configuration, Futurity view definitions, and EJB deployment descriptors.
- **Multiple XML test modules** (`xml-*`) — self-contained modules that test edge cases like malformed XML, Japanese XML element names, external class references, CSS-only XML, and multi-pattern web descriptors.

## Recommended Reading Order

Read these wiki pages in order to get oriented quickly:

1. **[Overview](../overview.md)** — The big-picture architecture and design goals of the project.
2. **[Root Module](../root.md)** — The entry point to the codebase and how the main module is structured.
3. **Package docs** — Dive into `com.optage.kopt.bp` and `eo.web` package pages for domain and web-layer specifics.

Once comfortable, consult the package-level wiki pages for `com.optage.kopt.batch`, `com.optage.kopt.dto`, `eo.web.webview`, and the `javax.faces` / `eo.web` sub-modules.

## Key Entry Points

Start with these classes — they are the most connected and referenced in the codebase:

### `ACA001SFBean` (6 connections) — most referenced

Located in `full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java`, this is the central JSF backing bean used across JSP pages, view definitions, and faces-config. Understanding this class gives you a grasp of how the web layer connects data to the UI.

Key entry points across the codebase:

| Class | File | Role |
|-------|------|------|
| `ACA001SFBean` | `full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java` | Central JSF backing bean |
| `JKKBpServiceBase` | `src/main/java/com/optage/kopt/bp/JKKBpServiceBase.java` | Base class for business processing services |
| `JKKHakkoSODCC` | `src/main/java/com/optage/kopt/bp/JKKHakkoSODCC.java` | Core dispatch class — calls send and validation logic |
| `KKPRC14901` | `src/main/java/com/optage/kopt/batch/KKPRC14901.java` | Primary batch processing entry point |
| `JKKSodRequestDTO` | `src/main/java/com/optage/kopt/dto/JKKSodRequestDTO.java` | Request data transfer object |
| `JKKSodResponseDTO` | `src/main/java/com/optage/kopt/dto/JKKSodResponseDTO.java` | Response data transfer object |

### Architecture at a glance

```mermaid
flowchart TD
    A["JSP Pages"] --> B["ACA001SFBean"]
    B --> C["ACA001SFLogic"]
    C --> D["Business Logic"]
    B --> E["View Layer"]
    D --> F["BP Package"]
    D --> G["Batch Package"]
    D --> H["DTO Package"]
    D --> I["EKK/ESC/KKW Packages"]
    E --> J["XML View Defs"]
    J --> K["SERVICEFORM"]
    K --> B
```

## Project Structure

The project is a Maven multi-module build. The layout mirrors a real Java EE application with several distinct areas:

```mermaid
flowchart LR
    A["src/main/java"] --> B["com.optage.kopt.batch"]
    A --> C["com.optage.kopt.bp"]
    A --> D["com.optage.kopt.dto"]
    A --> E["com.optage.kopt.ekk"]
    A --> F["com.optage.kopt.esc"]
    A --> G["com.optage.kopt.kkw"]
    A --> H["com.optage.kopt.unrelated"]
    I["full-fixture-codebase/"] --> J["eo.web.webview"]
    I --> K["WEB-INF/web.xml"]
    I --> L["futurity-app"]
    M["Test source"] --> N["src/test/java"]
    O["XML modules"] --> P["xml-build-excluded/"]
    O --> Q["xml-faces-config/"]
    O --> R["xml-futurity-view-def/"]
    O --> S["xml-japanese-elements/"]
    O --> T["xml-web-xml-multi-pattern/"]
```

### Module breakdown

| Path | Purpose |
|------|---------|
| `src/main/java/com/optage/kopt/` | Core Java domain — batch jobs, business processing, DTOs, services |
| `src/test/java/com/optage/kopt/` | JUnit tests (e.g. `JKKHakkoSODCCTest`) |
| `full-fixture-codebase/` | Full web-layer fixture with JSP, JSF, Servlet, and EJB config |
| `xml-build-excluded/` | XML modules that should be excluded from the build |
| `xml-faces-config/` | JSF faces-config with managed bean definitions |
| `xml-futurity-view-def/` | Futurity framework view definitions |
| `xml-japanese-elements/` | XML with Japanese-tag names (testing non-ASCII XML support) |
| `xml-web-xml-multi-pattern/` | Standard `web.xml` with filter, servlet, and listener |
| `xml-sun-ejb-jar/` | Sun application server EJB deployment descriptor |
| `xml-malformed/` | Intentionally broken XML (testing parser resilience) |
| `xml-unresolved-fqn/` | XML referencing external/missing classes |
| `xml-probe/` | Probe-mode configuration modules |
| `xml-css-class-only/` | XML containing only CSS class attributes |

### Core Java packages

```
src/main/java/com/optage/kopt/
├── batch/            # Batch job classes (KKPRC14901, KKPRC24901, KKPRC34901)
├── bp/               # Business processing services (JKKBpServiceBase, JKKHakkoSODCC, JKKSodSendCC)
├── dto/              # Data transfer objects (JKKSodRequestDTO, JKKSodResponseDTO)
├── ekk/              # Contract processing (EKK0301A010, EKK0301A020)
├── esc/              # Service control (ESC0101B001)
├── kkw/              # Batch trigger (KKW0100B001)
└── unrelated/        # Isolated class for testing (XYZ99999Unrelated)
```

## Configuration

### Build configuration

| File | Controls |
|------|----------|
| `pom.xml` | Root Maven POM — defines the `optage-mini-fixture` project (groupId `com.optage.kopt`, artifactId `optage-mini-fixture`) |
| `xml-build-excluded/pom.xml` | Sub-module POM for excluded XML modules |

### Web application configuration

| File | Role |
|------|------|
| `full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml` | Full servlet deployment descriptor — defines `X33JVRequestEncodingSjisFilter` and `FacesServlet` |
| `xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml` | Multi-pattern web descriptor — adds `X33AppContextListener` |
| `xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml` | JSF managed beans (`aca001Bean` in request scope, `aca002Bean` in session scope) |

### Application configuration

| File | Role |
|------|------|
| `xml-build-excluded/src/config/real-config.xml` | Root config referencing `eo.web.RealClass` |
| `xml-build-excluded/src/app/real-config.xml` | App-level config referencing `eo.web.RealClassInApp` |
| `xml-futurity-view-def/src/futurity-app/webA/env/view/def/WEBGAMEN_ACA001010PJP.xml` | Futurity screen definition — wires `ACA001SFBean` as the SERVICEFORM and `ACA001SFLogic` as the business logic |
| `xml-sun-ejb-jar/koptBp/ejbModule/META-INF/sun-ejb-jar.xml` | Sun EJB JNDI bindings for `ACSV0001Flow` and `ACSV0002Flow` |
| `xml-probe/src/app/real-config.xml` | Probe-mode configuration root |
| `xml-unresolved-fqn/src/config/external-refs.xml` | Config referencing external third-party classes |

### Data flow

```mermaid
sequenceDiagram
    participant CLT as Client
    participant JSP as JSP Page
    participant BEAN as ACA001SFBean
    participant BL as ACA001SFLogic
    participant BP as Business Logic
    participant XML as View Def XML
    CLT->>JSP: HTTP request
    JSP->>BEAN: Invoke backing bean
    BEAN->>BL: Delegate to logic
    BL->>BP: Execute business rules
    BP-->>BL: Return result
    BL-->>BEAN: Return data
    BEAN-->>JSP: Populate model
    JSP-->>CLT: Render response
    XML->>BEAN: Bind via SERVICEFORM
```

## Common Patterns

### Package-by-feature

Java classes are organized under `com.optage.kopt` by functional area:

- **`batch/`** — Standalone batch jobs (`KKPRC*.java`). Each batch class can delegate to other packages.
- **`bp/`** — Business processing services. `JKKBpServiceBase` is the abstract base; concrete classes like `JKKHakkoSODCC` orchestrate send/validation logic.
- **`dto/`** — Simple POJOs for data exchange (`JKKSodRequestDTO`, `JKKSodResponseDTO`).
- **`ekk/`, `esc/`, `kkw/`** — Domain-specific service packages (contract, service control, batch trigger).

### Batch-to-service delegation

Batch classes instantiate and call into service classes, which in turn may call into domain services:

```java
// KKPRC14901 calls into EKK processing
public void run() { new EKK0301A010().process(); }

// JKKHakkoSODCC dispatches to send and validation
public void dispatch() { new JKKSodSendCC().send(); }
public void validate() { new KKPRC14901().check(); }
```

### Web layer: Bean → Logic → XML-driven

The web layer follows a Futurity-driven pattern:

1. **JSP pages** import and use backing beans (`ACA001SFBean`) via `<jsp:useBean>` and `<%@ page import %>`.
2. **Backing beans** delegate to logic classes (`ACA001SFLogic`).
3. **View definitions** (`WEBGAMEN_ACA001010PJP.xml`) wire beans, logic, and actions declaratively via `<SERVICEFORM>` and `<BL>` elements.
4. **faces-config.xml** registers managed beans with their scopes.

### XML-driven configuration

This project uses XML extensively for configuration and wiring. The `config` and `SCREEN` XML formats use `class` and `bean` attributes to wire Java classes declaratively. A typical config looks like:

```xml
<config>
  <BL class="eo.web.RealClass"/>
</config>
```

And a Futurity view definition:

```xml
<SCREEN id="ACA001010P">
  <BL class="eo.web.webview.ACA001SF.ACA001SFLogic"/>
  <SERVICEFORM bean="eo.web.webview.ACA001SF.ACA001SFBean">
    <BUTTON class="eo.web.webview.ACA001SF.ACA001SFAction"/>
  </SERVICEFORM>
</SCREEN>
```

### Japanese XML elements

The `xml-japanese-elements/` module demonstrates that the parser handles non-ASCII element names. A screen definition uses Japanese tags:

```xml
<画面定義 id="ACA001">
  <項目 class="eo.web.webview.ACA001SF.ACA001SFLogic" name="ロジック"/>
  <フォーム bean="eo.web.webview.ACA001SF.ACA001SFBean"/>
</画面定義>
```

### Resilience to malformed XML

The `xml-malformed/` module contains intentionally broken XML to test parser resilience — unclosed tags, missing attributes, and trailing content in the root element.

## Next Steps

- Read the **[overview](../overview.md)** for the full architectural picture.
- Explore the **[root module](../root.md)** documentation for package-level detail.
- Run `mvn test` in `full-fixture-codebase/` to verify the test setup.
- Check `xml-build-excluded/` to understand which modules are intentionally excluded from the main build.