# Business Logic — KKW22101SF01DBean.addListDataInstance() [32 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW22101SF.KKW22101SF01DBean` |
| Layer | UI Data Bean (webview layer — X33 framework data binding component) |
| Module | `KKW22101SF` (Package: `eo.web.webview.KKW22101SF`) |

## 1. Role

### KKW22101SF01DBean.addListDataInstance()

This method is a **polymorphic data-instance factory** within the X33 web framework's data binding architecture. It creates a new typed bean instance for a specific repeating (repeatable) form field and appends it to the corresponding list field on the view bean. In the business domain of K-Opticom's telecom service management system, this method handles **two distinct service-type categories**: (1) Migration reason codes (`異動理由コード`) — used to record the reason for a customer's contract transfer or migration, and (2) Option service contract numbers (`オプションサービス契約番号`) — used to track optional add-on service contracts attached to a primary service order.

The method implements the **dispatch/routing pattern**: it examines the incoming `key` string to determine which of the two list-backed repeating fields the caller is requesting, then branches into the appropriate factory branch. Each branch lazily initializes its target list (creating an empty list if the instance is still null) and adds a new `X33VDataTypeStringBean` element, returning the zero-based index of the newly appended element. This enables dynamic row insertion in repeatable table sections of web UI screens, where users can add arbitrary numbers of migration reasons or optional service contracts.

As a **shared utility** within the `KKW22101SF01DBean` data bean, this method serves all screens backed by this bean (the KKW22101SF service function), providing the standard X33 mechanism for runtime list expansion. It is not called from external screens or CBS classes directly — it is invoked internally by the bean's own lifecycle methods (e.g., during data binding refresh or row iteration).

## 2. Processing Pattern (Detailed Business Logic)

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

    START --> CheckNull{"key == null?"}
    CheckNull -->|true| RET_NULL1(["return -1"])
    CheckNull -->|false| CheckKey{"key value"}

    CheckKey -->|"異動理由コード"| CheckIgoNull{"ido_rsn_cd_list == null?"}
    CheckKey -->|"オプションサービス契約番号"| CheckOpNull{"op_svc_kei_no_list == null?"}
    CheckKey -->|"other"| RET_DEFAULT(["return -1"])

    CheckIgoNull -->|true| InitIgo["ido_rsn_cd_list = new X33VDataTypeList()"]
    CheckIgoNull -->|false| CreateIgoBean["tmpBean = new X33VDataTypeStringBean()"]
    InitIgo --> CreateIgoBean

    CreateIgoBean --> AddIgo["ido_rsn_cd_list.add(tmpBean)"]
    AddIgo --> RET_Igo["return ido_rsn_cd_list.size() - 1"]

    CheckOpNull -->|true| InitOp["op_svc_kei_no_list = new X33VDataTypeList()"]
    CheckOpNull -->|false| CreateOpBean["tmpBean = new X33VDataTypeStringBean()"]
    InitOp --> CreateOpBean

    CreateOpBean --> AddOp["op_svc_kei_no_list.add(tmpBean)"]
    AddOp --> RET_Op["return op_svc_kei_no_list.size() - 1"]

    RET_Igo --> END_NODE(["End"])
    RET_Op --> END_NODE
    RET_NULL1 --> END_NODE
    RET_DEFAULT --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | A Japanese field name string that identifies which repeating (multi-row) form field to add a new element to. It acts as a **routing discriminator** — the value determines which list branch is taken. Valid values are `"異動理由コード"` (Migration Reason Code) and `"オプションサービス契約番号"` (Option Service Contract Number). Any other value (or `null`) results in a `-1` return, indicating no element was added. |
| — | `ido_rsn_cd_list` | `X33VDataTypeList` | Instance field — the list backing the migration reason code repeating field. Read to check for null, then used for element insertion and size retrieval. |
| — | `op_svc_kei_no_list` | `X33VDataTypeList` | Instance field — the list backing the option service contract number repeating field. Read to check for null, then used for element insertion and size retrieval. |

## 4. CRUD Operations / Called Services

This method performs **no database operations** and **no service component (SC/CBS) calls**. It operates entirely within the UI data bean layer, manipulating in-memory data structures.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| (N/A) | `(none)` | — | — | This method is a pure in-memory list factory. It creates and manages `X33VDataTypeStringBean` objects within the UI bean's list fields. No data is persisted to or retrieved from any database table. |

## 5. Dependency Trace

No external callers were found in the codebase. This method is an **internal utility** of the `KKW22101SF01DBean` data bean, consumed by the bean's own lifecycle (e.g., UI row iteration, dynamic row addition on the web screen) rather than being directly invoked by external screens or CBS layers.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | *(none found — internal method)* | *(internal to bean lifecycle)* | *(none)* |

## 6. Per-Branch Detail Blocks

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

