# Business Logic — KKW22501SFBean.addListDataInstance() [49 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW22501SF.KKW22501SFBean` |
| Layer | Web/View Controller (Web Client Bean — part of the X33V MVC framework) |
| Module | `KKW22501SF` (Package: `eo.web.webview.KKW22501SF`) |

## 1. Role

### KKW22501SFBean.addListDataInstance()

This method is a **polymorphic factory dispatcher** within the K-Opticom Web Client (X33V) framework. Its purpose is to lazily create and append new data instances for typed list-based view components, based on a string `key` that identifies the kind of list item to instantiate. It supports three distinct recurring data items used on the **Agency Event SP Settings screen** (`KKW22501` — 代理店イベントSP設定画面): (1) the recurring data item setting condition list for the current view, (2) the recurring data item setting condition list for the pre-change (before-edit) snapshot, and (3) the data extraction item list.

The method implements a **routing/dispatch pattern**: it inspects the `key` parameter against hard-coded Japanese label strings to determine which list and which data-bean class to instantiate. When the key starts with `"//"`, it delegates to the parent class's base implementation (used for generic common-info display lists handled at the framework level). For recognized recurring-data-item keys, it lazily initializes its internal `X33VDataTypeList` fields if they are null, creates a new instance of the corresponding data-bean (`KKW22501SF01DBean` or `KKW22501SF02DBean`), appends it to the list, and returns the index of the newly added element. If the key is unrecognised, it returns `-1`.

The method's role in the larger system is to act as the **instance-on-demand factory** for the screen's tabular data components. Rather than pre-allocating all rows at construction time, it allows the view layer to request a new row exactly when the user triggers an "add row" action, keeping memory usage lean and deferring bean construction until the data is actually needed. It is tightly coupled to the `KKW22501SF` screen, which manages agent (dealer) event SP configuration for telecom service orders.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance(String key)"])
    START --> CHECK_NULL{"key == null?"}
    CHECK_NULL -->|Yes| RET_NEG1(["return -1"])
    CHECK_NULL -->|No| CHECK_PREFIX{"key starts with '//'?"}
    CHECK_PREFIX -->|Yes| CALL_SUPER["super.addListDataInstance(key)"]
    CALL_SUPER --> RET_SUPER(["Return super result"])
    CHECK_PREFIX -->|No| CHECK_RECURRING{"key == 'データ抽出項目設定条件一覧照会（イベントSP）明細'?"}
    CHECK_RECURRING -->|Yes| INIT_RECURRING{"dchskm_sete_jkn_list_list == null?"}
    INIT_RECURRING -->|Yes| CREATE_RECURRING["dchskm_sete_jkn_list_list = new X33VDataTypeList()"]
    CREATE_RECURRING --> ADD_RECURRING
    INIT_RECURRING -->|No| ADD_RECURRING["KKW22501SF01DBean tmpBean = new KKW22501SF01DBean()"]
    ADD_RECURRING --> ADD_LIST_1["dchskm_sete_jkn_list_list.add(tmpBean)"]
    ADD_LIST_1 --> RET_IDX_1(["return dchskm_sete_jkn_list_list.size() - 1"])
    CHECK_RECURRING -->|No| CHECK_PREV{"key == '変更前データ抽出項目設定条件一覧照会（イベントSP）明細'?"}
    CHECK_PREV -->|Yes| INIT_PREV{"bf_dchskm_sete_jkn_list_list == null?"}
    INIT_PREV -->|Yes| CREATE_PREV["bf_dchskm_sete_jkn_list_list = new X33VDataTypeList()"]
    CREATE_PREV --> ADD_PREV
    INIT_PREV -->|No| ADD_PREV["KKW22501SF01DBean tmpBean = new KKW22501SF01DBean()"]
    ADD_PREV --> ADD_LIST_2["bf_dchskm_sete_jkn_list_list.add(tmpBean)"]
    ADD_LIST_2 --> RET_IDX_2(["return bf_dchskm_sete_jkn_list_list.size() - 1"])
    CHECK_PREV -->|No| CHECK_DCHSKM{"key == 'データ抽出項目一覧照会明細'?"}
    CHECK_DCHSKM -->|Yes| INIT_DCHSKM{"dchskm_list_list == null?"}
    INIT_DCHSKM -->|Yes| CREATE_DCHSKM["dchskm_list_list = new X33VDataTypeList()"]
    CREATE_DCHSKM --> ADD_DCHSKM
    INIT_DCHSKM -->|No| ADD_DCHSKM["KKW22501SF02DBean tmpBean = new KKW22501SF02DBean()"]
    ADD_DCHSKM --> ADD_LIST_3["dchskm_list_list.add(tmpBean)"]
    ADD_LIST_3 --> RET_IDX_3(["return dchskm_list_list.size() - 1"])
    CHECK_DCHSKM -->|No| RET_NOT_FOUND(["return -1"])
    RET_NEG1 --> END(["End"])
    RET_SUPER --> END
    RET_IDX_1 --> END
    RET_IDX_2 --> END
    RET_IDX_3 --> END
    RET_NOT_FOUND --> END
