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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW02701SF.KKW02701SF01DBean` |
| Layer | DBean (Data Bean — View/Web layer data structure manager) |
| Module | `KKW02701SF` (Package: `eo.web.webview.KKW02701SF`) |

## 1. Role

### KKW02701SF01DBean.addListDataInstance()

This method is the instance-level list data factory for the KKW02701SF screen's DBean, responsible for dynamically initializing repeated-item list structures based on a string key. In K-Opticom's telecom order-entry domain, certain screen fields represent repeating line items — for example, a customer contract may have multiple movement-reason codes (changes to a service) or multiple optional service subscription numbers (add-on services like insurance, broadband packages, etc.). This method dispatches on the `key` parameter to determine which repeated-item list should receive a new entry, creates the appropriate `X33VDataTypeStringBean` data type bean instance, ensures the target list is instantiated if null, appends the new element, and returns the index of the newly added item. It implements a **string-dispatch (routing) pattern**, acting as a shared utility within the DBean hierarchy that enables the parent `KKW02701SFBean` and its associated JSP view logic to grow dynamic repeat sections at runtime. If the key does not match any known repeated-item type, or if the key is null, the method returns -1 to signal that no list was modified. There are no database operations, service component calls, or external dependencies — this is a purely in-memory data-structure initialization method.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance(key)"])
    COND_NULL{"key is null"}
    COND_REASON{"key equals "異動理由コード"}
    COND_OPTION{"key equals "オプションサービス契約番号"}
    NULL_RETURN(["return -1"])
    INIT_REASON{"hktgi_ido_rsn_cd_list is null"}
    INIT_REASON_LIST["hktgi_ido_rsn_cd_list = new X33VDataTypeList()"]
    CREATE_REASON["tmpBean = new X33VDataTypeStringBean()"]
    ADD_REASON["hktgi_ido_rsn_cd_list.add(tmpBean)"]
    RETURN_REASON["return hktgi_ido_rsn_cd_list.size() - 1"]
    INIT_OPTION{"hktgi_op_svc_kei_no_list is null"}
    INIT_OPTION_LIST["hktgi_op_svc_kei_no_list = new X33VDataTypeList()"]
    CREATE_OPTION["tmpBean = new X33VDataTypeStringBean()"]
    ADD_OPTION["hktgi_op_svc_kei_no_list.add(tmpBean)"]
    RETURN_OPTION["return hktgi_op_svc_kei_no_list.size() - 1"]
    NO_MATCH_RETURN(["return -1"])

    START --> COND_NULL
    COND_NULL -->|true| NULL_RETURN
    COND_NULL -->|false| COND_REASON
    COND_REASON -->|true| INIT_REASON
    COND_REASON -->|false| COND_OPTION
    INIT_REASON --> INIT_REASON_LIST
    INIT_REASON_LIST --> CREATE_REASON
    CREATE_REASON --> ADD_REASON
    ADD_REASON --> RETURN_REASON
    RETURN_REASON --> END_NODE(["End"])
    INIT_OPTION --> INIT_OPTION_LIST
    INIT_OPTION_LIST --> CREATE_OPTION
    CREATE_OPTION --> ADD_OPTION
    ADD_OPTION --> RETURN_OPTION
    RETURN_OPTION --> END_NODE
    COND_OPTION -->|true| INIT_OPTION
    COND_OPTION -->|false| NO_MATCH_RETURN
    NO_MATCH_RETURN --> END_NODE
```

This flowchart illustrates the three-branch dispatch logic:

