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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW01034SF.KKW01034SF01DBean` |
| Layer | View Bean / Web UI (Package: `eo.web.webview.KKW01034SF`) |
| Module | `KKW01034SF` (Package: `eo.web.webview.KKW01034SF`) |

## 1. Role

### KKW01034SF01DBean.addListDataInstance()

This method is a **dynamic list factory** for the view layer data bean in the KKW01034SF screen module. Its business purpose is to **generate and manage runtime list instances** for repeatable (iterative) UI fields — specifically the "Disruption Reason Code" (移動理由コード) list item. In the telecom service contract domain, this supports screens where users need to add multiple disruption reasons for a single service contract line item, such as when a fiber-to-the-home (FTTH) or other telecom service is temporarily suspended or rerouted due to maintenance, equipment failure, or natural disaster.

The method implements a **discriminated factory pattern** (if-else dispatch) where the `key` parameter (a Japanese-display label string) determines which internal list field to target. Each recognized key maps to a specific strongly-typed bean list (e.g., `X33VDataTypeStringBean` inside an `X33VDataTypeList`), and the method lazily initializes the list container if it has not yet been created. This is part of the **Fujitsu Futurity X33V web framework** view bean infrastructure, which uses generic typed-list beans to represent repeating table rows on HTML forms.

Within the larger system, this method serves as a **shared UI data helper** called by screen beans (via the overridden parent class or directly) to dynamically expand list data structures during form rendering and postback processing. The caller passes a human-readable display label (e.g., "移動理由コード") and the method returns the zero-based index of the newly appended list element, enabling the caller to immediately reference or populate the new row.

The method has **two logical branches** in the KKW01034SF01DBean implementation: (1) the null-key guard, which short-circuits and returns -1; (2) the "Disruption Reason Code" case, which ensures the `ido_rsn_cd_list` is initialized and appends a new string-type bean, then returns the index of the newly added element.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance key"])

    START --> CheckNull["key is null"]

    CheckNull -->|true| RetNeg1["Return -1"]
    CheckNull -->|false| CheckKey["key equals 移動理由コード"]

    CheckKey -->|true| CheckList["ido_rsn_cd_list is null"]
    CheckKey -->|false| RetNeg2["Return -1"]

    CheckList -->|true| InitList["ido_rsn_cd_list = new X33VDataTypeList"]
    CheckList -->|false| CreateBean["Create X33VDataTypeStringBean tmpBean"]

    InitList --> CreateBean
    CreateBean --> AddBean["ido_rsn_cd_list.add tmpBean"]

    AddBean --> RetIndex["Return size - 1"]
    RetNeg1 --> END(["END"])
    RetNeg2 --> END
    RetIndex --> END
```

**Note:** The `KKW01034SFBean` parent class overrides `addListDataInstance` with additional branches (e.g., for "//"-prefixed keys delegating to `super.addListDataInstance(key)`, and for "顧客契約引継リスト" and "キャンペーン一覧" keys). The version documented here is the one defined directly in `KKW01034SF01DBean`, which specializes handling for the "Disruption Reason Code" list item only.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The human-readable display label of a repeatable list item on the form. In this method's scope, the recognized value is `"移動理由コード"` (Disruption Reason Code), which identifies the list field that stores disruption/reason codes associated with a service contract. The caller passes this display label to request a new row in that specific list. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `ido_rsn_cd_list` | `X33VDataTypeList` | The list container for disruption reason codes (移動理由コード). Each element is an `X33VDataTypeStringBean` holding a single disruption reason string. Lazily initialized on first use. |

## 4. CRUD Operations / Called Services

This method performs **no external service calls** (no SC/CBS invocations, no database reads/writes). It operates entirely within the view bean's in-memory data structures.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| N/A | *None* | — | — | This method is a pure in-memory factory. It does not invoke any service components, data access beans, or database operations. The list data it manages is eventually submitted back to the server during form postback, where the screen's business logic layer performs the actual CRUD against the database. |

**Classification rationale:** The method only manipulates local `X33VDataTypeList` and `X33VDataTypeStringBean` objects — these are framework-provided generic typed containers that hold form data for the JSF rendering layer. No SC (Service Component), CBS (Component Bean Service), or entity/table operations occur within this method's scope.

## 5. Dependency Trace

This method is defined in `KKW01034SF01DBean` and also overridden in the parent class `KKW01034SFBean`. Many other screen beans in the codebase (e.g., `FUW00901SFBean`, `FUW00912SFBean`, `KKW00825SFBean`, etc.) invoke `super.addListDataInstance(key)`, which chains to this method when the parent class does not override it, or to the parent's more comprehensive version when it does.

