# Business Logic — KKW01601SF03DBean.addListDataInstance() [43 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKA15301SF.KKW01601SF03DBean` |
| Layer | View / Data Bean (Web presentation layer, within `eo.web.webview` package) |
| Module | `KKA15301SF` (Package: `eo.web.webview.KKA15301SF`) |

## 1. Role

### KKW01601SF03DBean.addListDataInstance()

This method serves as the **centralized factory and dispatcher** for creating typed list-item instances within the KKA15301SF screen's data bean. It is a key part of the framework's dynamic list management system, which allows web screens to build up repeatable row structures (e.g., multiple service contract entries, multiple reason codes) from a string key lookup. The method receives a Japanese-labeled **item name** string (`key`) and dispatches to branch-specific initialization logic: for each recognized item, it lazily instantiates the backing `X33VDataTypeList`, creates a typed `X33VDataTypeStringBean` instance, appends it to the list, and returns the index of the newly appended element.

This is a **routing/dispatch design pattern** implemented via an if-else chain keyed on Japanese string literals. Each recognized branch corresponds to a specific field group in the telecommunication order/handover (引渡 -- "handover") business domain, where a customer service form allows users to add multiple lines of related data (e.g., adding additional reason codes for a service transfer, or listing multiple option service contract numbers). The return value is the 0-based index of the newly created element within its list, enabling the caller to subsequently retrieve and populate the new row via index-based accessors.

**Design role:** This method is a shared utility within the view-layer data bean hierarchy. It is defined in `KKW01601SF03DBean` and inherited by many subclasses (detailed in Section 5). It provides a uniform, key-driven API for screens to dynamically extend their data models without knowing the concrete list field names, abstracting away the lazy-init and indexing concerns.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance key"])
    COND_NULL{"key is null"}
    RET_N1(["Return -1"])
    COND_REASONS{"key equals '異動理由コード'"}
    INIT_REASONS{"hktgi_ido_rsn_cd_list is null"}
    CRE_REASONS_LIST["Create new X33VDataTypeList"]
    CRE_STRBEAN["Create X33VDataTypeStringBean"]
    ADD_REASONS["Add bean to list"]
    RET_REASONS["Return list.size - 1"]
    COND_OPSVC{"key equals 'オプションサービス契約番号'"}
    INIT_OPSVC{"hktgi_op_svc_kei_no_list is null"}
    CRE_OPSVC_LIST["Create new X33VDataTypeList"]
    ADD_OPSVC["Add bean to list"]
    RET_OPSVC["Return list.size - 1"]
    COND_MSKM{"key equals '同時申請サービス契約番号'"}
    INIT_MSKM{"hktgi_mskm_svc_kei_no_list is null"}
    CRE_MSKM_LIST["Create new X33VDataTypeList"]
    ADD_MSKM["Add bean to list"]
    RET_MSKM["Return list.size - 1"]
    RET_UNKNOWN(["Return -1"])
    END(["End"])
    START --> COND_NULL
    COND_NULL --> |Yes| RET_N1
    COND_NULL --> |No| COND_REASONS
    COND_REASONS --> |Yes| INIT_REASONS
    COND_REASONS --> |No| COND_OPSVC
    INIT_REASONS --> |Yes| CRE_REASONS_LIST
    INIT_REASONS --> |No| CRE_STRBEAN
    CRE_REASONS_LIST --> CRE_STRBEAN
    CRE_STRBEAN --> ADD_REASONS
    ADD_REASONS --> RET_REASONS
    COND_OPSVC --> |Yes| INIT_OPSVC
    COND_OPSVC --> |No| COND_MSKM
    INIT_OPSVC --> |Yes| CRE_OPSVC_LIST
    INIT_OPSVC --> |No| CRE_STRBEAN
    CRE_OPSVC_LIST --> CRE_STRBEAN
    CRE_STRBEAN --> ADD_OPSVC
    ADD_OPSVC --> RET_OPSVC
    COND_MSKM --> |Yes| INIT_MSKM
    COND_MSKM --> |No| RET_UNKNOWN
    INIT_MSKM --> |Yes| CRE_MSKM_LIST
    INIT_MSKM --> |No| CRE_STRBEAN
    CRE_MSKM_LIST --> CRE_STRBEAN
    CRE_STRBEAN --> ADD_MSKM
    ADD_MSKM --> RET_MSKM
    RET_N1 --> END
    RET_REASONS --> END
    RET_OPSVC --> END
    RET_MSKM --> END
    RET_UNKNOWN --> END
