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

| Field | Value |
|-------|-------|
| Fully Qualified Name | `eo.web.webview.KKW01037SF.KKW01037SFBean` |
| Layer | View Bean / Web Component (Service Component — view layer within the X33V framework) |
| Module | `KKW01037SF` (Package: `eo.web.webview.KKW01037SF`) |

## 1. Role

### KKW01037SFBean.addListDataInstance()

This method is the central dispatcher for dynamically constructing list-item data instances in the **Customer Contract Service** screen (`KKW01037SF`). It operates as a **typed factory and router**: given a logical key name, it determines which domain-specific list to append to, instantiates the correct data-bean type, and returns the index of the newly added element.

The method handles **three categories of input keys**: (1) **Common information views** — keys starting with `//` are delegated to the superclass's `addListDataInstance` for generic X33V framework rendering; (2) **Service Contract List** — a data-type view item (`サービス契約一覧リスト`) that constructs entries of type `KKW01037SF01DBean`; (3) **Customer Contract Handover List** — a fixed-element-count repeat view item (`顧客契約引継リスト`) that constructs entries of type `KKW01037SF02DBean` with a max-element guard to prevent exceeding the allowed list size.

Its role in the larger system is to provide a **unified extension point** for the X33V view bean framework. By centralizing list-item creation logic, the method allows screen-level code to request new list entries via a simple string key without needing to know the underlying bean types or list initialization rules. This pattern follows the **Strategy dispatch** design — the key acts as a discriminator that selects the appropriate instantiation strategy.

The method returns an `int` index (0-based position of the added element) for successful additions, `-1` for null input or unrecognized keys, and throws an `X31CException` if the customer contract handover list exceeds its maximum element count.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addListDataInstance String key"])
    COND_NULL{"key is null"}
    COND_COMMENT{key starts with double-slash}
    COND_SVC{key equals service contract list label}
    COND_CUST{key equals customer contract handover list label}
    SVC_NULL{svc_kei_list_list is null}
    SVC_INIT["svc_kei_list_list = new X33VDataTypeList"]
    SVC_NEW["KKW01037SF01DBean tmpBean"]
    SVC_ADD["svc_kei_list_list.add tmpBean"]
    SVC_RETURN["return svc_kei_list_list.size minus 1"]
    CUST_NULL{cust_kei_hktgi_list_list is null}
    CUST_INIT["cust_kei_hktgi_list_list = new X33VDataTypeList 1"]
    CUST_INIT_BEAN["KKW01037SF02DBean tmpBean for init loop"]
    CUST_INIT_ADD["cust_kei_hktgi_list_list.add tmpBean"]
    CUST_CHECK{maxElementCnt equals 0 OR size lt maxElementCnt}
    CUST_NEW["KKW01037SF02DBean tmpBean"]
    CUST_ADD["cust_kei_hktgi_list_list.add tmpBean"]
    CUST_RETURN["return cust_kei_hktgi_list_list.size minus 1"]
    CUST_THROW["throw createExceptionForX31Method ERRS_CANNOT_ADD_REPEATITEM"]
    RETURN_MINUS1["return -1"]
    SUPER_CALL["super.addListDataInstance key"]

    START --> COND_NULL
    COND_NULL -->|true| RETURN_MINUS1
    COND_NULL -->|false| COND_COMMENT
    COND_COMMENT -->|true| SUPER_CALL
    SUPER_CALL --> END_NODE(["End"])
    COND_COMMENT -->|false| COND_SVC
    COND_SVC -->|true| SVC_NULL
    SVC_NULL -->|true| SVC_INIT
    SVC_NULL -->|false| SVC_NEW
    SVC_INIT --> SVC_NEW
    SVC_NEW --> SVC_ADD
    SVC_ADD --> SVC_RETURN
    SVC_RETURN --> END_NODE
    COND_SVC -->|false| COND_CUST
    COND_CUST -->|true| CUST_NULL
    CUST_NULL -->|true| CUST_INIT
    CUST_NULL -->|false| CUST_CHECK
    CUST_INIT --> CUST_INIT_BEAN
    CUST_INIT_BEAN --> CUST_INIT_ADD
    CUST_INIT_ADD --> CUST_CHECK
    CUST_CHECK -->|true| CUST_NEW
    CUST_CHECK -->|false| CUST_THROW
    CUST_NEW --> CUST_ADD
    CUST_ADD --> CUST_RETURN
    CUST_RETURN --> END_NODE
    CUST_THROW --> END_NODE
    COND_CUST -->|false| RETURN_MINUS1
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `key` | `String` | The logical identifier of the list item type to instantiate. Maps to a domain-specific view category: `//`-prefixed keys delegate to common information views, `"サービス契約一覧リスト"` (Service Contract List) triggers `KKW01037SF01DBean` creation for service contract line items, and `"顧客契約引継リスト"` (Customer Contract Handover List) triggers `KKW01037SF02DBean` creation for customer contract handover entries. |