Within the `KKW01034SF` module itself, the direct callers are:

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKW01034SF (KKW01034SFBean) | `KKW01034SFBean.addListDataInstance(key)` → delegates to `super.addListDataInstance(key)` | — |
| 2 | External: `FUW00901SFBean` | `FUW00901SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 3 | External: `FUW00912SFBean` | `FUW00912SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 4 | External: `FUW00914SFBean` | `FUW00914SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 5 | External: `FUW00916SFBean` | `FUW00916SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 6 | External: `FUW00917SFBean` | `FUW00917SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 7 | External: `FUW00919SFBean` | `FUW00919SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 8 | External: `FUW00926SFBean` | `FUW00926SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 9 | External: `FUW00927SFBean` | `FUW00927SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 10 | External: `FUW00931SFBean` | `FUW00931SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 11 | External: `FUW00942SFBean` | `FUW00942SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 12 | External: `FUW00946SFBean` | `FUW00946SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 13 | External: `FUW00947SFBean` | `FUW00947SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 14 | External: `FUW00957SFBean` | `FUW00957SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |
| 15 | External: `FUW00959SFBean` | `FUW00959SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` | — |

**Note:** The method is called via `super.addListDataInstance(key)` inheritance chains. When `KKW01034SFBean` (the parent) overrides this method with additional branches, the call dispatches to the parent's version rather than `KKW01034SF01DBean`'s version. The `KKW01034SF01DBean` version is the most specialized — it handles only the "Disruption Reason Code" case.

## 6. Per-Branch Detail Blocks

**Block 1** — IF `(key == null)` (L687)

> Null-guard: If the caller passes a null key, the method short-circuits and returns -1 to indicate no element was added. This prevents NullPointerException on subsequent `key.equals()` calls.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // If key is null, return -1 (nullの場合、-1で返す。) |

**Block 2** — ELSE-IF `(key.equals("移動理由コード"))` (L693) [移動理由コード = Disruption Reason Code]

> Business description: Handles the "Disruption Reason Code" repeatable list item. This list stores disruption/reason codes for a service contract — e.g., why a telecom service was suspended or rerouted. Each entry is a single string value wrapped in an `X33VDataTypeStringBean`, stored in the `ido_rsn_cd_list` container.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("移動理由コード")` // Iterative item fixed element number specification processing. Disruption Reason Code (String type, Item ID: ido_rsn_cd) (各繰り返し項目の固定要素数指定への処理を行う。配列項目 "移動理由コード"(String型。項目ID:ido_rsn_cd)) |

**Block 2.1** — IF `(ido_rsn_cd_list == null)` (L694)

> If the list container has not yet been initialized, create a new empty `X33VDataTypeList` to hold disruption reason code entries.

| # | Type | Code |
|---|------|------|
| 1 | SET | `ido_rsn_cd_list = new X33VDataTypeList()` // If the list is null, generate a new empty instance (リストがnullの場合、新しい空のインスタンスを生成する) |

**Block 2.2** — Sequential processing (unconditional within the key-matching branch) (L698)

> Create a new typed string bean instance and append it to the disruption reason code list.

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean()` // Generate an instance of the specified data type bean using the data type bean type. The data type bean's item initial value setting is defined internally in each data bean. (データタイプビューン型で指定したデータタイプビューンのインスタンスを生成する。なお、データタイプビューンの項目初期値設定は、各データビューン内部で定義) |
| 2 | EXEC | `ido_rsn_cd_list.add(tmpBean)` // Append the new bean to the list |
| 3 | RETURN | `return ido_rsn_cd_list.size() - 1;` // Return the index of the newly added element |

**Block 3** — ELSE (implicit fall-through, no matching key) (L700)

> No matching list item key was found. Return -1 to signal that the requested item is not registered.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // If there is no corresponding item, return -1 (該当する項目がない場合、-1を返す) |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `ido_rsn_cd_list` | Field | Disruption Reason Code List — an in-memory list (`X33VDataTypeList`) where each element is a string bean holding a single disruption/reason code value associated with a service contract line item. |
| `ido_rsn_cd` | Field | Disruption Reason Code (Item ID) — the internal identifier for the disruption reason code field, derived from the Japanese label "移動理由コード". |
| 移動理由コード | Field | Disruption Reason Code — the Japanese display label for the repeatable list item that captures reasons for service disruption (e.g., maintenance, equipment failure, natural disaster). |
| `X33VDataTypeList` | Type | Fujitsu Futurity X33V framework generic typed list container — a collection of elements of a single type, used for repeatable UI fields (e.g., table rows on a form). |
| `X33VDataTypeStringBean` | Type | Fujitsu Futurity X33V framework typed bean for string values — wraps a single string value and provides getter/setter methods; used as the element type for string-based repeatable list items. |
| `X33VDataTypeBeanInterface` | Interface | Fujitsu X33V framework interface for typed data beans — this class implements it to provide data binding for JSF view components. |
| `X33VListedBeanInterface` | Interface | Fujitsu X33V framework interface for beans that contain list data — enables the framework to iterate and render repeating UI sections (e.g., data tables). |
| `X33SException` | Type | Fujitsu X33S framework exception type — thrown for service-layer errors; the method declares it in its throws clause. |
| KK | Prefix | K-Opticom — the telecommunications service provider domain. |
| SF | Suffix | Screen — a web screen module (e.g., KKW01034SF is the screen module ID). |
| Bean | Pattern | Data transfer / view bean — a Java class that holds UI state and form data, acting as the model in the JSF MVC pattern. |