```

**Processing flow:**

1. **Null check (L1449-1451):** If `key` is `null`, immediately return `-1`. No further processing occurs. This acts as a guard clause to prevent `NullPointerException` on subsequent `equals()` calls.

2. **Branch A -- "異動理由コード" (Reason Code for Handover Change):** When `key` equals `"異動理由コード"`, this branch manages the repeatable list of reason codes explaining why a service handover/change occurred. It lazily initializes `hktgi_ido_rsn_cd_list` if null, creates a new string-typed bean, appends it, and returns the index.

3. **Branch B -- "オプションサービス契約番号" (Option Service Contract Number):** When `key` equals `"オプションサービス契約番号"`, this branch manages the repeatable list of option service contract numbers tied to a primary service. It lazily initializes `hktgi_op_svc_kei_no_list`, creates a new string-typed bean, appends it, and returns the index.

4. **Branch C -- "同時申請サービス契約番号" (Simultaneous Application Service Contract Number):** When `key` equals `"同時申請サービス契約番号"`, this branch manages the repeatable list of service contract numbers that are being applied for simultaneously with the primary order. It lazily initializes `hktgi_mskm_svc_kei_no_list`, creates a new string-typed bean, appends it, and returns the index.

5. **Default -- unknown key:** If `key` does not match any of the three recognized values, return `-1` to signal that the item is not supported.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The Japanese-labeled item name that identifies which repeatable list field to create an instance for. It maps to one of three business data categories: handover reason codes (`"異動理由コード"`), option service contract numbers (`"オプションサービス契約番号"`), or simultaneous application service contract numbers (`"同時申請サービス契約番号"`). The value is matched via exact string equality. |

**Instance fields read by this method:**

| Field Name | Type | Business Meaning |
|-----------|------|-----------------|
| `hktgi_ido_rsn_cd_list` | `X33VDataTypeList` | List of handover reason code string beans — stores the reason codes explaining why a service handover or change is being performed. Null by default; lazily initialized on first add. |
| `hktgi_op_svc_kei_no_list` | `X33VDataTypeList` | List of option service contract number string beans — stores contract numbers for additional optional services bundled with the primary service. Null by default; lazily initialized on first add. |
| `hktgi_mskm_svc_kei_no_list` | `X33VDataTypeList` | List of simultaneous application service contract number string beans — stores contract numbers for services being applied for at the same time as the main order. Null by default; lazily initialized on first add. |

## 4. CRUD Operations / Called Services

This method performs **no external service calls** and **no direct CRUD operations** against databases or service components. It operates entirely within the view-layer data bean, manipulating in-memory Java collections.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| N/A | `X33VDataTypeList.add()` | (in-memory collection) | (none) | Appends a typed string bean instance to an in-memory list. This is a collection-level mutator, not a database persistence operation. |
| N/A | `X33VDataTypeStringBean.<init>()` | (framework class) | (none) | Constructs a new string data type bean with default-initialized internal state. The bean acts as a typed wrapper for a string value in the X33 framework's data binding system. |

**Note:** While this method adds data to lists, it does **not** persist to the database. Actual database operations occur when the screen's controller/CBS layer invokes service component methods (e.g., `callEKK...SC`) with the populated bean data as arguments.

## 5. Dependency Trace

**Callers of this method:** This method is defined in the base bean `KKW01601SF03DBean` and inherited by a large number of subclasses across multiple screen modules (FUW009xxSF families). The subclasses either:
- **Override** `addListDataInstance` to handle additional item types, then call `super.addListDataInstance(key)` to delegate unrecognized keys to the parent implementation.
- **Override** `addListDataInstance` with entirely custom logic (no `super` call).

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen: FUW00964SF01DBean | `FUW00964SF01DBean.addListDataInstance(key)` | (no external calls — local list manipulation) |
| 2 | Screen: FUW00964SF04DBean | `FUW00964SF04DBean.addListDataInstance(key)` | (no external calls — local list manipulation) |
| 3 | Screen: FUW00964SF07DBean | `FUW00964SF07DBean.addListDataInstance(key)` | (no external calls — local list manipulation) |
| 4 | Screen: FUW00964SFBean | `FUW00964SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 5 | Screen: FUW00916SFBean | `FUW00916SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 6 | Screen: FUW00917SFBean | `FUW00917SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 7 | Screen: FUW00957SFBean | `FUW00957SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 8 | Screen: FUW00961SFBean | `FUW00961SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 9 | Screen: FUW00947SFBean | `FUW00947SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 10 | Screen: FUW00942SFBean | `FUW00942SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 11 | Screen: FUW00908SFBean | `FUW00908SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 12 | Screen: FUW00918SFBean | `FUW00918SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 13 | Screen: FUW00902SFBean | `FUW00902SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 14 | Screen: FUW00903SFBean | `FUW00903SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |
| 15 | Screen: FUW00909SFBean | `FUW00909SFBean.addListDataInstance(key)` -> `super.addListDataInstance(key)` | (delegates to KKW01601SF03DBean) |

