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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKA16801SF.KKW02516SF01DBean` |
| Layer | Utility / Web View Data Bean (Model Layer — implements `X33VListedBeanInterface`) |
| Module | `KKA16801SF` (Package: `eo.web.webview.KKA16801SF`) |

## 1. Role

### KKW02516SF01DBean.addListDataInstance()

This method is the core instance-creation dispatcher within the K-Opticom web view data bean framework. It dynamically creates typed list-element instances for specific recurring (repeatable) form fields based on the business key (`key`) passed as a parameter. Each key maps to a dedicated data list field (`ido_rsn_cd_list` or `op_svc_kei_no_list`), and the method either initializes the list if it is null, then appends a new data-type bean (`X33VDataTypeStringBean`) to it, and returns the zero-based index of the newly added element.

The method implements a **dispatch/routing design pattern** — it examines the string key and routes the creation request to one of two service-type branches: the "Reason Code for Status Change" field (異動理由コード, `ido_rsn_cd`) and the "Option Service Contract Number" field (オプションサービス契約番号, `op_svc_kei_no`). Both branches produce `X33VDataTypeStringBean` instances, but they are stored in separate list fields so the screen can manage each repeatable field's data independently.

This is a **shared utility method** used by many screen beans (e.g., FUW00901SF, FUW00912SF, FUW00914SF, etc.) that override `addListDataInstance` and delegate to this base implementation. It plays the role of a factory and mutator combined: it creates instances and persists them into the bean's internal state, making the new element immediately available for downstream binding to the presentation layer (JSF/HTML forms).

If the key is `null` or does not match any recognized field name, the method safely returns `-1` to signal that no instance was created — enabling callers to detect unsupported or missing keys without throwing exceptions.

## 2. Processing Pattern (Detailed Business Logic)

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

    START --> COND_NULL["key == null ?"]

    COND_NULL -->|true| RET_NEG1_1(["return -1"])
    COND_NULL -->|false| COND1["key equals “異動理由コード”"]

    COND1 -->|true| CHECK_LIST1["ido_rsn_cd_list == null ?"]
    CHECK_LIST1 -->|true| INIT_LIST1["ido_rsn_cd_list = new X33VDataTypeList()"]
    INIT_LIST1 --> CREATE_BEAN1["tmpBean = new X33VDataTypeStringBean()"]
    CHECK_LIST1 -->|false| CREATE_BEAN1
    CREATE_BEAN1 --> ADD1["ido_rsn_cd_list.add(tmpBean)"]

    ADD1 --> RET_IDX1["return ido_rsn_cd_list.size() - 1"]

    COND1 -->|false| COND2["key equals “オプションサービス契約番号”"]

    COND2 -->|true| CHECK_LIST2["op_svc_kei_no_list == null ?"]
    CHECK_LIST2 -->|true| INIT_LIST2["op_svc_kei_no_list = new X33VDataTypeList()"]
    INIT_LIST2 --> CREATE_BEAN2["tmpBean = new X33VDataTypeStringBean()"]
    CHECK_LIST2 -->|false| CREATE_BEAN2
    CREATE_BEAN2 --> ADD2["op_svc_kei_no_list.add(tmpBean)"]

    ADD2 --> RET_IDX2["return op_svc_kei_no_list.size() - 1"]

    COND2 -->|false| RET_NEG1_2(["return -1"])

    RET_NEG1_1 --> END(["End"])
    RET_IDX1 --> END
    RET_IDX2 --> END
    RET_NEG1_2 --> END
```

**Branch descriptions:**

| Branch | Condition | Business Meaning |
|--------|-----------|------------------|
| Null guard | `key == null` | Early exit when no field name is provided |
| Branch 1 | `key.equals("異動理由コード")` | Creates an instance for the "Reason Code for Status Change" repeatable field |
| Branch 2 | `key.equals("オプションサービス契約番号")` | Creates an instance for the "Option Service Contract Number" repeatable field |
| Default | None of the above | Returns `-1` — no matching field |

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The business field name that identifies which recurring/repeatable list element to create. Accepts two recognized values: `"異動理由コード"` (Reason Code for Status Change — an internal tracking code describing why a service contract status changed) or `"オプションサービス契約番号"` (Option Service Contract Number — the contract ID for an optional add-on service). If the value does not match any recognized field, or is `null`, the method returns `-1`. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `ido_rsn_cd_list` | `X33VDataTypeList` | List storing instances of "Reason Code for Status Change" items — each element is a typed string bean |
| `op_svc_kei_no_list` | `X33VDataTypeList` | List storing instances of "Option Service Contract Number" items — each element is a typed string bean |

