# Business Logic — KKW00127SF02DBean.addListDataInstance() [50 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW00127SF.KKW00127SF02DBean` |
| Layer | Controller / View Data Bean (Package: `eo.web.webview.KKW00127SF`) |
| Module | `KKW00127SF` (Package: `eo.web.webview.KKW00127SF`) |

## 1. Role

### KKW00127SF02DBean.addListDataInstance()

This method is a **list item instance factory and dispatcher** within the KKW00127SF screen data bean. It is responsible for creating and managing repeatable list data structures used by the service contract agreement confirmation screen — the UI screen that displays, allows editing of, and submits service contract consent notices. The method operates as a **string-key-based dispatch (routing) pattern**, where the incoming `key` parameter is matched against Japanese display labels to determine which internal list field should receive a new element. It currently handles two supported list types: the Service Contract Status List (`サービス契約ステータスリスト`), which tracks the status of service contract lines, and the Introduction Code List (`紹介コードリスト`), which stores referral/introduction codes associated with the contract. Both lists use `X33VDataTypeStringBean` as their element type — a framework-managed value type for repeatable string fields within the Fujitsu Futurity X33 web framework. The method also enforces maximum element count constraints, throwing a framework exception if an addition would exceed the allowed list size. As a shared utility invoked by multiple downstream screens (via the `super.addListDataInstance(key)` delegation pattern observed in FUW* screen beans), this method serves as a **key-driven list growth mechanism** that ensures consistent instantiation and bounds-checking across the application's view layer.

