# KKW02516SFBean

## Purpose

`KKW02516SFBean` is the primary **JSP Form Bean** (data transfer object) for the `KKA168010PJP` screen within the K-Opticom web application. It serves as the central data container bridging the presentation layer (JSP) and business logic, holding all form input values, view-state metadata (enabled/disabled, read-only), and two repeat-designated item lists (customer contract continuation and discontinuation reasons) for a service contract management page.

## Design

This class is a **Form Bean** following the JavaServer Pages (JSP) model-view-controller (MVC) pattern. It inherits from Fujitsu's Futurity X33 framework's `X33VViewBaseBean` and implements `X33VListedBeanInterface` (for list-based repeat items) and `X31CBaseBean` (for common bean functionality). The bean is serializable for session persistence.

The architectural role is that of a **data-oriented DTO** — it does not contain business logic but rather serves as a stateful holder of screen data. The X33 framework uses reflection-free, display-name-based dispatch: instead of using internal Java field names (e.g., `use_staymd_value`), the framework and JSP refer to fields by their **Japanese display names** (e.g., `利用開始日`, `利用終了日`) as keys in the `loadModelData`, `storeModelData`, and `typeModelData` methods. This is a hallmark of code generated by the Web Client tool.

The bean manages two categories of fields:

1. **Single-value fields (~30+):** Standard getter/setter pairs, each optionally augmented with `_enabled` (Boolean), `_state` (String), and `_update` (String) properties. The `_enabled` flag controls whether the field is interactive on the screen, `_state` typically holds error/validation status, and `_update` signals whether the value has been modified.

2. **Repeat-designated (list) fields (2):** `cust_kei_hktgi_list_list` (Customer Contract Continuation List) and `ido_rsn_list_list` (Discontinuation Reason List). These are `X33VDataTypeList` containers whose elements are themselves beans (`KKW02516SF01DBean` and `KKW02516SF02DBean` respectively), enabling dynamic row-level data binding.

### Data Categories

| Category | Display Name (key) | Internal IDs | Type |
|---|---|---|---|
| User period start date | 利用開始日 | use_staymd | String + enabled |
| User period end date | 利用終了日 | use_endymd | String + enabled |
| User period end date (year) | 利用終了日（年） | use_endymd_year | String + enabled |
| User period end date (month) | 利用終了日（月） | use_endymd_mon | String + enabled |
| User period end date (day) | 利用終了日（日） | use_endymd_day | String + enabled |
| System ID | SYSID | sysid | String |
| Service contract number | サーチビス契約番号 | svc_kei_no | String |
| Discontinuation division | 異動区分 | ido_div | String |
| Operation service contract number | オプショサービス契約番号 | op_svc_kei_no | String |
| Process division | 処理区分 | tran_div | String |
| Application number | 申込番号 | mskm_no | String |
| Application detail number | 申込明細番号 | mskm_dtl_no | String |
| Operation YMD | 運用年月日 | unyo_ymd | String |
| Operation date-time | 運用年月日時分秒 | unyo_dtm | String |
| Reservation application date | 予約適用年月日 | rsv_aply_ymd | String |
| Generation registration date-time | 世代登録年月日時分秒 | gene_add_dtm | String |
| Operation service contract status | オプショサービス契約ステータス | op_svc_kei_stat | String |
| Operation service code | オプショサービスコード | op_svc_cd | String |
| Charge code | 料金コースコード | pcrs_cd | String |
| Plan code | 料金プランコード | pplan_cd | String |
| Service start date | サービス開始年月日 | svc_staymd | String |
| Service end date | サービス終了年月日 | svc_endymd | String |
| Service charge end date | サービス課金終了年月日 | svc_chrg_endymd | String |
| Recovery date | 回復年月日 | kaihk_ymd | String |
| Last update date-time | 最終更新年月日時分秒 | last_upd_dtm | String |
| Return message ID | 返却メッセージID | rtn_msg_id | String |
| Update status flag | 更新状態可否フラグ | chg_kahi_flg | Boolean |
| Progress special item 1 | 進展特記事項1 | prg_tkjk_1 | String + enabled |
| Return data | 返戻データ | returnData | String + enabled |
| Customer contract continuation list | 顧客契約引継リスト | cust_kei_hktgi_list_list | X33VDataTypeList |
| Discontinuation reason list | 異動理由リスト | ido_rsn_list_list | X33VDataTypeList |

## Key Methods