## 4. CRUD Operations / Called Services

This method performs **no direct database or service component (SC/CBS) calls**. All operations are in-memory list management within the data bean itself. The bean implements `X33VListedBeanInterface`, meaning it manages its own state without external persistence during this method's execution.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| *(none)* | — | — | — | This method performs pure in-memory instance creation. No SC, CBS, entity, or database table is involved. The `X33VDataTypeList` and `X33VDataTypeStringBean` objects are transient Java objects managed by the X33 web framework's view layer. |

## 5. Dependency Trace

All screen beans in the codebase that override `addListDataInstance` delegate to this base method via `super.addListDataInstance(key)`. The table below lists the known screen beans (by naming convention `FUW009XXSFBean`) that call this method through inheritance. These are web screens in the K-Opticom system, typically used for telecom service order management (option services, status changes, etc.).

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:FUW00901SF | `FUW00901SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 2 | Screen:FUW00902SF | `FUW00902SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 3 | Screen:FUW00907SF | `FUW00907SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 4 | Screen:FUW00909SF | `FUW00909SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 5 | Screen:FUW00912SF | `FUW00912SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 6 | Screen:FUW00914SF | `FUW00914SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 7 | Screen:FUW00916SF | `FUW00916SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 8 | Screen:FUW00917SF | `FUW00917SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 9 | Screen:FUW00919SF | `FUW00919SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 10 | Screen:FUW00926SF | `FUW00926SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 11 | Screen:FUW00927SF | `FUW00927SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 12 | Screen:FUW00931SF | `FUW00931SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 13 | Screen:FUW00942SF | `FUW00942SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 14 | Screen:FUW00946SF | `FUW00946SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |
| 15 | Screen:FUW00947SF | `FUW00947SFBean.addListDataInstance(key)` → `super.addListDataInstance(key)` → `KKW02516SF01DBean.addListDataInstance(key)` | *(none — in-memory bean only)* |

*Note: 18 additional screen beans were found delegating to `super.addListDataInstance(key)`. This table lists the first 15 unique callers.*

## 6. Per-Branch Detail Blocks

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

> If the key parameter is null, immediately return -1 to signal that no instance could be created.

| # | Type | Code |
|---|------|------|
| 1 | SET | `if(key == null)` |
| 2 | RETURN | `return -1;` // Early exit — null key means no valid field name [→ -1: Invalid/Not Found] |

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

> Creates a new instance for the "Reason Code for Status Change" (異動理由コード) repeatable field. This field is used to track the reason code when a service contract's status changes (e.g., suspension, cancellation). Each list element is a string-typed bean.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("異動理由コード")` // Check if key matches "Reason Code for Status Change" [→ Field ID: ido_rsn_cd] |
| 2 | IF | `if(ido_rsn_cd_list == null)` // Check if the list has been initialized |
| 3 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` // Initialize with a new empty typed list [→ New empty X33VDataTypeList instance] |
| 4 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create a new string-typed data bean [→ X33VDataTypeStringBean: typed string element] |
| 5 | CALL | `ido_rsn_cd_list.add(tmpBean);` // Append the new instance to the list [→ In-memory list add] |
| 6 | RETURN | `return ido_rsn_cd_list.size() - 1;` // Return the zero-based index of the newly added element [→ int: last index] |

**Block 2.1** — IF (nested) `(ido_rsn_cd_list == null)` (L777)

> Initializes the list if this is the first time the "Reason Code for Status Change" field instance is being created.

| # | Type | Code |
|---|------|------|
| 1 | SET | `ido_rsn_cd_list = new X33VDataTypeList();` // Create a fresh empty list [→ New X33VDataTypeList, not null] |

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

> Creates a new instance for the "Option Service Contract Number" (オプションサービス契約番号) repeatable field. This field stores the contract number for optional/add-on telecom services. Each list element is a string-typed bean.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.equals("オプションサービス契約番号")` // Check if key matches "Option Service Contract Number" [→ Field ID: op_svc_kei_no] |
| 2 | IF | `if(op_svc_kei_no_list == null)` // Check if the list has been initialized |
| 3 | SET | `op_svc_kei_no_list = new X33VDataTypeList();` // Initialize with a new empty typed list [→ New empty X33VDataTypeList instance] |
| 4 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create a new string-typed data bean [→ X33VDataTypeStringBean: typed string element] |
| 5 | CALL | `op_svc_kei_no_list.add(tmpBean);` // Append the new instance to the list [→ In-memory list add] |
| 6 | RETURN | `return op_svc_kei_no_list.size() - 1;` // Return the zero-based index of the newly added element [→ int: last index] |

