# KKW01033SF01DBean

## Purpose

`KKW01033SF01DBean` is a screen data bean for the **error/anomaly handling screen** (task code `KKW01033`) in the application's X33V web framework. It serves as the in-memory model that bridges HTTP request parameters from the UI to business logic, carrying field values, UI state flags, and a reason-code list. It exists to satisfy the framework's convention that every screen page has a corresponding `*DBean` that encapsulates all page-level data.

## Design

The class follows the **Active Record–style data bean** pattern used by the X33V framework (commonly seen in Japanese enterprise Java web applications built on JSF or a similar MVC tier). It is a plain Java object with `protected` fields, public getter/setter pairs, and three framework callback methods (`loadModelData`, `storeModelData`, `typeModelData`) plus list-management helpers.

Three interfaces drive its design:

- **`X33VDataTypeBeanInterface`** — requires `loadModelData(String key, String subkey)`, `storeModelData(...)`, and `typeModelData(...)`. These methods let the framework resolve, read, and write field values by **string-based keys** at runtime, without compile-time type knowledge.
- **`X33VListedBeanInterface`** — requires `addListDataInstance`, `removeElementFromListData`, and `clearListDataInstance`. These manage the one multi-valued property on the screen: the reason-code list.
- **`Serializable`** — enables the bean to be stored in the HTTP session across requests.

### The triple-field pattern

Every scalar property on the screen follows a consistent three-field grouping:

| Field | Role |
|---|---|
| `*_update` | Flag indicating whether this field was submitted (updated) in the current request. Often `null` for new pages and a non-empty string after a POST. |
| `*_value` | The actual user-entered or server-populated value. Default-initialised to `""`. |
| `*_state` | UI state string (e.g. enabled/disabled, or CSS class) used by the view layer to render the field. Default-initialised to `""`. |

This pattern lets the framework drive validation, conditional display, and post-back diffing without requiring additional annotations.

## Fields

| Field | Type | Default | Notes |
|---|---|---|---|
| `sysid_update`, `sysid_value`, `sysid_state` | `String` | `value`/`state` = `""` | System ID |
| `svc_kei_no_update`, `svc_kei_no_value`, `svc_kei_no_state` | `String` | `value`/`state` = `""` | Service contract number |
| `svc_kei_ucwk_no_update`, `svc_kei_ucwk_no_value`, `svc_kei_ucwk_no_state` | `String` | `value`/`state` = `""` | Service contract internal number |
| `ido_div_update`, `ido_div_value`, `ido_div_state` | `String` | `value`/`state` = `""` | Difference division |
| `ido_rsn_cd_list` | `X33VDataTypeList` | `new X33VDataTypeList()` | **Multi-valued** — reason-code list. Initialized in the constructor. |
| `mskm_no_update`, `mskm_no_value`, `mskm_no_state` | `String` | `value`/`state` = `""` | Application number |
| `mskm_dtl_no_update`, `mskm_dtl_no_value`, `mskm_dtl_no_state` | `String` | `value`/`state` = `""` | Application detail number |
| `popup_mode_update`, `popup_mode_value`, `popup_mode_state` | `String` | `value`/`state` = `""` | Popup mode |
| `ido_div_seni_ptn_update`, `ido_div_seni_ptn_value`, `ido_div_seni_ptn_state` | `String` | `value`/`state` = `""` | Difference division selection screen transfer pattern |
| `syscd_update`, `syscd_value`, `syscd_state` | `String` | `value`/`state` = `""` | External system code (added in ANK-2693-00-00 STEP2) |
| `index` | `int` | `0` | Row index, typically used for table-style displays |

## Key Methods

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

Reads a field value (or list size) by string key and sub-key. This is the framework's **GET** bridge.

- **`key`** — the Japanese property name (e.g. `"システムID"`, `"サービス契約番号"`, `"差異区分"`). For list properties, the key is in the form `"差異理由コード/0"` where the part after `/` is the list index.
- **`subkey`** — either `"value"` or `"state"`, or `"*"` when querying the reason-code list size.
- **Return** — the current field value (as `String`), or the list size as `Integer` if `subkey` is `"*"`. Returns `null` if the key does not match any known property.
- **Side effects** — none.

For the reason-code list (`"差異理由コード"`), this method extracts the index from the key, validates it, and delegates to the `X33VDataTypeStringBean` at that list position by calling its own `loadModelData(subkey)`. This recursive delegation supports nested property access inside list elements.

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

Writes a field value by string key. The three-argument version delegates to the four-argument version with `isSetAsString = false`. The four-argument version is the framework's **POST** bridge.

- **`key`** — same Japanese property names as `loadModelData`.
- **`subkey`** — `"value"` or `"state"`.
- **`in_value`** — the `Object` to set (cast to `String`).
- **`isSetAsString`** — unused in this class's implementation; present for the interface contract.
- **Side effects** — mutates the corresponding `*_value` or `*_state` field.

The reason-code list case is particularly important: when `key` is `"差異理由コード"`, the method extracts the index from the key string, then calls `storeModelData(subkey, in_value)` on the `X33VDataTypeStringBean` at that index, passing through the `isSetAsString` flag. This allows nested type-aware storage for list elements.

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

Returns the Java type for a given property, enabling the framework to perform type-safe conversions.

- All scalar properties return `String.class` for both `"value"` and `"state"` subkeys.
- For the reason-code list, if `subkey` is `"*"`, returns `Integer.class` (list size). If the index is valid, delegates to the element's `typeModelData(subkey)`. Otherwise returns `null`.

