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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW00816SF.KKW00816SFBean` |
| Layer | Web/View Controller Bean (Web MVC screen data bean) |
| Module | `KKW00816SF` (Package: `eo.web.webview.KKW00816SF`) |

## 1. Role

### KKW00816SFBean.addListDataInstance()

This method instantiates and registers new element instances into type-specific list data structures that represent repeatable customer contract line items on the KKSV00816 (Customer Contract Management) screen. It serves as the screen's central factory for list data elements, routing incoming item-name keys to the correct concrete bean type and list container.

The method implements a **dispatch/routing pattern**: it inspects the `key` parameter to determine which list data type the caller is requesting, then creates a new bean instance of the appropriate sub-view type (`KKW00816SF01DBean` for "Customer Contract Inheritance List" items, `KKW00816SF02DBean` for "Option Service Contract List" items) and appends it to the corresponding in-memory list. It also delegates common-data-bien (共通情報ビューン) requests — those whose key starts with `//` — to the superclass implementation.

In the larger system, this method is the entry point for populating repeatable data grids on a customer contract management screen. Each invocation adds a single new row to the screen's data model, allowing operators to build up dynamic lists of customer contract inheritances and option service contracts before submission.

When the input `key` does not match any recognized item, the method returns `-1` to signal an unrecognized item, enabling the caller to handle the unknown key gracefully.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance key"])
    CHECK_NULL{"key == null"}
    COMMON_CHECK{"key starts with //"}
    CUSTOMER_CHECK{"key == Customer Contract Inheritance List"}
    NULL_LIST{"cust_kei_hktgi_list_list == null?"}
    INIT_LIST["new X33VDataTypeList(1) loop add KKW00816SF01DBean"]
    SIZE_CHECK{"size < maxElementCnt?"}
    ADD_BEAN1["new KKW00816SF01DBean add to list"]
    THROW_EXC["throw createExceptionForX31Method ERRS_CANNOT_ADD_REPEATITEM"]
    RETURN1["return size - 1"]
    OPTION_CHECK{"key == Option Service Contract List"}
    OPTION_NULL{"op_svc_kei_list_list == null?"}
    INIT_OPTION["new X33VDataTypeList"]
    ADD_BEAN2["new KKW00816SF02DBean add to list"]
    RETURN2["return size - 1"]
    RETURN_DEFAULT["return -1"]
    COMMON_DELEGATE["super.addListDataInstance key"]
    RETURN_COMMON["return result"]
    END_EXCEPTION(["End - Exception"])

    START --> CHECK_NULL
    CHECK_NULL -->|Yes| RETURN_DEFAULT
    CHECK_NULL -->|No| COMMON_CHECK
    COMMON_CHECK -->|Yes| COMMON_DELEGATE
    COMMON_DELEGATE --> RETURN_COMMON
    COMMON_CHECK -->|No| CUSTOMER_CHECK
    CUSTOMER_CHECK -->|Yes| NULL_LIST
    CUSTOMER_CHECK -->|No| OPTION_CHECK
    NULL_LIST -->|Yes| INIT_LIST
    INIT_LIST --> SIZE_CHECK
    NULL_LIST -->|No| SIZE_CHECK
    SIZE_CHECK -->|Yes| ADD_BEAN1
    SIZE_CHECK -->|No| THROW_EXC
    ADD_BEAN1 --> RETURN1
    THROW_EXC --> END_EXCEPTION
    OPTION_CHECK -->|Yes| OPTION_NULL
    OPTION_CHECK -->|No| RETURN_DEFAULT
    OPTION_NULL -->|Yes| INIT_OPTION
    INIT_OPTION --> ADD_BEAN2
    OPTION_NULL -->|No| ADD_BEAN2
    ADD_BEAN2 --> RETURN2
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The item name (in Japanese) that identifies which list data type to instantiate. It acts as a dispatch key that determines which concrete bean and list container to use. Valid values include `"顧客契約引継リスト"` (Customer Contract Inheritance List) and `"オプションサービス契約リスト"` (Option Service Contract List). Keys starting with `//` indicate a common-data-bien (共通情報ビューン — common information view) item delegated to the superclass. If `null`, the method returns `-1` immediately. |
| — | `cust_kei_hktgi_list_list` | `X33VDataTypeList` (instance field) | The in-memory list container for "Customer Contract Inheritance List" items, holding `KKW00816SF01DBean` elements. Read for null-check and size validation; written when a new element is added or when the list is first instantiated. |
| — | `op_svc_kei_list_list` | `X33VDataTypeList` (instance field) | The in-memory list container for "Option Service Contract List" items, holding `KKW00816SF02DBean` elements. Read for null-check; written when a new element is added. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| I | `KKW00816SFBean.addListDataInstance` | KKW00816SFBean | - | Calls `addListDataInstance` in `KKW00816SFBean` (internal list data instance factory) |