```

**Block descriptions:**

1. **Null guard** — If `key` is `null`, return `-1` immediately (no operation).
2. **Common-info display list branch** — If `key` starts with `"//"`, delegate to the parent class's `addListDataInstance(key)`. This handles generic framework-managed common-info display lists processed at the base class level.
3. **Recurring data item setting condition list (current view)** — If the key matches the recurring data item setting condition list label for the Event SP detail, instantiate `KKW22501SF01DBean` and append it to `dchskm_sete_jkn_list_list`.
4. **Recurring data item setting condition list (pre-change)** — If the key matches the pre-change variant of the recurring data item setting condition list, instantiate `KKW22501SF01DBean` and append it to `bf_dchskm_sete_jkn_list_list`.
5. **Data extraction item list** — If the key matches the data extraction item list label, instantiate `KKW22501SF02DBean` and append it to `dchskm_list_list`.
6. **Fallback** — If none of the above match, return `-1` (no corresponding item found).

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The item label (data-type-bean name) that identifies which list to instantiate a row for. It is a human-readable Japanese label string that maps to a specific data-bean class. Values include `"データ抽出項目設定条件一覧照会（イベントSP）明細"` (Recurring data item setting condition list — Event SP detail, uses `KKW22501SF01DBean`), `"変更前データ抽出項目設定条件一覧照会（イベントSP）明細"` (Pre-change recurring data item setting condition list — Event SP detail, uses `KKW22501SF01DBean`), `"データ抽出項目一覧照会明細"` (Data extraction item list, uses `KKW22501SF02DBean`), or any string starting with `"//"` (common-info display list, delegated to parent). |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `dchskm_sete_jkn_list_list` | `X33VDataTypeList` | List backing the current-view recurring data item setting condition rows. Lazily initialized if `null`. |
| `bf_dchskm_sete_jkn_list_list` | `X33VDataTypeList` | List backing the pre-change (pre-edit snapshot) recurring data item setting condition rows. Lazily initialized if `null`. |
| `dchskm_list_list` | `X33VDataTypeList` | List backing the data extraction item list rows. Lazily initialized if `null`. |

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| C | `KKW22501SFBean.addListDataInstance` | KKW22501SFBean | - | Calls `addListDataInstance` in `KKW22501SFBean` |

### Internal method calls:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| C | `super.addListDataInstance` | X33VViewBaseBean | - | Delegates to the parent framework class for common-info display list handling (key starts with `//`) |
| C | `X33VDataTypeList.add` | X33VDataTypeList | - | Appends a new typed data-bean instance to the internal list backing a UI component |
| C | `KKW22501SF01DBean.<init>` | KKW22501SF01DBean | - | Instantiates the recurring data item setting condition data bean (used for both current and pre-change lists) |
| C | `KKW22501SF02DBean.<init>` | KKW22501SF02DBean | - | Instantiates the data extraction item data bean |