This method is essential for the framework's type conversion pipeline, which uses reflection to coerce incoming `String` request parameters into the correct Java types before calling `storeModelData`.

### `ArrayList<String> listKoumokuIds()`

A **static** method that returns the complete list of property names recognised by this bean. This is the source of truth for what fields exist on the screen and is likely used by the framework for:

- Generating hidden form fields or metadata.
- Validating that incoming request parameters reference known properties.
- Building UI form elements dynamically.

The returned list contains 10 Japanese names, one per field group.

### `int addListDataInstance(String key)` / `void removeElementFromListData(String key, int index)` / `void clearListDataInstance(String key)`

These three methods implement the `X33VListedBeanInterface` contract for the reason-code list:

- **`addListDataInstance`** — Creates a new `X33VDataTypeStringBean`, appends it to `ido_rsn_cd_list`, and returns the new index. If the key is not `"差異理由コード"`, returns `-1`. If the list is `null`, creates a new one first.
- **`removeElementFromListData`** — Removes the element at the given index from the list, if the index is in bounds.
- **`clearListDataInstance`** — Clears all elements from the list.

### `ArrayList<SelectItem> getJsflist_ido_rsn_cd()`

A JSF-specific convenience method that converts the internal `X33VDataTypeList` into an `ArrayList<SelectItem>` suitable for rendering a `<h:selectOneMenu>` or similar dropdown. Each list element is cast to `X33VDataTypeStringBean`, its `getValue()` is extracted, and a `SelectItem` is created with the list index as the value and the string value as the label.

### `void setIndex(int index)` / `int getIndex()`

Simple accessor for the row index, used when the bean represents a row in a repeated table.

## Relationships

```mermaid
flowchart TD
    subgraph Interfaces
        I1["X33VDataTypeBeanInterface"]
        I2["X33VListedBeanInterface"]
    end

    subgraph Dependencies
        D1["X33VDataTypeList"]
        D2["X33VDataTypeStringBean"]
        D3["SelectItem"]
        D4["ArrayList"]
    end

    KKW["KKW01033SF01DBean"] --> I1
    KKW --> I2
    KKW --> D1
    KKW --> D2
    KKW --> D4

    D1 --> D2
    KKW --> D3
```

### Who uses this class

- **`KKW010330PJP.jsp`** — the JSP view that renders the error/anomaly screen. The JSP binds to the bean's properties via JSF EL or the X33V framework's tag library.

### Who this class depends on

The bean has no outbound references to business logic or data access layers. Its only dependencies are:

- `X33VDataTypeList`, `X33VDataTypeStringBean` — framework collection and typed-element classes.
- `SelectItem` — JSF utility class for dropdown options.
- The three interfaces it implements.

## Usage Example

A typical request lifecycle involving this bean:

1. **Page load** — The framework instantiates `KKW01033SF01DBean`, populates `*_value` fields from the database via the logic layer, and dispatches to `KKW010330PJP.jsp`.

2. **Render** — The JSP uses JSF tags like `<h:inputText value="#{bean.sysid_value}" disabled="#{bean.sysid_state == 'disabled'}"/>` to bind fields. The `getJsflist_ido_rsn_cd()` method feeds a dropdown with reason codes.

3. **Submit** — On POST, the framework calls `storeModelData(key, subkey, requestValue)` for every form field, passing user input back into the bean's fields.

4. **Validation** — The `*_update` fields are checked to determine which fields were actually submitted. The `typeModelData()` method ensures type conversion happens before values are stored.

5. **Logic invocation** — The JSP or a backing controller passes the bean to a logic class (e.g. `KKW01033SFLogic`) that reads field values and performs business operations.

## Notes for Developers

- **Thread safety** — This is a per-request object (instantiated per HTTP request by the framework). It is **not thread-safe** and should never be shared across threads.
- **Field naming convention** — The `*_update`, `*_value`, `*_state` triple is a framework convention. Always access values through the generated getters/setters rather than directly referencing fields, to maintain compatibility with the reflection-based `loadModelData`/`storeModelData` methods.
- **List handling** — The `ido_rsn_cd_list` is the only multi-valued property. It contains `X33VDataTypeStringBean` instances. All list operations (`add`, `remove`, `clear`) are keyed by the literal Japanese property name `"差異理由コード"`. The index in `loadModelData`/`storeModelData` is embedded in the key string after a `/` separator.
- **Null handling** — `loadModelData` returns `null` when the key does not match or the index is out of bounds. `storeModelData` silently returns when `key` or `subkey` is `null`. Callers must not assume the returned value is non-null.
- **The `index` field** — Used to track the row position when the bean appears in a repeated table context. It is independent of list element indices.
- **Constructor initialization** — The constructor creates a new `X33VDataTypeList()` for `ido_rsn_cd_list`. Be careful not to set it to `null` via the setter, as this will cause `NullPointerException` in `getJsflist_ido_rsn_cd()`, `addListDataInstance`, and the `loadModelData`/`storeModelData` list branches.
- **Serialization** — The class implements `Serializable`, allowing it to be stored in the HTTP session. The `X33VDataTypeList` and its elements must also be serializable for this to work correctly.
- **`storeModelData(gamenId, ...)`** — The version that takes `gamenId` (screen ID) is currently implemented as a pass-through to the three-argument version. The `gamenId` parameter is reserved for future use and is ignored today.
- **`isSetAsString` parameter** — In this bean's implementation, the `isSetAsString` flag is accepted by the four-argument `storeModelData` but not explicitly used. It is forwarded to nested `X33VDataTypeStringBean.storeModelData()` calls for list elements, where it may affect type conversion logic.