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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW00844SF.KKW00844SF01DBean` |
| Layer | View/Bean Component (X33V framework — web client-side data bean) |
| Module | `KKW00844SF` (Package: `eo.web.webview.KKW00844SF`) |

## 1. Role

### KKW00844SF01DBean.addListDataInstance()

This method is a **factory dispatcher** that dynamically creates and appends a new typed list-data instance into one of several internal `X33VDataTypeList` collections, based on the string key provided. In the Fujitsu X33 web framework, `KKW00844SF01DBean` serves as the **dialog data bean** for the screen responsible for viewing and managing service contract line items — specifically, it holds transient, per-screen collections of UI-bound values that flow between the JSP view layer and the controller.

The method follows a **routing/dispatch pattern**: each branch matches a hardcoded Japanese label (e.g., "動理由コード" — Reason Code, "オプションサービス契約番号" — Option Service Contract Number) and appends an `X33VDataTypeStringBean` instance to the corresponding strongly-typed list. If the list is null, it lazily initializes it before appending. The method returns the index of the newly appended element (i.e., `list.size() - 1`), enabling the caller to immediately address the new entry.

This is a **shared utility method** implemented by `X33VListedBeanInterface` and inherited by dozens of derived screen beans across the system. Each derived bean overrides the method (typically calling `super.addListDataInstance(key)`) to add its own screen-specific list item branches. The base method in `KKW00844SF01DBean` provides the common service-contract line item domain items.

When the key is null or does not match any registered item, the method returns `-1` to signal "no matching item found." This is a non-throwing, fail-safe pattern suitable for use during view initialization and repeated screen operations.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance key"])
    NULL_CHECK{"key is null?"}
    RSN_BRANCH{"key equals 動理由コード"}
    RSN_NULL{"ido_rsn_cd_list is null?"}
    RSN_CREATE["Create X33VDataTypeStringBean tmpBean"]
    RSN_ADD["Add tmpBean to ido_rsn_cd_list"]
    RSN_RETURN_RSN["Return ido_rsn_cd_list.size() -1"]
    SVC_BRANCH{"key equals オプションサービス契約番号"}
    SVC_NULL{"op_svc_kei_no_list is null?"}
    SVC_CREATE["Create X33VDataTypeStringBean tmpBean"]
    SVC_ADD["Add tmpBean to op_svc_kei_no_list"]
    SVC_RETURN["Return op_svc_kei_no_list.size() -1"]
    NO_MATCH_RETURN["Return -1 (no matching item)"]
    END_NODE(["End"])

    START --> NULL_CHECK
    NULL_CHECK -->|yes| NO_MATCH_RETURN
    NULL_CHECK -->|no| RSN_BRANCH
    RSN_BRANCH -->|yes| RSN_NULL
    RSN_NULL -->|yes| RSN_CREATE
    RSN_NULL -->|no| RSN_CREATE
    RSN_CREATE --> RSN_ADD
    RSN_ADD --> RSN_RETURN_RSN
    RSN_RETURN_RSN --> END_NODE
    RSN_BRANCH -->|no| SVC_BRANCH
    SVC_BRANCH -->|yes| SVC_NULL
    SVC_NULL -->|yes| SVC_CREATE
    SVC_NULL -->|no| SVC_CREATE
    SVC_CREATE --> SVC_ADD
    SVC_ADD --> SVC_RETURN
    SVC_RETURN --> END_NODE
    SVC_BRANCH -->|no| NO_MATCH_RETURN
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The Japanese display label of a list item, used to identify which typed collection should receive a new entry. Valid values are `"動理由コード"` (Reason Code — an integer-type field indicating the reason for a change/error in a service line item) and `"オプションサービス契約番号"` (Option Service Contract Number — the contract ID for an optional service attached to a service line item). This key determines which internal `X33VDataTypeList` receives the appended element. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `ido_rsn_cd_list` | `X33VDataTypeList` | List of reason codes for line item changes/errors — lazily initialized on first use |
| `op_svc_kei_no_list` | `X33VDataTypeList` | List of option service contract numbers — lazily initialized on first use |

## 4. CRUD Operations / Called Services

This method performs only in-memory object creation and collection mutation. It does **not** call any service components (SC), CBS, or data access layer methods.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| *(none)* | *(none)* | *(none)* | *(none)* | This method performs no database or service calls. It only creates in-memory bean instances and mutates local lists. |

**In-memory operations:**

| # | Type | Description |
|---|-------|-------------|
| 1 | Create | Instantiates `new X33VDataTypeStringBean()` — a simple string-typed data wrapper from the X33V framework |
| 2 | Create | Lazily initializes `new X33VDataTypeList()` if the target list is null |
| 3 | Append | Calls `X33VDataTypeList.add(tmpBean)` to append the new bean to the typed collection |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKW00844SF | `KKW00844SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` | *(none — in-memory only)* |
| 2 | Screen:FKS00005 | `FKS00005SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 3 | Screen:FKS00006 | `FKS00006SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 4 | Screen:FKS00010 | `FKS00010SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 5 | Screen:FKS00011 | `FKS00011SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 6 | Screen:FUW00901 | `FUW00901SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 7 | Screen:FUW00907 | `FUW00907SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 8 | Screen:FUW00912 | `FUW00912SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 9 | Screen:FUW00917 | `FUW00917SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 10 | Screen:FUW00919 | `FUW00919SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 11 | Screen:FUW00926 | `FUW00926SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 12 | Screen:FUW00927 | `FUW00927SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 13 | Screen:FUW00931 | `FUW00931SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 14 | Screen:FUW00959 | `FUW00959SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |
| 15 | Screen:FUW00964 | `FUW00964SFBean` -> `addListDataInstance(key)` -> `KKW00844SF01DBean.addListDataInstance` (via super) | *(none — in-memory only)* |