### Detailed method-call analysis:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| I | `X33VDataTypeList.add()` | X33VDataTypeList | - (in-memory) | Creates a new in-memory list data instance by appending a bean to `cust_kei_hktgi_list_list`. Used for "Customer Contract Inheritance List". |
| I | `X33VDataTypeList.add()` | X33VDataTypeList | - (in-memory) | Creates a new in-memory list data instance by appending a bean to `op_svc_kei_list_list`. Used for "Option Service Contract List". |
| I | `super.addListDataInstance(key)` | X33VDataTypeBean (superclass) | - (in-memory) | Delegates common-data-bien item instantiation to the parent class for keys starting with `//`. |
| E | `createExceptionForX31Method(ERRS_CANNOT_ADD_REPEATITEM)` | X33VDataTypeBean (superclass) | - | Throws an exception when attempting to add an element beyond the maximum allowed count for a repeatable list. |

**Classification rationale:** This method operates entirely in-memory on the view bean layer. No database or SC/CBS calls are made directly. It instantiates new list element beans and inserts them into in-memory `X33VDataTypeList` containers. The "Create" (I = Insert) classification refers to in-memory data creation, not database persistence.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKSV00816 | `KKW00816SFBean.addListDataInstance(key)` | in-memory X33VDataTypeList insert |

**Notes:** The only pre-identified caller is `KKW00816SFBean.addListDataInstance()` (the no-arg overload), which is itself a method within the same class. This overload is typically invoked from the screen controller during user actions such as "Add New Row" buttons on the Customer Contract Management screen, where the caller reads a UI action parameter and delegates to this key-based method.

## 6. Per-Branch Detail Blocks

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

> If `key` is `null`, return `-1` immediately. This guards against null-pointer exceptions and signals to the caller that no valid item was found.

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

**Block 2** — ELSE-IF (common data-bien check) (L2353)

> If the key starts with `//`, delegate to the superclass's `addListDataInstance` method. This handles common-data-bien (共通情報ビューン — common information view) items that follow a shared instantiation pattern defined in the parent class.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `key.startsWith("//")` // 共通情報ビューンの場合 — if it is a common information view item |
| 2 | CALL | `super.addListDataInstance(key)` // 共通情報ビューンリストは基底クラスで処理 — common data-bien list is processed by the base class |
| 3 | RETURN | `return super.addListDataInstance(key);` |

**Block 3** — ELSE-IF ("Customer Contract Inheritance List") (L2359)

> Handles the item `"顧客契約引継リスト"` (Customer Contract Inheritance List). This is a repeatable list with a fixed maximum element count of 1 and uses `KKW00816SF01DBean` as the data bean type.

**Block 3.1** — IF (list null check) (L2360)

> If the list is `null`, create a new `X33VDataTypeList` with a maximum element count of 1 and pre-initialize it with one bean instance. This prepares the list for subsequent add operations.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `cust_kei_hktgi_list_list == null` // リストがnullの場合、新しい空のインスタンスを生成 — if list is null, generate new empty instance |
| 2 | SET | `cust_kei_hktgi_list_list = new X33VDataTypeList(1);` // Maximum element count = 1 (fixed) |
| 3 | FOR | `for(int i=0; i<1; i++)` — loop runs exactly 1 iteration |
| 4 | SET | `KKW00816SF01DBean tmpBean = new KKW00816SF01DBean();` // データタイプビューン型で指定したデータタイプビューンのインスタンスを生成 — generate instance of specified data-type view bean |
| 5 | CALL | `cust_kei_hktgi_list_list.add(tmpBean);` |

**Block 3.2** — IF (max element count check) (L2370)