**Note:** The pattern extends across 50+ files (FUW009xxSF screen family). Additional subclasses override with custom `addListDataInstance` implementations: `FUW00964SF10DBean`, `FUW00957SF01DBean`, `FUW00957SF04DBean`, `FUW00957SF05DBean`, `FUW00917SF01DBean`, `FUW00907SF01DBean`, `FUW00947SF01DBean`, `FUW00914SF01DBean`, `FUW00909SF02DBean`, `FUW00942SF03DBean`, `FUW00942SF05DBean`, `FUW00942SF07DBean`, `FUW00908SF02DBean`, `FUW00918SF01DBean`, `FUW00921SF02DBean`, `FUW00921SF03DBean`, `FUW00921SF04DBean`, `FUW00921SF06DBean`, `FUW00916SF05DBean`, `FUW00916SF06DBean`, `FUW00914SF01DBean`, `FUW00926SFBean`, `FUW00959SFBean`, `FUW00901SFBean`, `FUW00927SFBean`, `FUW00931SFBean`, `FUW00919SFBean`, `FUW00907SFBean`, `FUW00946SFBean`, `FUW00928SFBean`, `FUW00932SFBean`, `FUW00921SFBean`, `FUW00912SFBean`.

## 6. Per-Branch Detail Blocks

**Block 1** — IF (null check) (L1449)

> Guard clause: if `key` is null, return -1 immediately. Prevents NullPointerException.

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

**Block 2** — ELSE-IF `"異動理由コード"` (Reason Code for Handover) (L1453)

> Dispatch branch: Manages the repeatable list of reason codes that explain why a service handover (引渡) is occurring. Corresponds to the field ID `hktgi_ido_rsn_cd`.

| # | Type | Code |
|---|------|------|
| 1 | COND | `else if (key.equals("異動理由コード"))` // 引取り項目「異動理由コード」(String型、項目ID:hktgi_ido_rsn_cd) (List item "Reason Code for Handover" String type, Item ID: hktgi_ido_rsn_cd) |
| 2 | COND | `if (hktgi_ido_rsn_cd_list == null)` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, generate a new empty instance) |
| 3 | SET | `hktgi_ido_rsn_cd_list = new X33VDataTypeList();` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, create new empty instance) |
| 4 | COND | (else — list not null, skip initialization) |
| 5 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // データタイプビューン型で指定したデータタイプのビューンインスタンスを生成。なお、データタイプビューンの項目初期値設定は、各データビューン内部で定義 (Instantiate the data type bean of the specified type. The default value settings of the data type bean items are defined internally in each data bean.) |
| 6 | CALL | `hktgi_ido_rsn_cd_list.add(tmpBean);` // 追加する (Add the bean) |
| 7 | RETURN | `return hktgi_ido_rsn_cd_list.size() - 1;` // Return 0-based index |

**Block 2.1** — ELSE (nested null check: list already exists) (L1453)

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // 同上 (Same as Block 2, line 5) |
| 2 | CALL | `hktgi_ido_rsn_cd_list.add(tmpBean);` // 追加する (Add the bean) |
| 3 | RETURN | `return hktgi_ido_rsn_cd_list.size() - 1;` // Return index |

**Block 3** — ELSE-IF `"オプションサービス契約番号"` (Option Service Contract Number) (L1464)

> Dispatch branch: Manages the repeatable list of option service contract numbers. Corresponds to the field ID `hktgi_op_svc_kei_no`.