### loadModelData(String key, String subkey) → Object

The central method for **reading field values** from this bean. It is the workhorse that the X33 framework calls whenever the JSP needs to populate a form field from the bean.

The dispatch logic uses the **`key` parameter** which is the Japanese display name of the field (e.g., `利用開始日`), and the **`subkey` parameter** which is one of `value`, `enable`, or `state`:

- **`subkey == "value"`**: Returns the field's current value (String or Boolean) via the corresponding getter.
- **`subkey == "enable"`**: Returns the field's enabled state (Boolean) via the `_enabled` getter.
- **`subkey == "state"`**: Returns the field's state/message (String) via the `_state` getter.

For **repeat-designated (list) fields**, the key format uses `/` as a separator:
- `顧客契約引継リスト/0/plan_name` — accesses `plan_name` in the first element of the customer contract list.
- `顧客契約引継リスト/*` — returns the list size as an Integer.

For **common info beans** (identified by keys starting with `//`), the method delegates to the parent class's `loadCommonInfoData`.

**Example dispatch paths:**

```
key="利用開始日", subkey="value"  → getUse_staymd_value()
key="利用開始日", subkey="enable" → getUse_staymd_enabled()
key="利用開始日", subkey="state"  → getUse_staymd_state()
key="顧客契約引継リスト/0/name", subkey="value" → bean at index 0, loadModelData("name", subkey)
key="顧客契約引継リスト/*", subkey="*" → cust_kei_hktgi_list_list.size()
```

If the key is `null`, the method returns `null`. If the key refers to an unknown field, it falls through the entire else-if chain and returns `null`.

### storeModelData(String key, String subkey, Object in_value, boolean isSetAsString) → void

The counterpart to `loadModelData`, used for **writing user input back** into the bean. The framework calls this when form data is submitted.

The dispatch pattern mirrors `loadModelData` but in reverse:

- **`subkey == "value"`**: Casts `in_value` and calls the appropriate setter (e.g., `setUse_staymd_value((String)in_value)`).
- **`subkey == "enable"`**: Casts `in_value` to Boolean and calls the `_enabled` setter.
- **`subkey == "state"`**: Casts `in_value` to String and calls the `_state` setter.

The `isSetAsString` flag (default `false`) is documented as a way to force String-type setting for Long-type fields, though in practice all fields in this bean are String or Boolean.

For list fields, the method navigates the index path and delegates `storeModelData` to the individual element bean:
```java
((X33VDataTypeBeanInterface)cust_kei_hktgi_list_list.get(tmpIndex))
    .storeModelData(keyElement, subkey, in_value, isSetAsString);
```

### typeModelData(String key, String subkey) → Class<?>

Returns the **Java type** of a field, used by the X33 framework for type-safe data binding. The same display-name-based dispatch is used:

- For fields with `subkey == "value"`: Returns `String.class` (for most fields) or `Boolean.class` (for `chg_kahi_flg` and enabled date fields).
- For fields with `subkey == "enable"`: Returns `Boolean.class`.
- For fields with `subkey == "state"`: Returns `String.class`.
- For list fields with key ending in `/*`: Returns `Integer.class` (representing list size).
- For common info beans (key starting with `//`): Delegates to the parent class's `typeCommonInfoData`.

### listKoumokuIds(String key) → ArrayList<String>

Returns the **list of display names** for all fields in the service form, or for a specific key's sub-fields.

When called with `key == null`, it returns all 32 field display names (the complete set of single-value fields plus the two list fields). This is used by the framework to enumerate available form fields.

When called with a specific key like `顧客契約引継リスト`, it delegates to `KKW02516SF01DBean.listKoumokuIds()` to get the sub-field names for that data-type bean. Similarly, `異動理由リスト` delegates to `KKW02516SF02DBean.listKoumokuIds()`.

For common info beans (key starting with `/`), it delegates to the parent class.

### addListDataInstance(String key) → int

Adds a **new row** to a repeat-designated list and returns the index of the newly added element.

For `顧客契約引継リスト`:
- If the list is `null`, it initializes it with capacity 1 and adds one initial element.
- If a max element count is set, it respects that limit and throws `X33SException` if exceeded.
- Creates a new `KKW02516SF01DBean` instance and adds it.

For `異動理由リスト`:
- If the list is `null`, initializes it as an empty `X33VDataTypeList`.
- Creates a new `KKW02516SF02DBean` instance and adds it.