> Check if the current list size is within the allowed maximum. If so, add a new `KKW00816SF01DBean` instance. The max element count is determined by `getMaxElementCnt()` — when it returns 0, there is no maximum limit.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `cust_kei_hktgi_list_list.getMaxElementCnt() == 0 \|\| cust_kei_hktgi_list_list.size() < cust_kei_hktgi_list_list.getMaxElementCnt()` // MAX要素数以上の追加は許されない処理 — adding beyond max element count is not permitted |
| 2 | SET | `KKW00816SF01DBean tmpBean = new KKW00816SF01DBean();` // データタイプビューン型のインスタンスを生成 — generate data-type view bean instance |
| 3 | SET | `cust_kei_hktgi_list_list.add(tmpBean);` // リストに追加 — add to list |
| 4 | RETURN | `return cust_kei_hktgi_list_list.size() - 1;` // Return the index of the newly added element |

**Block 3.3** — ELSE (max element exceeded) (L2377)

> If the list has reached its maximum allowed element count, throw an exception to prevent adding more items.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `throw super.createExceptionForX31Method(ERRS_CANNOT_ADD_REPEATITEM);` // 異常通知 — error notification |

**Block 4** — ELSE-IF ("Option Service Contract List") (L2384)

> Handles the item `"オプションサービス契約リスト"` (Option Service Contract List). This list has no fixed initial element count and uses `KKW00816SF02DBean` as the data bean type. It does NOT enforce a maximum element count check — elements are always appended.

**Block 4.1** — IF (list null check) (L2385)

> If the list is `null`, create a new default `X33VDataTypeList`.

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

**Block 4.2** — Unconditional (no else branch) (L2389)

> Always adds a new `KKW00816SF02DBean` instance and returns its index. No max element check is performed for this list type.

| # | Type | Code |
|---|------|------|
| 1 | SET | `KKW00816SF02DBean tmpBean = new KKW00816SF02DBean();` // データタイプビューン型のインスタンスを生成 — generate data-type view bean instance |
| 2 | CALL | `op_svc_kei_list_list.add(tmpBean);` |
| 3 | RETURN | `return op_svc_kei_list_list.size() - 1;` |

**Block 5** — ELSE (unrecognized key) (L2392)

> If the key does not match any known item name, return `-1` to indicate the item is not recognized.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `key` | Parameter | Item name (in Japanese) used to dispatch to the correct list data type. Acts as a routing key for the add-list-data-instance factory method. |
| `顧客契約引継リスト` | Field/UI Item | "Customer Contract Inheritance List" — the list of customer contract inheritance items. Uses `KKW00816SF01DBean` as its data bean type. |
| `オプションサービス契約リスト` | Field/UI Item | "Option Service Contract List" — the list of optional service contract items. Uses `KKW00816SF02DBean` as its data bean type. |
| `cust_kei_hktgi_list_list` | Instance Field | In-memory list storing `KKW00816SF01DBean` instances for customer contract inheritance items. |
| `op_svc_kei_list_list` | Instance Field | In-memory list storing `KKW00816SF02DBean` instances for option service contract items. |
| 共通情報ビューン | Japanese Term | "Common Information View" — a shared view type prefixed with `//` in the key. Processed by the superclass rather than the view-specific bean. |
| `X33VDataTypeList` | Type | A generic typed list container from the X33 view framework, providing methods like `add()`, `size()`, `getMaxElementCnt()` for managing repeatable data structures. |
| `KKW00816SF01DBean` | Class | Data bean for individual rows in the Customer Contract Inheritance List. Contains fields specific to customer contract inheritance operations. |
| `KKW00816SF02DBean` | Class | Data bean for individual rows in the Option Service Contract List. Contains fields specific to option service contract operations. |
| `ERRS_CANNOT_ADD_REPEATITEM` | Constant | Error message key indicating that a repeatable list item cannot be added (typically because the maximum element count has been reached). |
| `X33SException` | Exception | Framework exception class thrown by view beans when business rules are violated. |
| `createExceptionForX31Method` | Method | Superclass utility that wraps error constants into `X33SException` instances. |
| `KKW00816SFBean` | Class | The screen data bean for the KKSV00816 screen (Customer Contract Management). Holds all view-level state including repeatable lists. |
| KKSV00816 | Screen ID | Customer Contract Management screen — the web screen that uses this bean for managing customer contract inheritance and option service contract lists. |