# Business Logic — KKW01031SF01DBean.addListDataInstance() [21 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW01031SF.KKW01031SF01DBean` |
| Layer | Data Bean / View Layer (Web Client DBean) |
| Module | `KKW01031SF` (Package: `eo.web.webview.KKW01031SF`) |

## 1. Role

### KKW01031SF01DBean.addListDataInstance()

This method is a framework-level list data factory method within the Fujitsu Futurity X33 web framework. It implements the `X33VListedBeanInterface` contract by creating and appending new instances of typed data beans into a list-based field at runtime. Specifically, it handles the `"異動理由コード"` (Reason Code for Change/Movement) list item — when invoked with that key, it ensures the `ido_rsn_cd_list` field is initialized (if null) and appends a fresh `X33VDataTypeStringBean` to it, returning the zero-based index of the newly added element. The method follows a routing/dispatch pattern: it evaluates the `key` parameter against known item names and routes to the appropriate list-initialization branch. As a shared utility method on a Data Bean (DBean), it is intended to be called by the X33 framework during page rendering or by subclass beans that delegate back via `super.addListDataInstance(key)`. If the key does not match any known item (or is null), the method returns -1 to signal no action was taken.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance String key"])
    CHECK_NULL{key is null}
    RETURN_NULL["Return -1 - Key is null"]
    CHECK_KEY{key equals 異動理由コード}
    CHECK_LIST{ido_rsn_cd_list is null}
    INIT_LIST["ido_rsn_cd_list = new X33VDataTypeList()"]
    CREATE_BEAN["tmpBean = new X33VDataTypeStringBean()"]
    ADD_LIST["ido_rsn_cd_list.add(tmpBean)"]
    RETURN_IDX["Return ido_rsn_cd_list.size() - 1"]
    RETURN_DEFAULT["Return -1 - No matching key"]
    END_NODE(["Return / Next"])

    START --> CHECK_NULL
    CHECK_NULL -->|Yes| RETURN_NULL
    RETURN_NULL --> END_NODE
    CHECK_NULL -->|No| CHECK_KEY
    CHECK_KEY -->|Yes| CHECK_LIST
    CHECK_KEY -->|No| RETURN_DEFAULT
    RETURN_DEFAULT --> END_NODE
    CHECK_LIST -->|Yes| INIT_LIST
    CHECK_LIST -->|No| CREATE_BEAN
    INIT_LIST --> CREATE_BEAN
    CREATE_BEAN --> ADD_LIST
    ADD_LIST --> RETURN_IDX
    RETURN_IDX --> END_NODE