**Instance fields read by this method:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `svc_kei_list_list` | `X33VDataTypeList` | The service contract list — holds the collection of `KKW01037SF01DBean` instances representing individual service contract line items on the screen. |
| `cust_kei_hktgi_list_list` | `X33VDataTypeList` | The customer contract handover list — holds the collection of `KKW01037SF02DBean` instances representing customer contract handover entries. Initialized with a max element count of 1 in the constructor. |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| CALL | `KKW01037SFBean.addListDataInstance` | - | - | Calls `super.addListDataInstance(key)` — delegates common information view items to the X33V base view bean framework |
| - | `KKW01037SF01DBean` constructor | - | - | Creates a new data-type view bean instance for a service contract list entry |
| - | `KKW01037SF02DBean` constructor | - | - | Creates a new data-type view bean instance for a customer contract handover entry |
| C | `svc_kei_list_list.add()` | - | - | Adds a new `KKW01037SF01DBean` instance to the service contract list |
| C | `cust_kei_hktgi_list_list.add()` | - | - | Adds a new `KKW01037SF02DBean` instance to the customer contract handover list |
| U | `cust_kei_hktgi_list_list` init | - | - | Initializes `cust_kei_hktgi_list_list` with a max element count of 1 and pre-populates it with one `KKW01037SF02DBean` |

**Classification notes:** This method operates entirely at the **view bean level** — it does not directly invoke any SC (Service Component) or CBS (business logic component) classes. All operations are in-memory list manipulations within the X33V framework. The actual database CRUD operations (Create/Read/Update/Delete) would be triggered later by the screen's submit/handler flow, not within this method.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKW01037SF | `KKW01037SFBean.addListDataInstance()` (no-arg overload) -> `addListDataInstance(key)` | `addListDataInstance(key) [C] svc_kei_list_list`, `addListDataInstance(key) [C] cust_kei_hktgi_list_list` |

**Caller details:**

| # | Caller (Screen/Batch) | Details |
|---|----------------------|---------|
| 1 | `KKW01037SFBean.addListDataInstance()` (no-arg overload) | Same-class overload that delegates to the key-based version. Found in the same `KKW01037SFBean` class. |

The pre-computed caller graph shows only one direct caller: a **no-arg overload** of the same method within `KKW01037SFBean`, which serves as a convenience entry point that delegates to the key-based version. This is a common pattern in view beans where a default key (or the first configured list item) is created by the screen framework at initialization time.

## 6. Per-Branch Detail Blocks

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

> Null guard: if the caller passes a null key, return -1 immediately to prevent NullPointerException in subsequent string operations.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return -1;` // Null check — if key is null, return -1 (日本語: nullの場合、-1で返す) |

**Block 2** — [ELSE-IF] `(key.startsWith("//"))` (L741)

> Common information view delegation: keys starting with `//` indicate common/generic information view items. These are handled by the X33V base framework superclass, not by this domain-specific bean. Returns the result of the superclass method.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `super.addListDataInstance(key)` // Delegate to superclass (日本語: 共通情報ビューのケース、共通情報ビューリストは基底クラスで処理) |

**Block 3** — [ELSE-IF] `(key.equals("サービス契約一覧リスト"))` (L746)

> Service Contract List (サービス契約一覧リスト) instantiation: creates a new entry in the service contract list for the "Service Contract List" data-type view. This view represents individual service contract line items displayed on the screen.

| # | Type | Code |
|---|------|------|
| 1 | IF (nested) | `if (svc_kei_list_list == null)` // Check if the list instance is null (日本語: リストがnullの場合、新しい空のインスタンスを生成する) |
| 2 | SET (nested) | `svc_kei_list_list = new X33VDataTypeList()` // Initialize new empty list (日本語: リストがnullの場合、新しい空のインスタンスを生成する) |
| 3 | SET (nested) | `KKW01037SF01DBean tmpBean = new KKW01037SF01DBean()` // Create new data-type view bean instance (日本語: データタイプビュー型の指定したデータタイプビューのインスタンスを生成する) |
| 4 | EXEC (nested) | `svc_kei_list_list.add(tmpBean)` // Add the bean to the list |
| 5 | RETURN (nested) | `return svc_kei_list_list.size() - 1` // Return 0-based index of the added element |

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

> Customer Contract Handover List (顧客契約引継リスト) instantiation: creates a new entry in the customer contract handover list for the "Customer Contract Handover List" data-type view. This view represents customer contract handover entries with a maximum element count guard.