- **Null check** (line 1467): If the key is null, return -1 immediately — no list initialization occurs.
- **Branch 1 — Movement Reason Code** (lines 1471–1479): When `key` equals `"異動理由コード"` (Movement Reason Code), a new row entry is added to the `hktgi_ido_rsn_cd_list`. If the list is null, it is initialized as a new empty `X33VDataTypeList`. A string-type data bean is created, added to the list, and the new element's index is returned.
- **Branch 2 — Option Service Contract Number** (lines 1483–1491): When `key` equals `"オプションサービス契約番号"` (Option Service Contract Number), a new row entry is added to the `hktgi_op_svc_kei_no_list` using the same null-check-and-initialize pattern.
- **Fallback** (line 1493): If the key does not match any known repeated-item type, return -1.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The item identifier that determines which repeated-item list to populate. It maps to human-readable Japanese field names used in the screen's JSP view. Valid values are `"異動理由コード"` (Movement Reason Code — triggers creation of a movement reason code entry in the repeated list) or `"オプションサービス契約番号"` (Option Service Contract Number — triggers creation of an optional service subscription number entry). Any other value or `null` results in a -1 return with no state modification. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `hktgi_ido_rsn_cd_list` | `X33VDataTypeList` | List of movement reason code entries — holds repeating rows for service change/transfer reasons |
| `hktgi_op_svc_kei_no_list` | `X33VDataTypeList` | List of option service contract number entries — holds repeating rows for optional/add-on service subscriptions |

**Instance fields written by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `hktgi_ido_rsn_cd_list` | `X33VDataTypeList` | New `X33VDataTypeList()` instance assigned if previously null (Branch 1) |
| `hktgi_op_svc_kei_no_list` | `X33VDataTypeList` | New `X33VDataTypeList()` instance assigned if previously null (Branch 2) |

## 4. CRUD Operations / Called Services

This method performs **no CRUD operations**. It does not call any Service Component (SC), Consumer Business Service (CBS), or database layer. All operations are in-memory data-structure manipulations within the DBean.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| *(none)* | — | — | — | This method is a pure in-memory list data factory with no database or service component interactions. |

The only method calls are local data type bean constructors (`X33VDataTypeList()`, `X33VDataTypeStringBean()`) and list manipulation (`add()`), which are part of the X33 framework's built-in data bean utilities.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | DBean:KKW02701SF01DBean (self) | *(self-reference — factory method)* | *(none — in-memory only)* |

**Notes:**
- This method is a public utility method defined directly on the `KKW02701SF01DBean` class.
- No external callers were found in the Java codebase scanning 59,002+ files. The method is likely invoked from JSP/view layers or through the X33 framework's reflection-based data bean binding mechanism (the X33VListedBeanInterface contract may call it via property access).
- The parent `KKW02701SFBean` class defines its own `addListDataInstance` overrides that delegate to `super.addListDataInstance(key)` for its own repeated-item types (e.g., `"顧客契約引継リスト"`), which in turn would call this method for the `KKW02701SF01DBean`-specific types.
- Since no Java callers reference this specific method directly, the call chain is limited to the DBean self-context and any JSP view-layer data binding that accesses the bean's public methods.

## 6. Per-Branch Detail Blocks

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

> Early return: null guard prevents further processing. Returns -1 to indicate no list was initialized.

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

---

**Block 2** — [ELSE-IF] `(key.equals("異動理由コード"))` [CONSTANT: key = "異動理由コード" = "Movement Reason Code"] (L1471)

> Initializes the movement reason code repeated-item list. If the list is null, a new empty list is created. A new string-type data bean instance is appended, and the index of the newly added element is returned.

| # | Type | Code |
|---|------|------|
| 1 | CONDITION | `key.equals("異動理由コード")` // 異動理由コード (Movement Reason Code) |
| 2 | CONDITION | `hktgi_ido_rsn_cd_list == null` // リストがnullの場合 (If list is null) |
| 3 | SET | `hktgi_ido_rsn_cd_list = new X33VDataTypeList()` // 新しい空のインスタンスを生成 (Generate a new empty instance) |
| 4 | SET | `tmpBean = new X33VDataTypeStringBean()` // データタイプビーン型の指定したデータタイプビーンのインスタンスを生成 (Instantiate data type bean) |
| 5 | EXEC | `hktgi_ido_rsn_cd_list.add(tmpBean)` // 要素を追加 (Add element to list) |
| 6 | RETURN | `return hktgi_ido_rsn_cd_list.size() - 1;` // 追加された要素のインデックス番号 (Index of the added element) |