```

**CRITICAL — Constant Resolution:**
The key comparison uses a literal Japanese string `"異動理由コード"` (Reason Code for Change/Movement) — this is a hardcoded item identifier, not a constant reference. No external constant file lookup is needed.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The item name (field identifier) that specifies which list-type data field should receive a new element. Currently, only the literal value `"異動理由コード"` (Reason Code for Change/Movement) is recognized. This value determines which internal list field is targeted for element addition. |
| — | `ido_rsn_cd_list` | `X33VDataTypeList` | Instance field read/written. The list holding `X33VDataTypeStringBean` elements for movement/change reason codes. May be `null` on first invocation, requiring lazy initialization. |

## 4. CRUD Operations / Called Services

This method performs **no database or service component calls**. All operations are in-memory data bean manipulation within the view layer:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| — | (none) | — | — | In-memory list bean creation only; no SC/CBS/DAO layer involvement |

## 5. Dependency Trace

This method is a framework-level data bean method that is not directly invoked by any named screen or batch in the codebase. It is part of the X33 view layer's `X33VListedBeanInterface` contract. The following subclasses override and delegate to this method via `super.addListDataInstance(key)`:

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Framework: X33ViewLayer | `X33VListedBeanInterface.addListDataInstance(key)` (interface contract) | (none — in-memory only) |
| 2 | FUW00912SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 3 | FUW00926SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 4 | FUW00959SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 5 | FUW00964SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 6 | FUW00927SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 7 | FUW00901SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 8 | FUW00919SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 9 | FUW00931SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 10 | FUW00917SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 11 | FUW00907SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |
| 12 | FUW00957SFBean | `FUW010D010001` (example) -> `addListDataInstance` -> `super.addListDataInstance(key)` -> `KKW01031SF01DBean.addListDataInstance` | (none — in-memory only) |

Note: Many FUW (Fujitsu Unified Web) screen beans implement `addListDataInstance` with their own custom branches and delegate unrecognized keys back to `super.addListDataInstance(key)`, which ultimately reaches this method. The X33 framework may also invoke this method directly during page data initialization.

## 6. Per-Branch Detail Blocks

> Each branch of the control flow is displayed as a hierarchical block structure.

**Block 1** — [IF] `(key == null)` (L615)

> If the key parameter is null, return -1 immediately. This is a null-guard that prevents NPE when checking the key value later.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // nullの場合約、-1で返す。 (Returns -1 if null.) |

**Block 2** — [ELSE-IF] `(key.equals("異動理由コード")) [key equals "異動理由コード" (Reason Code for Change/Movement)]` (L620)

> Handles the specific list item for "Reason Code for Change/Movement" — a string-type field identified by item ID `ido_rsn_cd`. Lazily initializes the list if needed, creates a new typed string bean, appends it, and returns the zero-based index of the new element.

| # | Type | Code |
|---|------|------|
| 1 | IF | `if (ido_rsn_cd_list == null)` // リストがnullの場合、新しい空のインスタントを生成する (If list is null, generate a new empty instance.) [L621] |
| 1.1 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` // リスト初期化 (Initialize list) [L622] |
| 2 | EXEC | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // データタイプビーン型のインスタントを生成する。データタイプビーンの項目初期値設定は、各データビーン内で定義 (Generate instance of data type bean. Data type bean field initial value settings are defined within each data bean.) [L624] |
| 3 | EXEC | `ido_rsn_cd_list.add(tmpBean);` // リストに追加 (Add to list) [L625] |
| 4 | RETURN | `return ido_rsn_cd_list.size() - 1;` // 追加された要素のインデックス番号を返す (Return the index of the added element) [L626] |

**Block 3** — [ELSE (implicit default)] (L629)

> If the key does not match any recognized item name, return -1 to indicate no matching item was found.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // 該当する項目がない場合、-1を返す (Returns -1 if no matching item) [L629] |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `異動理由コード` | Field | Reason Code for Change/Movement — the reason code that explains why a service contract line item was modified, moved, or transferred. Stored as a string-type list item. |
| `ido_rsn_cd_list` | Field | IDO Reason Code List — the internal list field (`X33VDataTypeList`) that holds multiple reason code entries for change/movement records. Each entry is a `X33VDataTypeStringBean`. |
| `ido_rsn_cd` | Field | IDO Reason Code — item identifier for the reason code of a service contract line item change/movement. The prefix `ido` likely stands for "Iodo" (異動, change/movement in Japanese). |
| `X33VDataTypeList` | Type | Fujitsu X33 framework generic list container for list-type data bean items. Holds instances of typed beans. |
| `X33VDataTypeStringBean` | Type | Fujitsu X33 framework data bean wrapping a single String value with validation and lifecycle support. |
| `X33VListedBeanInterface` | Interface | X33 framework interface that data beans must implement to support list-type fields (repeating rows). Provides methods like `addListDataInstance`, `removeListDataInstance`, `listKoumokuIds`. |
| `DBean` | Abbreviation | Data Bean — a view-layer class in the X33 framework that holds and manages data for a single screen, implementing data type interfaces for type-safe field handling. |
| `X33SException` | Type | X33 framework checked exception for service-layer errors that may be thrown during data bean operations. |
| KK | Prefix | K-Opticom — the telecommunications company whose system this code belongs to. |
| KKW01031SF | Module | Service Screen module identifier — likely a specific screen flow for service contract management (SF = Service Function). |
| 顧客契約引継リスト | Field | Customer Contract Succession List — a list item whose data type bean class is `KKW01031SF01DBean`. |