# Business Logic — KKW02516SFBean.addListDataInstance() [48 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKA16801SF.KKW02516SFBean` |
| Layer | Web Component (View Bean — `eo.web.webview.KKA16801SF`) |
| Module | `KKA16801SF` (Package: `eo.web.webview.KKA16801SF`) |

## 1. Role

### KKW02516SFBean.addListDataInstance()

This method is the central dispatcher for dynamically instantiating list-type form data items within the KKW02516SF customer contract succession screen. The KKW02516SF screen is used to handle customer contract succession operations — a business process where service contracts are transferred between customers (e.g., when a property changes ownership in a fiber broadband deployment context). The method accepts a `key` parameter that identifies the type of list item to instantiate, and returns the index of the newly added element in the target list.

It implements the **routing/dispatch design pattern**, branching on the string value of `key` to determine which specific data-bean type should be instantiated and appended to which list collection. It handles three service types of list items: (1) common information beans (keys starting with "//"), delegated to the parent framework; (2) the "Customer Contract Succession List" (顧客契約引継リスト) which uses the `KKW02516SF01DBean` data type with a fixed maximum of 1 element; and (3) the "Reason for Change List" (異動理由リスト) which uses the `KKW02516SF02DBean` data type with no hard-coded capacity limit.

As a view-layer utility called by the screen's own controller logic, this method serves as the **entry point for programmatic list item injection** during user interactions that require adding new rows to repeat-item sections of the form. If the key does not match any known list type or the list has reached its maximum capacity, the method returns -1 or throws an application exception, respectively.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance(key)"])
    CHECK_NULL{key == null}
    CHECK_PREFIX{key starts with //}
    CHECK_REPEATED_1{key == 「顧客契約引続リスト」}
    CHECK_NULL_LIST_1{cust_kei_hktgi_list_list == null}
    CHECK_MAX{size < maxElementCnt}
    REPEAT_LIST_1["cust_kei_hktgi_list_list = new X33VDataTypeList(1)
for loop add KKW02516SF01DBean"]
    CHECK_REPEATED_2{key == 「異動理由リスト」}
    CHECK_NULL_LIST_2{ido_rsn_list_list == null}
    REPEAT_LIST_2["ido_rsn_list_list = new X33VDataTypeList()"]
    CREATE_REPEAT_1["KKW02516SF01DBean tmpBean
cust_kei_hktgi_list_list.add(tmpBean)"]
    CREATE_REPEAT_2["KKW02516SF02DBean tmpBean
ido_rsn_list_list.add(tmpBean)"]
    THROW["throw createExceptionForX31Method
(ERRS_CANNOT_ADD_REPEATITEM)"]
    RET_INDEX_1["return cust_kei_hktgi_list_list.size() - 1"]
    RET_INDEX_2["return ido_rsn_list_list.size() - 1"]
    RET_MINUS1["return -1
no matching item"]
    SUPER["super.addListDataInstance(key)
framework default handler"]

    START --> CHECK_NULL
    CHECK_NULL -->|true| RET_MINUS1
    CHECK_NULL -->|false| CHECK_PREFIX
    CHECK_PREFIX -->|true| SUPER
    CHECK_PREFIX -->|false| CHECK_REPEATED_1
    CHECK_REPEATED_1 -->|true| CHECK_NULL_LIST_1
    CHECK_REPEATED_1 -->|false| CHECK_REPEATED_2
    CHECK_NULL_LIST_1 -->|true| REPEAT_LIST_1
    CHECK_NULL_LIST_1 -->|false| CHECK_MAX
    REPEAT_LIST_1 --> CHECK_MAX
    CHECK_MAX -->|true| CREATE_REPEAT_1
    CHECK_MAX -->|false| THROW
    CREATE_REPEAT_1 --> RET_INDEX_1
    THROW --> RET_MINUS1
    CHECK_REPEATED_2 -->|true| CHECK_NULL_LIST_2
    CHECK_REPEATED_2 -->|false| RET_MINUS1
    CHECK_NULL_LIST_2 -->|true| REPEAT_LIST_2
    CHECK_NULL_LIST_2 -->|false| NOOP
    REPEAT_LIST_2 --> CREATE_REPEAT_2
    NOOP["(no-op, list already exists)"] --> CREATE_REPEAT_2
    CREATE_REPEAT_2 --> RET_INDEX_2
    SUPER --> RET_MINUS1
    RET_INDEX_1 --> END(["End"])
    RET_INDEX_2 --> END
    RET_MINUS1 --> END
```

**Block processing summary:**

1. **Null guard (L1909-1911):** If the `key` parameter is null, the method immediately returns -1, indicating no item was added.
2. **Common information bean dispatch (L1914-1918):** If the key starts with "//", the request is forwarded to the parent framework's `addListDataInstance` method for generic common information bean handling.
3. **Customer Contract Succession List (L1921-1946):** If the key equals "顧客契約引継リスト" (Customer Contract Succession List), the method initializes a new `X33VDataTypeList<1>` with one pre-instantiated `KKW02516SF01DBean` if the list is null, then checks capacity before adding a new bean. If the list is full, it throws `ERRS_CANNOT_ADD_REPEATITEM`. Otherwise, it returns the zero-based index of the newly added element.
4. **Reason for Change List (L1949-1955):** If the key equals "異動理由リスト" (Reason for Change List), the method creates a new empty `X33VDataTypeList` if null, appends a `KKW02516SF02DBean` instance, and returns the new list size minus one.
5. **Default (L1955):** If the key does not match any known type, return -1.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The business label of the list item type to instantiate. It identifies which repeat-item list should receive a new element. For common information beans, keys start with "//". For specific repeat-item lists, the key is the Japanese display name of the list (e.g., "顧客契約引継リスト" or "異動理由リスト"). The key directly determines which data-bean class is created and which target list is modified. |

**Instance fields read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `cust_kei_hktgi_list_list` | `X33VDataTypeList` | The customer contract succession list. Holds a list of `KKW02516SF01DBean` objects representing each contract succession line item. |
| `ido_rsn_list_list` | `X33VDataTypeList` | The reason for change list. Holds a list of `KKW02516SF02DBean` objects representing each reason code for a customer contract change/move. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `KKW02516SFBean.addListDataInstance` | KKW02516SFBean | - | Self-referential (overloaded caller) |

### Called method analysis:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `super.addListDataInstance` | X33VViewBaseBean | - | Delegates common information bean instantiation to the Fujitsu Futurity X33 framework base class. This is a Read/registration operation managed by the framework's bean lifecycle. |
| C | `X33VDataTypeList.<init>` | Framework | - | Allocates a new typed list container (with initial capacity) for either the customer contract succession list or the reason for change list. |
| C | `X33VDataTypeList.add` | Framework | - | Appends a new data-bean instance (`KKW02516SF01DBean` or `KKW02516SF02DBean`) to the target list collection. |
| C | `KKW02516SF01DBean.<init>` | View Bean | - | Creates a new instance of the customer contract succession data bean. This bean contains fields for the contract succession line item data (no database operation — it is a view-level data holder). |
| C | `KKW02516SF02DBean.<init>` | View Bean | - | Creates a new instance of the reason for change data bean. This bean contains fields for the change/reason data (view-level data holder, no direct DB operation). |

**Classification note:** This method operates entirely at the **view bean layer** — it does not perform any direct database CRUD operations or invoke any SC/CBS service components. It manages the in-memory state of list-type form data structures. All data creation (C) is purely object instantiation within the view layer; there are no R/U/D database operations in this method.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKW02516SF | `KKW02516SFBean.addListDataInstance()` (overload) -> `addListDataInstance(key)` | `addListDataInstance [C] in-memory list (no DB)` |

**Notes:**
- The only direct caller found is the parameterless overloaded `addListDataInstance()` method within the same `KKW02516SFBean` class. This overload serves as a convenient no-arg entry point, likely called from the screen controller when the target list type is predetermined or derived from context.
- No other screens or external components directly invoke this method — it is internal to the KKW02516SF screen's bean.

## 6. Per-Branch Detail Blocks

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

> Null guard: return early if no key is provided.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // No item added, null key |

**Block 2** — [ELSE-IF] `(key.startsWith("//"))` — key matches common information bean prefix (L1914)

> Delegates to the framework's default common information bean handler for generic list data. Common information beans are shared UI components used across multiple screens (e.g., dropdown options, reference data).

| # | Type | Code |
|---|------|------|
| 1 | CALL | `super.addListDataInstance(key);` // Framework default handler for common info beans |

**Block 3** — [ELSE-IF] `(key.equals("顧客契約引継リスト"))` [CUSTOMER_CONTRACT_SUCCESSION_LIST] (L1921)

> Handles the Customer Contract Succession List — the primary repeat-item list on this screen. Each element represents a contract succession line item (KKW02516SF01DBean). The list has a fixed initial capacity of 1 and a maximum element count enforced at runtime.

**Block 3.1** — [IF] `(cust_kei_hktgi_list_list == null)` (L1922)

> Initialize a new list with one pre-created element if the list does not yet exist.

| # | Type | Code |
|---|------|------|
| 1 | SET | `cust_kei_hktgi_list_list = new X33VDataTypeList(1);` // Create list with initial capacity of 1 |
| 2 | EXEC | `for(int i=0; i<1; i++) { KKW02516SF01DBean tmpBean = new KKW02516SF01DBean(); cust_kei_hktgi_list_list.add(tmpBean); }` // Pre-instantiate one element (0:1 loop) |

**Block 3.2** — [IF] `(cust_kei_hktgi_list_list.getMaxElementCnt() == 0 || cust_kei_hktgi_list_list.size() < cust_kei_hktgi_list_list.getMaxElementCnt())` (L1930)

> Capacity check: allow the addition only if the list has no max set (0) or is below its max capacity. This prevents adding beyond the configured limit.

| # | Type | Code |
|---|------|------|
| 1 | SET | `KKW02516SF01DBean tmpBean = new KKW02516SF01DBean();` // Create new data bean instance |
| 2 | EXEC | `cust_kei_hktgi_list_list.add(tmpBean);` // Append to list. Initial value setup is defined within the bean itself. // (初期値設定は、各データビューン内で定義) |
| 3 | RETURN | `return cust_kei_hktgi_list_list.size() - 1;` // Return zero-based index of the newly added element |

**Block 3.2.1** — [ELSE] `(capacity exceeded)` (L1936)

> The list has reached its maximum number of elements. Throw an application exception to notify the caller that no more repeat items can be added.

| # | Type | Code |
|---|------|------|
| 1 | THROW | `throw super.createExceptionForX31Method(ERRS_CANNOT_ADD_REPEATITEM);` // Error notification: cannot add more repeat items |

**Block 4** — [ELSE-IF] `(key.equals("異動理由リスト"))` [REASON_FOR_CHANGE_LIST] (L1949)

> Handles the Reason for Change List — a repeat-item list where each element represents a reason code for a customer contract change/move (KKW02516SF02DBean). Unlike the customer contract succession list, this list has no pre-defined initial capacity or max element limit.

| # | Type | Code |
|---|------|------|
| 1 | IF | `(ido_rsn_list_list == null)` (L1950) // Initialize if null |
| 1.1 | SET | `ido_rsn_list_list = new X33VDataTypeList();` // Create empty list (no initial capacity specified) |
| 2 | SET | `KKW02516SF02DBean tmpBean = new KKW02516SF02DBean();` // Create new data bean instance |
| 3 | EXEC | `ido_rsn_list_list.add(tmpBean);` // Append to list. Initial value setup is defined within the bean itself. // (初期値設定は、各データビューン内で定義) |
| 4 | RETURN | `return ido_rsn_list_list.size() - 1;` // Return zero-based index of the newly added element |

**Block 5** — [DEFAULT] (L1955)

> The key does not match any known list type. Return -1 to indicate no item was added.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `cust_kei_hktgi_list_list` | Field | Customer contract succession list — a repeatable list of contract succession line items on the KKW02516SF screen |
| `ido_rsn_list_list` | Field | Reason for change list — a repeatable list of change/reason codes for customer contract modifications |
| 顧客契約引継リスト | Japanese field label | Customer Contract Succession List — the display name used as the key to identify the customer contract succession data type |
| 異動理由リスト | Japanese field label | Reason for Change List — the display name used as the key to identify the change/reason data type |
| X33VDataTypeList | Framework class | Fujitsu Futurity X33 framework typed list container for repeat-item form data |
| KKW02516SF01DBean | View bean | Customer contract succession data bean — holds fields for a single contract succession line item |
| KKW02516SF02DBean | View bean | Reason for change data bean — holds fields for a single change/reason entry |
| ERRS_CANNOT_ADD_REPEATITEM | Exception constant | Application error code indicating that the maximum number of repeat items has been reached and no more can be added |
| X33VViewBaseBean | Framework superclass | Base class for all X33 framework view beans; provides bean lifecycle management and framework-level `addListDataInstance` |
| X31CBaseBean | Interface | X31 framework interface for base bean operations |
| X33VListedBeanInterface | Interface | X33 framework interface for beans that manage list-type repeat items |
| common information bean | Domain concept | A shared UI data bean (key starts with "//") managed by the framework's default handler, used for reference/dropdown data across screens |
| KKW02516SF | Screen code | Customer contract succession screen — the web screen for handling contract succession operations when ownership transfers |
| repeat-item | Domain concept | A form data section that can contain zero or more rows of the same data structure (e.g., multiple contract line items) |
| K-Opticom | Company | Japanese telecommunications provider — the organization that owns and operates this fiber broadband service platform |