> Guard clause: if the caller passes `null` as the key, return `-1` immediately.
> Japanese comment: `nullの場合、-1で返す。` → "If null, return -1."

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` |

**Block 2** — ELSE-IF `(key.equals("異動理由コード"))` (L1588)

> Dispatches to the migration reason code list branch. Creates a new String-type bean instance and appends it to `ido_rsn_cd_list`.
> Japanese comments:
> - `各繰り返し項目の固定要素数指定への処理を行う。` → "Performs processing for specifying a fixed number of elements in each repeating item."
> - `配置項目 "異動理由コード"(String型。項目ID:ido_rsn_cd)` → "Layout item 'Migration Reason Code' (String type. Item ID: ido_rsn_cd)"

| # | Type | Code |
|---|------|------|
| 1 | CONDITION | `key.equals("異動理由コード")` // Migration Reason Code check |

**Block 2.1** — IF (nested within Block 2) `(ido_rsn_cd_list == null)` (L1589)

> Lazy initialization: if the migration reason code list has not yet been instantiated, create a new empty list.
> Japanese comment: `リストがnullの場合、新しい空のインスタンスを生成する` → "If the list is null, generate a new empty instance."

| # | Type | Code |
|---|------|------|
| 1 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` |

**Block 2.2** — EXEC (nested within Block 2) (L1594)

> Create a new String-typed data bean instance for the repeating field element.
> Japanese comment: `データデータタイプビューン型で指定したデータタイプビューンのインスタンスを生成する。` → "Generate an instance of the data type view specified by the data type view bean type."
> Japanese comment: `なお、データタイプビューンの項目初期値設定は、各データビューン内で定義` → "Note that item initial value settings for the data type view are defined within each data bean."

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` |
| 2 | CALL | `ido_rsn_cd_list.add(tmpBean);` // Append the new bean to the list |
| 3 | RETURN | `return ido_rsn_cd_list.size() - 1;` // Return zero-based index of the added element |

**Block 3** — ELSE-IF `(key.equals("オプションサービス契約番号"))` (L1599)

> Dispatches to the option service contract number list branch. Creates a new String-type bean instance and appends it to `op_svc_kei_no_list`.
> Japanese comment: `配置項目 "オプションサービス契約番号"(String型。項目ID:op_svc_kei_no)` → "Layout item 'Option Service Contract Number' (String type. Item ID: op_svc_kei_no)"

| # | Type | Code |
|---|------|------|
| 1 | CONDITION | `key.equals("オプションサービス契約番号")` // Option Service Contract Number check |

**Block 3.1** — IF (nested within Block 3) `(op_svc_kei_no_list == null)` (L1600)

> Lazy initialization: if the option service contract number list has not yet been instantiated, create a new empty list.
> Japanese comment: `リストがnullの場合、新しい空のインスタンスを生成する` → "If the list is null, generate a new empty instance."

| # | Type | Code |
|---|------|------|
| 1 | SET | `op_svc_kei_no_list = new X33VDataTypeList();` |

**Block 3.2** — EXEC (nested within Block 3) (L1605)

> Create a new String-typed data bean instance and append it to the option service contract number list.
> Japanese comment: `データデータタイプビューン型で指定したデータタイプビューンのインスタンスを生成する。` → "Generate an instance of the data type view specified by the data type view bean type."
> Japanese comment: `なお、データタイプビューンの項目初期値設定は、各データビューン内で定義` → "Note that item initial value settings for the data type view are defined within each data bean."

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` |
| 2 | CALL | `op_svc_kei_no_list.add(tmpBean);` // Append the new bean to the list |
| 3 | RETURN | `return op_svc_kei_no_list.size() - 1;` // Return zero-based index of the added element |

**Block 4** — ELSE (implicit, L1609)

> Fallback: no matching key was found. Return `-1` to indicate the requested field is not supported.
> Japanese comment: `該当する項目がない場合、-1を返す` → "If no corresponding item exists, return -1."

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `異動理由コード` | Field (Japanese) | Migration Reason Code — identifies the reason why a customer's contract was transferred or migrated (e.g., service type change, location move, plan switch) |
| `ido_rsn_cd` | Field | Short name for Migration Reason Code — the item ID used internally within the X33 data binding framework |
| `オプションサービス契約番号` | Field (Japanese) | Option Service Contract Number — the identifier for an optional add-on service contract attached to a primary telecom service order |
| `op_svc_kei_no` | Field | Short name for Option Service Contract Number — the item ID used internally within the X33 data binding framework |
| X33VDataTypeList | Technical | X33 framework list container — a typed list that holds multiple instances of a repeating form field element |
| X33VDataTypeStringBean | Technical | X33 framework string data bean — a typed wrapper bean holding a single string value, used as the element type for the above list |
| X33VViewBaseBean | Technical | Base class in the X33 framework — the parent class from which KKW22101SF01DBean extends, providing web view data binding infrastructure |
| X33VListedBeanInterface | Technical | X33 interface — enables the bean to participate in list-based UI components (repeatable rows) |
| X33SException | Technical | X33 framework exception — the checked exception type thrown by X33 data binding methods |
| KKW22101SF | Module | K-Opticom Service Function 22101 — a telecom service management screen module within the web application |
| 繰り返し項目 | Business term (Japanese) | Repeating item / multi-row field — a form section that can contain an arbitrary number of rows (e.g., a table of migration reasons) |
| 固定要素数指定 | Business term (Japanese) | Fixed element count specification — the mechanism for defining how many repeating elements a form field supports |