**CRUD classification rationale:**
This method performs **no database operations**. It is purely an in-memory factory/dispatcher. All "Create" operations are in-memory list appends and data-bean instantiations. It does not call any SC (Service Component) or CBS (Common Business Service) methods that interact with the database.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKW22501 | `KKW22501SFController/KKW22501SF.execute` -> `KKW22501SFBean.addListDataInstance(String key)` | `super.addListDataInstance [C] -`, `KKW22501SF01DBean new [C] -`, `KKW22501SF02DBean new [C] -` |
| 2 | (Internal) | `KKW22501SFBean.addListDataInstance()` (no-arg overload) -> `KKW22501SFBean.addListDataInstance(String key)` | Same as above |

**Notes:**
- The pre-extracted caller data shows only one direct caller: `KKW22501SFBean.addListDataInstance()` (a no-arg overload), suggesting this method is primarily invoked by a convenience wrapper on the same bean.
- The `KKW22501` screen (代理店イベントSP設定画面 — Agency Event SP Settings screen) is the entry point. The screen controller calls this method when the user requests to add a new row to any of the three data lists on the screen.
- This method does not call any external SC/CBS services; all operations are local to the bean instance.

## 6. Per-Branch Detail Blocks

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

> Guard clause: if the key is null, return -1 immediately. No processing occurs.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // key is null, no item to instantiate |

**Block 2** — ELSE-IF `(key.startsWith("//"))` (L1294)

> Common-info display list branch: keys starting with `//` indicate common-info view types. These are handled by the base class framework (共通情報ビューン). The method delegates to the parent's `addListDataInstance` which manages generic display lists at the framework level.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.startsWith("//")` // check if key is a common-info display list identifier |
| 2 | CALL | `super.addListDataInstance(key)` // delegate to parent class for common-info view processing (共通情報ビューンは基底クラスで処理) |

**Block 3** — ELSE-IF `(key.equals("データ抽出項目設定条件一覧照会（イベントSP）明細"))` (L1301)

> Recurring data item setting condition list (current view). This is the primary data list for the recurring data item configuration on the Agency Event SP Settings screen. The data-bean class is `KKW22501SF01DBean`. The item ID for this list is `dchskm_sete_jkn_list`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("データ抽出項目設定条件一覧照会（イベントSP）明細")` // matches recurring data item setting condition list label |
| 2 | IF | `dchskm_sete_jkn_list_list == null` // if the list is null, create a new empty instance (リストがnullの場合、新しく空のインスタンを生成) |
| 2.1 | SET | `dchskm_sete_jkn_list_list = new X33VDataTypeList()` // initialize the typed data list |
| 3 | SET | `KKW22501SF01DBean tmpBean = new KKW22501SF01DBean()` // create a data-type-bean instance for the recurring item (データタイプビューン型で指定したデータタイプビューンのインスタンを生成) |
| 4 | CALL | `dchskm_sete_jkn_list_list.add(tmpBean)` // append the new bean to the list |
| 5 | RETURN | `return dchskm_sete_jkn_list_list.size() - 1;` // return the index of the newly added element (追加された要素のインデックス番号) |

**Block 4** — ELSE-IF `(key.equals("変更前データ抽出項目設定条件一覧照会（イベントSP）明細"))` (L1314)

> Pre-change recurring data item setting condition list. This is the snapshot/list of setting conditions as they existed before the current edit (変更前). Uses the same data-bean class `KKW22501SF01DBean` but maintains a separate list `bf_dchskm_sete_jkn_list_list` (bf = before). The item ID for this list is `bf_dchskm_sete_jkn_list`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("変更前データ抽出項目設定条件一覧照会（イベントSP）明細")` // matches pre-change recurring data item setting condition list label |
| 2 | IF | `bf_dchskm_sete_jkn_list_list == null` // if the list is null, create a new empty instance |
| 2.1 | SET | `bf_dchskm_sete_jkn_list_list = new X33VDataTypeList()` // initialize the pre-change typed data list |
| 3 | SET | `KKW22501SF01DBean tmpBean = new KKW22501SF01DBean()` // create a data-type-bean instance for the pre-change recurring item |
| 4 | CALL | `bf_dchskm_sete_jkn_list_list.add(tmpBean)` // append the new bean to the pre-change list |
| 5 | RETURN | `return bf_dchskm_sete_jkn_list_list.size() - 1;` // return the index of the newly added element |