| # | Type | Code |
|---|------|------|
| 1 | COND | `else if (key.equals("オプションサービス契約番号"))` // 引取り項目「オプションサービス契約番号」(String型、項目ID:hktgi_op_svc_kei_no) (List item "Option Service Contract Number" String type, Item ID: hktgi_op_svc_kei_no) |
| 2 | COND | `if (hktgi_op_svc_kei_no_list == null)` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, generate a new empty instance) |
| 3 | SET | `hktgi_op_svc_kei_no_list = new X33VDataTypeList();` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, create new empty instance) |
| 4 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // データタイプビューン型で指定したデータタイプのビューンインスタンスを生成 (Instantiate data type bean) |
| 5 | CALL | `hktgi_op_svc_kei_no_list.add(tmpBean);` // 追加する (Add the bean) |
| 6 | RETURN | `return hktgi_op_svc_kei_no_list.size() - 1;` // Return index |

**Block 4** — ELSE-IF `"同時申請サービス契約番号"` (Simultaneous Application Service Contract Number) (L1475)

> Dispatch branch: Manages the repeatable list of simultaneously applied service contract numbers. Corresponds to the field ID `hktgi_mskm_svc_kei_no`.

| # | Type | Code |
|---|------|------|
| 1 | COND | `else if (key.equals("同時申請サービス契約番号"))` // 引取り項目「同時申請サービス契約番号」(String型、項目ID:hktgi_mskm_svc_kei_no) (List item "Simultaneous Application Service Contract Number" String type, Item ID: hktgi_mskm_svc_kei_no) |
| 2 | COND | `if (hktgi_mskm_svc_kei_no_list == null)` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, generate a new empty instance) |
| 3 | SET | `hktgi_mskm_svc_kei_no_list = new X33VDataTypeList();` // リストがnullの場合、新しい空のインスタンスを生成 (If list is null, create new empty instance) |
| 4 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // データタイプビューン型で指定したデータタイプのビューンインスタンスを生成 (Instantiate data type bean) |
| 5 | CALL | `hktgi_mskm_svc_kei_no_list.add(tmpBean);` // 追加する (Add the bean) |
| 6 | RETURN | `return hktgi_mskm_svc_kei_no_list.size() - 1;` // Return index |

**Block 5** — ELSE (default / unknown key) (L1486)

> Fallback: if the key does not match any recognized item name, return -1.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-----------------|
| `hktgi` | Prefix | Handover (引渡) — refers to the service handover process where responsibility for a customer's telecom service is transferred between parties (e.g., from installer to customer, or between service providers) |
| `ido_rsn_cd` | Field | Reason code for handover change — a code identifying why a service handover is being performed (e.g., customer request, error correction, upgrade) |
| `ido_div` | Field | Handover division/type — classifies the type of handover operation |
| `svc_kei_no` | Field | Service contract number — the unique identifier for a service contract line item in the order management system |
| `op_svc_kei_no` | Field | Option service contract number — a contract number for optional/add-on services bundled with a primary service |
| `mskm_svc_kei_no` | Field | Simultaneous application service contract number — a contract number for a service being applied for at the same time as the main order |
| 異動理由コード | Field | Reason Code for Handover Change — the Japanese label for `hktgi_ido_rsn_cd`; identifies the reason for a service status change or handover |
| オプションサービス契約番号 | Field | Option Service Contract Number — the Japanese label for `hktgi_op_svc_kei_no`; identifies optional services added to a primary service contract |
| 同時申請サービス契約番号 | Field | Simultaneous Application Service Contract Number — the Japanese label for `hktgi_mskm_svc_kei_no`; identifies services applied for simultaneously with the main order |
| X33VDataTypeList | Framework class | A generic typed list container from the X33 (Fujitsu Futurity) web framework; used to hold a sequence of typed data bean instances |
| X33VDataTypeStringBean | Framework class | A string-typed data bean from the X33 framework; provides typed wrapper for a single string value in the data binding system |
| X33VDataTypeBeanInterface | Framework interface | Interface that marks a class as compatible with the X33 framework's data binding and lazy-loading mechanisms |
| X33VListedBeanInterface | Framework interface | Interface that marks a bean as containing list-type data fields that can be iterated and manipulated |
| X33SException | Framework exception | The standard checked exception type in the X33 framework for signaling business/runtime errors |
| DBean | Naming convention | "Detail Bean" or "Data Bean" — a view-layer bean that holds form data and intermediate processing state for a specific screen |
| KKA prefix | Module convention | Internal module code prefix for K-Opticom's web application services (KKA = internal service domain) |
| FUW prefix | Screen convention | Screen module prefix (FUW009xxSF) — each number pair identifies a distinct web screen in the system |
| 引取り項目 | Japanese term | List item / extracted field — refers to a data field within a repeatable row in a list-based form |