For common info beans (key starting with `//`), delegates to the parent class. Returns `-1` if the key is unrecognized.

### removeElementFromListData(String key, int index) → void

Removes the element at the given index from a repeat-designated list. Includes bounds checking (`index >= 0 && index < list.size()`) to prevent `IndexOutOfBoundsException`. For common info beans, delegates to the parent class.

### clearListDataInstance(String key) → void

Clears all elements from a repeat-designated list. For the two list fields, calls `.clear()` on the respective list. For common info beans, delegates to the parent class.

### getCust_kei_hktgi_list_list() / setCust_kei_hktgi_list_list() → X33VDataTypeList

Direct access to the customer contract continuation list. This list holds `KKW02516SF01DBean` instances, each representing a single row in the customer contract continuation repeat table.

### getJsflist_typelist_cust_kei_hktgi_list() → ArrayList<SelectItem>

Builds a list of `SelectItem` objects (for `<h:selectOneMenu>` dropdown rendering) from the customer contract list data. Each element in the list is converted into a selectable option, likely for dropdown display in the JSP.

### getIdo_rsn_list_list() / setIdo_rsn_list_list() → X33VDataTypeList

Direct access to the discontinuation reason list. This list holds `KKW02516SF02DBean` instances, each representing a single row in the discontinuation reason repeat table.

### getJsflist_typelist_ido_rsn_list() → ArrayList<SelectItem>

Builds a list of `SelectItem` objects from the discontinuation reason list for dropdown rendering.

### Return Data Fields (returnData)

Added under the worktop migration ticket ANK-2694-00-00, the `returnData` field (返戻データ) provides a String-based return data container with `value`, `enabled`, and `state` properties. This appears to support data passing from `koptWebB` back to `koptWebA` during a migration step.

## Relationships

```mermaid
flowchart TD
    subgraph KKA16801SF ["Package: KKA16801SF"]
        JSP["KKA168010PJP.jsp<br/>Presentation Layer"]
        BEAN["KKW02516SFBean<br/>Form Bean / Data Container"]
        XML["WEBGAMEN_KKA168010PJP.xml<br/>Screen Configuration"]
        D1["KKW02516SF01DBean<br/>Customer Contract Bean"]
        D2["KKW02516SF02DBean<br/>Discontinuation Reason Bean"]
    end

    JSP -->|Instantiates and populates| BEAN
    XML -->|Declares fields and lists| BEAN
    BEAN -->|contains List of| D1
    BEAN -->|contains List of| D2
    BEAN -->|delegates load/store to| D1
    BEAN -->|delegates load/store to| D2
```

### Who depends on this class (2 inbound connections)

1. **KKA168010PJP.jsp** — The JSP page that renders the screen. It instantiates this bean (typically as a JSF managed property), binds form inputs to its fields, and submits user data back.

2. **WEBGAMEN_KKA168010PJP.xml** — The screen configuration XML that declares the bean as the form bean for this screen, maps display names to field names, and defines the structure of repeat-designated items.

### What this class depends on (outbound dependencies)

- `X33VViewBaseBean` — Base bean providing common view-layer functionality and `loadCommonInfoData`/`storeCommonInfoData` for shared info beans.
- `X33VListedBeanInterface` — Interface requiring list management methods (`addListDataInstance`, `removeElementFromListData`, `clearListDataInstance`).
- `X31CBaseBean` — Base interface for common bean functionality.
- `X33VDataTypeList`, `X33VDataTypeBeanInterface` — Framework types for list-based repeat items.
- `KKW02516SF01DBean` — Inner bean type for customer contract continuation list elements.
- `KKW02516SF02DBean` — Inner bean type for discontinuation reason list elements.
- `SelectItem` (JSF) — For dropdown option rendering.
- `X33SException` — Framework exception type for list operations.

## Usage Example

A typical usage flow within the X33 framework:

```java
// 1. JSP page or controller creates the bean
KKW02516SFBean bean = new KKW02516SFBean();

// 2. Load initial data from database / business layer
bean.setUse_staymd_value("20240101");
bean.setUse_staymd_enabled(true);
bean.setSvc_kei_no_value("SVC-12345");
bean.setChg_kahi_flg_value(false); // read-only mode

// 3. Add rows to repeat list
int idx1 = bean.addListDataInstance("顧客契約引継リスト");
// The returned index is 0

// 4. Set values in list elements via the dispatch mechanism
// This goes through storeModelData with a compound key
bean.storeModelData("顧客契約引継リスト/0/plan_name", "value", "Basic Plan");
bean.storeModelData("顧客契約引継リスト/0/customer_name", "value", "Acme Corp");

// 5. Add another row
int idx2 = bean.addListDataInstance("顧客契約引継リスト");
bean.storeModelData("顧客契約引継リスト/1/plan_name", "value", "Premium Plan");

// 6. Add discontinuation reasons
bean.addListDataInstance("異動理由リスト");
bean.storeModelData("異動理由リスト/0/reason", "value", "Contract expiration");

// 7. Get field value via display name (X33 framework pattern)
Object value = bean.loadModelData("利用開始日", "value");
// Returns "20240101"

// 8. Get list size
Integer size = (Integer) bean.loadModelData("顧客契約引継リスト/*", "*");
// Returns 2

// 9. Remove a list element
bean.removeElementFromListData("顧客契約引継リスト", 0);

// 10. Get dropdown options
ArrayList<SelectItem> options = bean.getJsflist_typelist_cust_kei_hktgi_list();
```

## Notes for Developers

### Japanese Display Names as Keys

The entire bean is keyed by **Japanese display names** (e.g., `利用開始日`, `SYSID`, `顧客契約引継リスト`), not by internal Java field names. This is a convention imposed by the Fujitsu Futurity X33 code generation tool. When adding new fields, you must:

1. Declare the Java field with its internal ID (`fieldName_value`, `fieldName_enabled`, `fieldName_state`).
2. Add the Japanese display name string as a key in `loadModelData`, `storeModelData`, `typeModelData`, and `listKoumokuIds`.
3. Ensure the display name strings are **consistent** across all four dispatch locations — a mismatch will silently return `null` with no error.

### Thread Safety

This bean is **not thread-safe**. It is designed to be instantiated once per HTTP request/screen lifecycle and held in the HTTP session. Concurrent access to the same bean instance from multiple threads (e.g., shared sessions) would cause data corruption, especially on the mutable `X33VDataTypeList` fields.

### Repeat-Designated List Initialization

The two list fields (`cust_kei_hktgi_list_list` and `ido_rsn_list_list`) are initialized lazily — they start as `null` and are created on first `addListDataInstance()` call. Accessing them before initialization (e.g., calling `getCust_kei_hktgi_list_list().size()` directly) will throw `NullPointerException`. Always use the framework's dispatch methods (`loadModelData`, `addListDataInstance`) which handle null checks.

### The `_update` Fields

Each field has an associated `_update` String property (e.g., `use_staymd_update`) but no getter/setter pairs are fully exposed in the standard pattern. The `_update` fields appear to be framework-managed markers that indicate whether a field's value has been modified since the last load/store cycle. The getters/setters exist in the base class or are set automatically by the X33 framework.

### Boolean vs String Fields

Most fields are `String` type, but `use_staymd_enabled`, `use_endymd_year_enabled`, `use_endymd_mon_enabled`, `use_endymd_day_enabled`, `chg_kahi_flg_value`, `prg_tkjk_1_enabled`, and `returnData_enabled` are `Boolean` types. The `typeModelData` method correctly distinguishes these — fields with `subkey == "enable"` return `Boolean.class`.

### Validation

This bean performs no validation. It simply holds data. Validation logic (if any) is implemented in the associated page processor (e.g., `KKA168010PJP` processor class), not in the bean itself.

### The Return Data Field

The `returnData` field was added under ticket ANK-2694-00-00 as part of a worktop (wan tsutoppu) migration from `koptWebB` to `koptWebA`. This appears to carry raw response data from a backend service call, allowing downstream processors to inspect the full response without requiring additional method calls.

### Code Generation Artifact

This file is generated by the Web Client tool (noted in the header: `generated by Web Client tool V01/L01`). Manual edits to this file will be lost on regeneration unless the changes are made through the Web Client tool's configuration UI. The legacy entry (2012.10.24) and later modification (2015.09.30) confirm this is a long-maintained codebase artifact.

### Key Gotcha — Silent Null Returns

If a field's display name is misspelled in any of the three dispatch methods (`loadModelData`, `storeModelData`, `typeModelData`), the else-if chain falls through to the final `return null;` with no exception or warning. This makes it easy to introduce subtle bugs when renaming fields. Always cross-reference the display names in all four dispatch methods.