**Block 5** — ELSE-IF `(key.equals("データ抽出項目一覧照会明細"))` (L1326)

> Data extraction item list. This list holds the data extraction conditions/items (データ抽出項目) for the screen. Uses data-bean class `KKW22501SF02DBean`. The item ID for this list is `dchskm_list`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("データ抽出項目一覧照会明細")` // matches data extraction item list label |
| 2 | IF | `dchskm_list_list == null` // if the list is null, create a new empty instance |
| 2.1 | SET | `dchskm_list_list = new X33VDataTypeList()` // initialize the data extraction item typed data list |
| 3 | SET | `KKW22501SF02DBean tmpBean = new KKW22501SF02DBean()` // create a data-type-bean instance for the data extraction item list |
| 4 | CALL | `dchskm_list_list.add(tmpBean)` // append the new bean to the data extraction item list |
| 5 | RETURN | `return dchskm_list_list.size() - 1;` // return the index of the newly added element |

**Block 6** — ELSE (fallback, L1332)

> No matching item was found for the given key. Return `-1` to indicate that the key does not correspond to any recognized list type.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `dchskm_sete_jkn_list_list` | Field | Recurring data item setting condition list (current view) — internal list backing the `KKW22501SF01DBean` rows for the current-state recurring item configuration |
| `bf_dchskm_sete_jkn_list_list` | Field | Pre-change recurring data item setting condition list — internal list backing the `KKW22501SF01DBean` rows for the snapshot of setting conditions before the current edit (bf = "before") |
| `dchskm_list_list` | Field | Data extraction item list — internal list backing the `KKW22501SF02DBean` rows for the screen's data extraction condition items |
| `key` | Parameter | Item label / data-type-bean name — a Japanese string that identifies which list a new row should be appended to |
| KKW22501 | Screen ID | Agency Event SP Settings screen (代理店イベントSP設定画面) — the telecom service configuration screen where agents (dealers) manage event SP (Special Promotion) settings |
| `KKW22501SF01DBean` | Bean Class | Recurring data item setting condition detail bean — holds data for one row of the recurring item setting condition list |
| `KKW22501SF02DBean` | Bean Class | Data extraction item detail bean — holds data for one row of the data extraction item list |
| X33VDataTypeList | Framework Type | X33V framework typed data list — a generic list container that holds instances of typed data beans (X33VDataTypeBeanInterface implementations) |
| X33VViewBaseBean | Framework Class | Base view bean class — provides the framework-level `addListDataInstance(String key)` that handles common-info display lists (keys starting with `//`) |
| データ抽出項目設定条件一覧照会（イベントSP）明細 | Label | Recurring data item setting condition list display (Event SP) detail — the current-view list of data extraction condition settings for Event SP items |
| 変更前データ抽出項目設定条件一覧照会（イベントSP）明細 | Label | Pre-change data extraction item setting condition list display (Event SP) detail — the snapshot list of data extraction condition settings before the current edit |
| データ抽出項目一覧照会明細 | Label | Data extraction item list display detail — the list of data extraction items/conditions shown on the screen |
| 共通情報ビューン | Term | Common-info display — a generic framework-managed display list type, identified by keys starting with `"//"` |
| 繰り返し項目 | Term | Recurring item — a data field that can appear multiple times (e.g., multiple rows in a table), requiring lazy instance creation |
| X33SException | Framework Type | X33V framework exception class — thrown by bean methods on processing errors |
| SP | Acronym | Special Promotion — a marketing/promotional campaign concept in the K-Opticom telecom system |
| Event | Term | In this context, a configured event/condition associated with a Special Promotion campaign |