## 2. Processing Pattern (Detailed Business Logic)

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

    START --> C1{"key is null?"}

    C1 -->|true| R1["Return -1"]
    C1 -->|false| C2{"key equals Service Contract Status List?"}

    C2 -->|true| C3{"svc_kei_stat_lis_list is null?"}
    C2 -->|false| C4{"key equals Introduction Code List?"}

    C3 -->|true| N1["svc_kei_stat_lis_list = new X33VDataTypeList(1)
loop add X33VDataTypeStringBean"]
    C3 -->|false| C5{"size < maxElementCnt or maxElementCnt = 0?"}
    N1 --> C5

    C5 -->|true| A1["X33VDataTypeStringBean tmpBean = new
svc_kei_stat_lis_list.add(tmpBean)"]
    A1 --> R2["Return svc_kei_stat_lis_list.size() - 1"]
    C5 -->|false| E1["throw ERRS_CANNOT_ADD_REPEATITEM"]

    C4 -->|true| C6{"intr_cd_list_list is null?"}
    C4 -->|false| R3["Return -1"]

    C6 -->|true| N2["intr_cd_list_list = new X33VDataTypeList(1)
loop add X33VDataTypeStringBean"]
    C6 -->|false| C7{"size < maxElementCnt or maxElementCnt = 0?"}
    N2 --> C7

    C7 -->|true| A2["X33VDataTypeStringBean tmpBean = new
intr_cd_list_list.add(tmpBean)"]
    A2 --> R4["Return intr_cd_list_list.size() - 1"]
    C7 -->|false| E2["throw ERRS_CANNOT_ADD_REPEATITEM"]
```

**Processing flow summary:**
1. **Null check** — If `key` is null, immediately return -1 (invalid key rejection).
2. **Branch 1: Service Contract Status List** — If `key` equals `"サービス契約ステータスリスト"` (Service Contract Status List), initialize the `svc_kei_stat_lis_list` list if null, then check capacity constraints before appending a new `X33VDataTypeStringBean` instance. Returns the index of the newly added element.
3. **Branch 2: Introduction Code List** — If `key` equals `"紹介コードリスト"` (Introduction Code List), follow the same initialization, capacity-check, and append pattern against the `intr_cd_list_list` field. Returns the index of the newly added element.
4. **Fallback** — If the key does not match any supported list type, return -1 (unknown/unsupported item).
5. **Capacity overflow** — If either list has reached its `maxElementCnt` limit, throw an `X33SException` via the framework's `createExceptionForDataType` utility.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The display label (Japanese name) of the list item whose instance is to be created. It acts as a dispatch key that determines which internal list field will receive a new element. Possible values: `"サービス契約ステータスリスト"` (Service Contract Status List — item ID: `svc_kei_stat_lis`) or `"紹介コードリスト"` (Introduction Code List — item ID: `intr_cd_list`). Any other value or `null` results in a -1 return code, indicating the item is not supported for instance creation. |

**Instance fields read by this method:**
| No | Field Name | Type | Business Description |
|----|-----------|------|---------------------|
| 1 | `svc_kei_stat_lis_list` | `X33VDataTypeList` | Service contract status list — a repeatable string field storing the status of each service contract line item in the consent notice |
| 2 | `intr_cd_list_list` | `X33VDataTypeList` | Introduction code list — a repeatable string field storing referral/introduction codes associated with the service contract |

## 4. CRUD Operations / Called Services

This method performs **no external service calls, no database access, and no CBS invocations**. All operations are in-memory list manipulations within the view data bean. The only operations are internal list management:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| C (Create) | `X33VDataTypeList.add()` | N/A (framework) | N/A (in-memory) | Creates a new list element (X33VDataTypeStringBean instance) within the target repeatable list. |
| C (Create) | `X33VDataTypeStringBean()` constructor | N/A (framework) | N/A (in-memory) | Instantiates a new string value type bean for addition to the list. |
| E (Error) | `X33VViewBaseBean.createExceptionForDataType()` | N/A (framework) | N/A (in-memory) | Throws a framework exception when the list has reached its maximum element count and no further additions are permitted. |

**Note:** This is a pure view-layer method. It does not interact with any SC (Service Component), CBS (Business Component Service), or database tables. Data persistence would be handled by the screen's submit process, not by this factory method.

## 5. Dependency Trace

This method is called via the inheritance chain from the X33V framework's base bean (`X33VViewBaseBean`). The pattern observed across the codebase is that child screen beans (e.g., `FUW00901SFBean`, `FUW00912SFBean`, `FUW00926SFBean`, `FUW00927SFBean`, `FUW00931SFBean`, `FUW00942SFBean`, `FUW00946SFBean`, `FUW00947SFBean`, `FUW00957SFBean`, `FUW00959SFBean`, `FUW00961SFBean`, `FUW00964SFBean`, `FUW00965SFBean`, `FUW00902SFBean`, `FUW00907SFBean`, `FUW00909SFBean`, `FUW00914SFBean`, `FUW00916SFBean`, `FUW00917SFBean`, `FUW00919SFBean`) override this method and delegate unmatched keys to `super.addListDataInstance(key)`, which routes back to this implementation.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Bean: FUW00901SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 2 | Bean: FUW00902SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 3 | Bean: FUW00907SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 4 | Bean: FUW00909SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 5 | Bean: FUW00912SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 6 | Bean: FUW00914SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 7 | Bean: FUW00916SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 8 | Bean: FUW00917SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 9 | Bean: FUW00919SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 10 | Bean: FUW00926SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 11 | Bean: FUW00927SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 12 | Bean: FUW00931SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 13 | Bean: FUW00942SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 14 | Bean: FUW00946SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |
| 15 | Bean: FUW00947SF | `super.addListDataInstance(key)` -> `KKW00127SF02DBean.addListDataInstance` | in-memory list add (C) |

**Note:** All callers use the delegation pattern `return super.addListDataInstance(key)`, meaning the incoming key is first processed by the child bean's own branches, and any unmatched keys fall through to this parent implementation. The FUW* beans handle their own domain-specific list types (e.g., "代理店コードリスト" / Agency Code List) in their overrides, then delegate the rest to this method for the shared Service Contract Status List and Introduction Code List types.

## 6. Per-Branch Detail Blocks

**Block 1** — IF `(key == null)` (L899)

> Null guard: Rejects null keys immediately, returning -1 to signal that no item is being created. This prevents NullPointerException in subsequent `equals()` checks.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // null key rejected; no instance created |

**Block 2** — ELSE-IF `(key.equals("サービス契約ステータスリスト"))` [Service Contract Status List] (L903)

> Branch 1: Handles the Service Contract Status List. This is a repeatable string list that stores status values for each line in the service contract consent notice. The list is lazily initialized on first access.

**Block 2.1** — IF `(svc_kei_stat_lis_list == null)` (L904)

> Lazy initialization: If the list has not been created yet, instantiate it with a max element count of 1 and pre-add one element.

| # | Type | Code |
|---|------|------|
| 1 | SET | `svc_kei_stat_lis_list = new X33VDataTypeList(1);` // Initialize list with maxElementCnt=1 |
| 2 | EXEC | `for(int i=0; i<1; i++) { ... }` // Loop: add initial element |
| 3 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create new string bean |
| 4 | EXEC | `svc_kei_stat_lis_list.add(tmpBean);` // Pre-add one element to the list |

**Block 2.2** — ELSE (svc_kei_stat_lis_list != null) (L904)

> List already initialized; skip initialization.

| # | Type | Code |
|---|------|------|
| 1 | (implicit) | // Skip: list already initialized |

**Block 2.3** — IF `(svc_kei_stat_lis_list.getMaxElementCnt() == 0 \|\| svc_kei_stat_lis_list.size() < svc_kei_stat_lis_list.getMaxElementCnt())` (L912)

> Capacity check: Determines whether the list has room for another element. A maxElementCnt of 0 means unlimited capacity.

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Instantiate new string-type repeatable item bean |
| 2 | EXEC | `svc_kei_stat_lis_list.add(tmpBean);` // Append the new bean to the list |
| 3 | RETURN | `return svc_kei_stat_lis_list.size() - 1;` // Return the 0-based index of the newly added element |

**Block 2.4** — ELSE (capacity reached) (L915)

> The list has reached its maximum element count. No further additions are permitted.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `throw X33VViewBaseBean.createExceptionForDataType(X33VViewBaseBean.ERRS_CANNOT_ADD_REPEATITEM);` // Throw framework exception for capacity overflow |

**Block 3** — ELSE-IF `(key.equals("紹介コードリスト"))` [Introduction Code List] (L922)

> Branch 2: Handles the Introduction Code List. This is a repeatable string list that stores referral/introduction codes associated with the service contract. Follows the same lazy-initialization, capacity-check, and append pattern as Block 2.

**Block 3.1** — IF `(intr_cd_list_list == null)` (L923)

> Lazy initialization: If the list has not been created yet, instantiate it with a max element count of 1 and pre-add one element.

| # | Type | Code |
|---|------|------|
| 1 | SET | `intr_cd_list_list = new X33VDataTypeList(1);` // Initialize list with maxElementCnt=1 |
| 2 | EXEC | `for(int i=0; i<1; i++) { ... }` // Loop: add initial element |
| 3 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Create new string bean |
| 4 | EXEC | `intr_cd_list_list.add(tmpBean);` // Pre-add one element to the list |

**Block 3.2** — ELSE (intr_cd_list_list != null) (L923)

> List already initialized; skip initialization.

| # | Type | Code |
|---|------|------|
| 1 | (implicit) | // Skip: list already initialized |

**Block 3.3** — IF `(intr_cd_list_list.getMaxElementCnt() == 0 \|\| intr_cd_list_list.size() < intr_cd_list_list.getMaxElementCnt())` (L931)

> Capacity check: Determines whether the introduction code list has room for another element.

| # | Type | Code |
|---|------|------|
| 1 | SET | `X33VDataTypeStringBean tmpBean = new X33VDataTypeStringBean();` // Instantiate new string-type repeatable item bean |
| 2 | EXEC | `intr_cd_list_list.add(tmpBean);` // Append the new bean to the list |
| 3 | RETURN | `return intr_cd_list_list.size() - 1;` // Return the 0-based index of the newly added element |

**Block 3.4** — ELSE (capacity reached) (L934)

> The list has reached its maximum element count. No further additions are permitted.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `throw X33VViewBaseBean.createExceptionForDataType(X33VViewBaseBean.ERRS_CANNOT_ADD_REPEATITEM);` // Throw framework exception for capacity overflow |

**Block 4** — ELSE (default/fallthrough) (L939)

> Unmatched key: The `key` parameter does not match any supported list type. Return -1 to indicate that no instance was created.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // No matching key found; indicate no item was created |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `サービス契約ステータスリスト` | Field/Key | Service Contract Status List — the Japanese display label for the list item that manages repeatable service contract status values (item ID: `svc_kei_stat_lis`) |
| `紹介コードリスト` | Field/Key | Introduction Code List — the Japanese display label for the list item that manages repeatable referral/introduction codes (item ID: `intr_cd_list`) |
| `svc_kei_stat_lis_list` | Field | Service contract status list — internal field storing a list of `X33VDataTypeStringBean` instances representing the status of each service contract line item |
| `intr_cd_list_list` | Field | Introduction code list — internal field storing a list of `X33VDataTypeStringBean` instances representing referral codes associated with the service contract |
| `svc_kei_stat_lis` | Field | Service detail status list — item identifier used as the item ID for the service contract status list within the X33 framework's data binding system |
| `intr_cd` | Field | Introduction code — item identifier for the referral code list item |
| `X33VDataTypeList` | Type | Framework list container — a value type list from the Fujitsu Futurity X33 framework that manages collections of typed elements with max element count constraints |
| `X33VDataTypeStringBean` | Type | Framework string value bean — a repeatable string value type class from the X33 framework; each instance represents one element in a repeatable list field |
| `X33VViewBaseBean` | Type | Framework base bean — the base class for view data beans in the X33 framework; provides exception creation utilities and the parent `addListDataInstance` method |
| `X31CBaseBean` | Type | X31 base bean — the foundational base bean class in the X31 framework layer, providing common bean functionality |
| `X33SException` | Type | X33 system exception — the exception class used by the X33 framework to signal runtime errors in view beans |
| `ERRS_CANNOT_ADD_REPEATITEM` | Constant | Framework error constant — indicates that a repeatable list item has reached its maximum element count and cannot accept further additions |
| `KKW00127SF` | Module | Service contract agreement confirmation screen module — the screen module responsible for displaying, editing, and submitting service contract consent notices |
| `KKW00127SF02DBean` | Class | Service contract agreement confirmation screen 02 Data Bean — the view data bean class that holds the screen's input/output data including repeatable lists |
| `KKW00127SFBean` | Class | Service contract agreement confirmation screen main bean — the parent screen bean that delegates list item key resolution to child beans including KKW00127SF02DBean |
| Data Type Bean | Pattern | A bean that implements `X33VDataTypeBeanInterface` and represents structured data (as opposed to simple scalar value types) within a repeatable list |
| Repeatable List Item | Concept | A list field that can hold multiple instances of the same data type; used in the UI to display rows of tabular data (e.g., multiple service contract line items) |
| Lazy Initialization | Pattern | Initializing a list field only on its first access, rather than at bean construction time, to avoid unnecessary object allocation |
| FUW00*SF* | Screen | Web screen bean classes that extend or delegate to the base list data instance mechanism; each handles its own domain-specific list types and delegates unknown keys to parent implementations |
| Service Contract | Business term | An agreement between K-Opticom and a customer for telecommunication services; the screen KKW00127SF manages the consent notice for such agreements |
| Introduction Code | Business term | A referral or introduction code associated with a service contract, typically used for tracking customer referral sources |