**Block 3.1** — IF (nested) `(op_svc_kei_no_list == null)` (L789)

> Initializes the list if this is the first time the "Option Service Contract Number" field instance is being created.

| # | Type | Code |
|---|------|------|
| 1 | SET | `op_svc_kei_no_list = new X33VDataTypeList();` // Create a fresh empty list [→ New X33VDataTypeList, not null] |

**Block 4** — ELSE (default) `(no matching key)` (L798)

> No recognized field name matched the key parameter. Return -1 to indicate the caller that the requested field type is not supported or not found.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // No matching field — returns -1 [→ -1: Invalid/Not Found] |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `異動理由コード` (ido_rsn_cd) | Field | Reason Code for Status Change — a string field that stores the reason code explaining why a service contract's status changed (e.g., suspension, cancellation, modification). Each repeatable instance holds one reason code value. |
| `オプションサービス契約番号` (op_svc_kei_no) | Field | Option Service Contract Number — a string field that stores the contract number for optional/add-on telecom services. Each repeatable instance holds one contract number value. |
| `ido_rsn_cd_list` | Field | Internal list field storing `X33VDataTypeStringBean` instances for the "Reason Code for Status Change" repeatable field. |
| `op_svc_kei_no_list` | Field | Internal list field storing `X33VDataTypeStringBean` instances for the "Option Service Contract Number" repeatable field. |
| `X33VDataTypeStringBean` | Class | A data-type bean from the Fujitsu Futurity X33 web framework that represents a single typed string value in a view model. Used here as the element type for both repeatable fields. |
| `X33VDataTypeList` | Class | A typed list container from the X33 web framework that holds instances of a specific bean type. Provides `add()` for appending and `size()` for getting the element count. |
| `X33VListedBeanInterface` | Interface | X33 framework marker interface indicating that a bean manages repeatable/list-based form data. The bean must provide list-data instance creation and removal methods. |
| `X33VViewBaseBean` | Class | Base class for all X33 web view data beans. Provides common functionality for view-layer data management, including the base `addListDataInstance` method that subclasses override. |
| `X33SException` | Class | X33 framework exception class thrown for service-level errors. Declared in the method's `throws` clause but not thrown by the current implementation directly. |
| K-Opticom | Business term | A Japanese telecommunications provider offering fiber-optic broadband (FTTH), mobile phone, and bundled telecom services. This codebase manages the web front-end for service order and contract operations. |
| Web Client tool | Tool | K-Opticom's internal code generation tool (V01/L01) that scaffolds data bean classes and screen beans for the X33 web framework. The `KKW02516SF01DBean` class was generated by this tool. |
| SF (Screen Feature) | Acronym | Screen Feature — a module identifier in K-Opticom's naming convention. Screen beans follow the pattern `FUW009XXSFBean` where `XX` is the sequential screen number. |
| DBean (Data Bean) | Acronym | Data Bean — a data carrier class that holds form field values for a single screen. Extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` for repeatable data support. |
| 固定要素数 (Kotei Yoso-suu) | Japanese term | Fixed element count — a screen configuration parameter that determines how many repeating elements are pre-created. Referenced in calling code (e.g., KKW02516SFBean) when initializing list items. |