**Block 2.1** — [nested IF] `(hktgi_ido_rsn_cd_list == null)` (L1473)

> Nested null check: only executed when the key matched "Movement Reason Code" but the target list was not yet initialized (e.g., first-time access after bean construction, or the constructor's initialization was somehow bypassed).

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

---

**Block 3** — [ELSE-IF] `(key.equals("オプションサービス契約番号"))` [CONSTANT: key = "オプションサービス契約番号" = "Option Service Contract Number"] (L1483)

> Initializes the option service contract number repeated-item list. Same pattern as Block 2: null check, list initialization, string data bean creation, element addition, and index return.

| # | Type | Code |
|---|------|------|
| 1 | CONDITION | `key.equals("オプションサービス契約番号")` // オプションサービス契約番号 (Option Service Contract Number) |
| 2 | CONDITION | `hktgi_op_svc_kei_no_list == null` // リストがnullの場合 (If list is null) |
| 3 | SET | `hktgi_op_svc_kei_no_list = new X33VDataTypeList()` // 新しい空のインスタンスを生成 (Generate a new empty instance) |
| 4 | SET | `tmpBean = new X33VDataTypeStringBean()` // データタイプビーン型の指定したデータタイプビーンのインスタンスを生成 (Instantiate data type bean) |
| 5 | EXEC | `hktgi_op_svc_kei_no_list.add(tmpBean)` // 要素を追加 (Add element to list) |
| 6 | RETURN | `return hktgi_op_svc_kei_no_list.size() - 1;` // 追加された要素のインデックス番号 (Index of the added element) |

**Block 3.1** — [nested IF] `(hktgi_op_svc_kei_no_list == null)` (L1485)

> Nested null check for the option service list, same semantics as Block 2.1.

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

---

**Block 4** — [ELSE / fallback] (L1493)

> When `key` does not match any recognized repeated-item type. Returns -1 to signal no action was taken.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `hktgi_ido_rsn_cd_list` | Field | Movement reason code list — stores repeating rows of reason codes for service changes/transfers (異動理由) |
| `hktgi_op_svc_kei_no_list` | Field | Option service contract number list — stores repeating rows of optional/add-on service subscription numbers |
| `X33VDataTypeStringBean` | Type | X33 framework string-type data bean — a typed wrapper for a single string value used in repeated-item lists |
| `X33VDataTypeList` | Type | X33 framework list container — generic typed list that holds instances of a specific `X33VDataTypeBeanInterface` implementation |
| `X33VListedBeanInterface` | Interface | X33 contract for beans that manage repeated-item (list) data — enables JSP view binding to dynamic lists |
| `X33VDataTypeBeanInterface` | Interface | X33 contract marking a class as a valid data type for list elements |
| DBean | Acronym | Data Bean — view-layer bean that holds screen data structures, including repeated-item lists |
| 異動理由コード (Ido Riyuu Code) | Field | Movement Reason Code — classifies the reason for a service change or transfer (e.g., relocation, cancellation, upgrade) |
| オプションサービス契約番号 (Opusushon Saabisu Keiyaku Bangou) | Field | Option Service Contract Number — identifies an add-on or optional service subscription (e.g., insurance, premium support) |
| 顧客契約引継リスト (Kokyaku Keiyaku Hikitsugi Risuto) | Field | Customer Contract Handover List — a repeated-item list for transferring customer contracts between agents (defined in parent bean, not this method) |
| コーパス履歴一覧リスト (Koasu Rekishii Ichiran Risuto) | Field | Course History List — a repeated-item list for service history entries (defined in parent bean) |
| X33 | Acronym | Fujitsu Futurity X33 — the enterprise web application framework used for this project's view layer |
| KKW02701SF | Module | Screen module identifier for a service change/transfer order entry screen in the K-Opticom telecom billing system |
| index | Field | Local variable holding the current list index during repeated-item operations |