| # | Type | Code |
|---|------|------|
| 1 | IF (nested) | `if (cust_kei_hktgi_list_list == null)` // Check if the list instance is null (日本語: リストがnullの場合、新しい空のインスタンスを生成する) |
| 2 | SET (nested) | `cust_kei_hktgi_list_list = new X33VDataTypeList(1)` // Initialize with max element count of 1 (日本語: リストがnullの場合、新しい空のインスタンスを生成する) |
| 3 | FOR (nested) | `for (int i=0; i<1; i++)` // Pre-populate with one initial entry (repeat item with fixed element count of 1) (日本語: 繰り返し項目の固定要素数指定への処理) |
| 4 | SET (nested for) | `KKW01037SF02DBean tmpBean = new KKW01037SF02DBean()` // Create data-type view bean instance (日本語: データタイプビュー型の指定したデータタイプビューのインスタンスを生成する) |
| 5 | EXEC (nested for) | `cust_kei_hktgi_list_list.add(tmpBean)` // Add to the list |
| 6 | IF (nested) | `if (cust_kei_hktgi_list_list.getMaxElementCnt() == 0 || cust_kei_hktgi_list_list.size() < cust_kei_hktgi_list_list.getMaxElementCnt())` // Check if adding is allowed (日本語: MAX要素数以上の追加は許さない処理) |
| 7 | SET (nested if) | `KKW01037SF02DBean tmpBean = new KKW01037SF02DBean()` // Create new data-type view bean instance (日本語: データタイプビュー型の指定したデータタイプビューのインスタンスを生成する) |
| 8 | EXEC (nested if) | `cust_kei_hktgi_list_list.add(tmpBean)` // Add the bean to the list |
| 9 | RETURN (nested if) | `return cust_kei_hktgi_list_list.size() - 1` // Return 0-based index of the added element |
| 10 | ELSE (nested if) | (see Block 4.1) |

**Block 4.1** — [nested ELSE] `(maxElementCount exceeded)` (L773)

> Exception guard: if the customer contract handover list has reached its maximum element count, throw an X31CException to prevent adding more entries.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `throw super.createExceptionForX31Method(ERRS_CANNOT_ADD_REPEATITEM)` // Throw exception for repeated item addition limit (日本語: 異常通知) |

**Block 5** — [DEFAULT / FALLTHROUGH] `(key not matching any recognized value)` (L781)

> Unrecognized key: if the key does not match any of the three handled categories (null, common info, service contract list, customer contract handover list), return -1 to indicate the item type is not recognized.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `サービス契約一覧リスト` | Japanese field | Service Contract List — the screen's data-type view for displaying a list of service contract line items |
| `顧客契約引継リスト` | Japanese field | Customer Contract Handover List — the screen's data-type view for customer contract handover entries (e.g., when a customer's contract is transferred or taken over) |
| `X33VDataTypeList` | Class | X33V framework data-type list — a generic typed list container that holds view bean instances in the X33V web framework |
| `X33VDataTypeBeanInterface` | Interface | X33V data-type bean interface — the contract that all view bean types must implement to be stored in a `X33VDataTypeList` |
| `KKW01037SF01DBean` | Class | Data-type view bean for service contract list entries — represents a single service contract line item row on the screen |
| `KKW01037SF02DBean` | Class | Data-type view bean for customer contract handover list entries — represents a single customer contract handover row on the screen |
| `X33VViewBaseBean` | Class | Base class for X33V view beans — provides common view-layer functionality including `addListDataInstance` for list item creation |
| `X31CBaseBean` | Interface | X31C base bean interface — Fujitsu's X31C framework contract for view beans |
| `ERRS_CANNOT_ADD_REPEATITEM` | Constant | Error constant — error code thrown when attempting to add a repeated list item that exceeds the maximum allowed element count |
| `X31CException` | Class | X31C framework exception — the exception type thrown by `createExceptionForX31Method` when a business rule violation occurs |
| `X33SException` | Class | X33S framework exception — imported exception type (used indirectly via the superclass) |
| `X33V` | Framework | X33View — Fujitsu's web application framework for building rich client/server UI components |
| `X31C` | Framework | X31Component — Fujitsu's component framework that provides the base bean infrastructure |
| `data-type view` | Technical term | A view bean type whose data is wrapped in a typed data container (X33VDataTypeList) for structured display on the screen |
| `repeat item` | Technical term | A list-type screen item that can contain multiple rows, each represented by a data-type view bean instance |
| `max element count` | Technical term | The maximum number of rows allowed in a repeat item list — when this limit is reached, no more items can be added |
| `key` | Parameter | A string discriminator that determines which list category and bean type to instantiate |