## 6. Per-Branch Detail Blocks

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

> Null-guard: if the key parameter is null, return -1 immediately. This prevents NullPointerException and signals "no matching item."

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // Return -1 if key is null. (nullの場合、-1で返す) [-> -1 = no match sentinel] |

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

> Branch for the "Reason Code" line item. This is a String-typed field (item ID: `ido_rsn_cd`). If the list is null, lazily initializes a new `X33VDataTypeList`, creates a new `X33VDataTypeStringBean` instance, and appends it. The reason code represents the reason for a change or error in a service line item.

| # | Type | Code |
|---|------|------|
| 1 | COND | `key.equals("動理由コード")` // Check if key is the reason code item label. [-> "動理由コード" = Reason Code (reason for line item change/error)] |
| 2 | **Block 2.1** — [IF] `ido_rsn_cd_list == null` (L777) |
| 2.1 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` // If list is null, generate new empty instance. (リストがnullの場合、新しい空のインスタンを生成する) [-> lazy initialization] |
| 3 | EXEC | `new X33VDataTypeStringBean()` // Generate instance of the specified data type bean. (データタイプビーン型で指定したデータタイプビーンのインスタントを生成する) [-> new string-typed wrapper] |
| 3 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Instantiate new string bean. (データタイプビーン型で指定したデータタイプビーンのインスタントを生成する。なお、データタイプビーン項目初期値設定は、各データビーン内部で定義) |
| 4 | CALL | `ido_rsn_cd_list.add(tmpBean);` // Append new bean to the reason code list. |
| 5 | RETURN | `return ido_rsn_cd_list.size() - 1;` // Return the index of the appended element. (追加された要素のインデックス番号) |

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

> Branch for the "Option Service Contract Number" line item. This is a String-typed field (item ID: `op_svc_kei_no`). If the list is null, lazily initializes a new `X33VDataTypeList`, creates a new `X33VDataTypeStringBean` instance, and appends it. The option service contract number identifies an optional service contract attached to a service line item.

| # | Type | Code |
|---|------|------|
| 1 | COND | `key.equals("オプションサービス契約番号")` // Check if key is the option service contract number item label. [-> "オプションサービス契約番号" = Option Service Contract Number] |
| 2 | **Block 3.1** — [IF] `op_svc_kei_no_list == null` (L787) |
| 3.1 | SET | `op_svc_kei_no_list = new X33VDataTypeList();` // If list is null, generate new empty instance. (リストがnullの場合、新しい空のインスタンスを生成する) [-> lazy initialization] |
| 4 | EXEC | `new X33VDataTypeStringBean()` // Generate instance of the specified data type bean. (データタイプビーン型で指定したデータタイプビーンのインスタントを生成する) [-> new string-typed wrapper] |
| 4 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Instantiate new string bean. (データタイプビーン型で指定したデータタイプビーンのインスタントを生成する。なお、データタイプビーン項目初期値設定は、各データビーン内部で定義) |
| 5 | CALL | `op_svc_kei_no_list.add(tmpBean);` // Append new bean to the option service contract number list. |
| 6 | RETURN | `return op_svc_kei_no_list.size() - 1;` // Return the index of the appended element. (追加された要素のインデックス番号) |

**Block 4** — [ELSE — default return] (L796)

> Default case: no matching key was found. Return -1 to indicate the key does not correspond to any registered list item.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `ido_rsn_cd` | Field | Item ID for "Reason Code" — the reason for a change or error in a service line item |
| `op_svc_kei_no` | Field | Item ID for "Option Service Contract Number" — the contract ID for an optional service attached to a service line item |
| 動理由コード | Field (Japanese) | Reason Code — Japanese label for the line item reason code. Indicates why a service line item was changed or flagged for error |
| オプションサービス契約番号 | Field (Japanese) | Option Service Contract Number — Japanese label for the option service contract. Identifies an optional (add-on) service contract tied to a service line item |
| KKW00844SF | Screen Code | Service contract line item viewing screen — displays and manages line items for a service contract |
| X33VDataTypeList | Framework class | Generic typed list container from the Fujitsu X33V web framework. Holds a collection of items implementing `X33VDataTypeBeanInterface` |
| X33VDataTypeStringBean | Framework class | A string-typed data wrapper implementing `X33VDataTypeBeanInterface`. Used to represent a single string value in an X33V typed list |
| X33VListedBeanInterface | Framework interface | X33V interface that designates a bean as supporting list-based (repeating) fields. Enables the framework to manage list add/remove/iteration operations |
| X33VDataTypeBeanInterface | Framework interface | X33V interface for single-value data types (string, boolean, long, etc.). Provides `getValue()` and `setValue()` methods |
| X33SException | Framework class | Exception class from the Fujitsu X33 framework, used for view-layer validation errors |
| K-Opticom | Business term | The company — a Japanese telecommunications service provider offering fiber-optic (FTTH), voice, and optional services |