# KKW01037SF01DBean

## Purpose

`KKW01037SF01DBean` is the **data model bean** for a customer referral screen (screen ID `KKW01037SF01`) in the K-Opticom web application. It holds form state for customer referral information, managing both "referred customer" (被紹介者, `hi`-prefixed) and "referring customer" (紹介者, `sho`-prefixed) data. The class is used as a JSF/Struts-style request-scoped data holder that bridges the JSP view layer and the business logic layer.

## Design

This class follows the **Data Transfer Object (DTO) / Model-View binding bean** pattern within the Fujitsu Futurity X33/X31 web framework. It implements two key framework interfaces:

- **`X33VDataTypeBeanInterface`** — Provides dynamic data loading and typing. The framework uses `loadModelData()`, `storeModelData()`, and `typeModelData()` to perform **reflection-style property access** by string key, enabling the view layer to read/write fields without compile-time coupling to the bean.
- **`X33VListedBeanInterface`** — Indicates the bean participates in the framework's listed/iterable data model (likely for row-based table rendering).
- **`Serializable`** — Allows the bean to be passed across layers and persisted in session state.

The class is generated by the **Web Client tool** (v2.0.39), a code generator that produces boilerplate bean classes from screen definitions. A later enhancement (issue ANK-4416-00-00, dated 2023-10-06) added support for simultaneous entry of "intro code" and "partner enterprise entry code".

Each of the 11 domain fields has a **4-field bundle**:

| Suffix | Purpose | Type | Default |
|--------|---------|------|---------|
| `_value` | The actual user-entered or displayed value | `String` | `""` |
| `_enabled` | Whether the field is enabled (editable) in the UI | `Boolean` | `true` |
| `_state` | UI validation state (e.g., error, success messages) | `String` | `""` |
| `_update` | Change-tracking flag set by the framework or business logic | `String` | `null` |

This pattern allows the framework to manage field-level enable/disable, display error messages in `_state`, and track which fields were modified by the user via `_update`.

## Fields

The bean defines 11 logical fields (44 physical properties total), grouped into three categories:

### Referred Customer (被紹介者) — `hi_` prefix

| Field ID | Display Name (key) | Purpose |
|----------|-------------------|---------|
| `hi_svc_kei_no` | 被紹介者お客さまYD | Referred customer service key number |
| `hi_prc_grp_nm` | 被紹介者料金グループ名 | Referred customer price group name |
| `hi_svc_kei_stat` | 被紹介者ステータス | Referred customer service status |
| `hi_svc_sta_ymd` | 被紹介者サービス開始年月日 | Referred customer service start date |

### Intro / Partner Codes — no prefix

| Field ID | Display Name (key) | Purpose |
|----------|-------------------|---------|
| `intr_cd` | 紹介コード | Intro / referral code |
| `coupon_cd` | クーポンコード | Coupon code (added in ANK-4416-00-00) |

### Referring Customer (紹介者) — `sho_` prefix

| Field ID | Display Name (key) | Purpose |
|----------|-------------------|---------|
| `sho_svc_kei_no` | 紹介者お客さまYD | Referring customer service key number |
| `sho_prc_grp_nm` | 紹介者料金グループ名 | Referring customer price group name |
| `sho_sysid` | 紹介者SYSID | Referring customer system ID |
| `sho_cust_nm` | 紹介者契約者名 | Referring customer contract party name |

### Additional

| Field | Type | Purpose |
|-------|------|---------|
| `index` | `int` | Row index for use in table/list rendering |

## Key Methods

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

This is the primary **data retrieval method** from the framework. It accepts a human-readable field name (the `key`) and a sub-key (`"value"`, `"enable"`, or `"state"`) and returns the corresponding property value.

```java
Object val = bean.loadModelData("紹介者お客さまYD", "value");   // returns sho_svc_kei_no_value
Boolean enabled = bean.loadModelData("紹介者お客さまYD", "enable"); // returns sho_svc_kei_no_enabled
String state = bean.loadModelData("紹介者お客さまYD", "state");   // returns sho_svc_kei_no_state
```

The `key` parameter must match one of the 11 display names exactly (e.g., `"被紹介者お客さまYD"`, `"紹介コード"`). The `subkey` is case-insensitive and supports `"value"`, `"enable"`, and `"state"`. If either parameter is `null` or the key doesn't match any field, the method returns `null`.

This method is the read-side of the framework's dynamic property accessor protocol. It eliminates the need for the JSP to know specific field names at compile time.

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

Overloaded entry point. The three-argument version delegates to the four-argument form with `isSetAsString = false`:

```java
bean.storeModelData("紹介コード", "value", "ABC123");
bean.storeModelData("紹介コード", "enable", true);
```

### `storeModelData(String gamenId, String key, String subkey, Object in_value) → void`

Four-argument version that accepts a `gamenId` (screen ID, currently unused/reserved). It simply delegates to the three-argument form, so the `gamenId` parameter has no effect.

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

The **core setter implementation**. Like `loadModelData`, it dispatches to the correct field based on the `key`/`subkey` pair and casts `in_value` to the appropriate type (`String` for value/state, `Boolean` for enable).

The `isSetAsString` parameter is documented but currently unused in this class — the body always casts to the concrete type directly rather than using the string conversion path. This is an inherited hook from `X31CBaseBean` that may be used by subclasses.

Key behavior:
- If `key` or `subkey` is `null`, the method returns early without setting anything.
- The same 11 field names and 3 sub-keys (`"value"`, `"enable"`, `"state"`) are supported.
- No value is set if the key doesn't match any known field — there is no fallback or exception.

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

A **static factory method** that returns a list of all 11 field display names in a fixed order. This is used by the framework to enumerate which fields should be processed during data binding:

```java
["被紹介者お客さまYD",
 "被紹介者料金グループ名",
 "被紹介者ステータス",
 "被紹介者サービス開始年月日",
 "紹介コード",
 "クーポンコード",
 "紹介者お客さまYD",
 "紹介者料金グループ名",
 "紹介者SYSID",
 "紹介者契約者名"]
```

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

Returns the expected Java type for a given key/subkey pair. Used by the framework for validation and type-safe binding:

| subkey | Returned type |
|--------|--------------|
| `"value"` | `String.class` |
| `"enable"` | `Boolean.class` |
| `"state"` | `String.class` |

Returns `null` for unknown keys or subkeys.

### Getter/Setter pairs

Each of the 44 fields has a standard JavaBean getter and setter. For example:

```java
public String getHi_svc_kei_no_value() { return this.hi_svc_kei_no_value; }
public void setHi_svc_kei_no_value(String param) { this.hi_svc_kei_no_value = param; }

public Boolean getHi_svc_kei_no_enabled() { return this.hi_svc_kei_no_enabled; }
public void setHi_svc_kei_no_enabled(Boolean param) { this.hi_svc_kei_no_enabled = param; }
```

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

Simple accessor for a row index field used when rendering the bean in a tabular context.

## Relationships

```mermaid
flowchart LR
    JSP["KKW010370PJP
JSP Page"]
    BEAN["KKW01037SF01DBean
Data Bean"]
    JSP -->|reads/writes properties| BEAN

    subgraph hiSection["Referred Customer Fields (被紹介者)"]
        F1["hi_svc_kei_no
Service Key No"]
        F2["hi_prc_grp_nm
Price Group Name"]
        F3["hi_svc_kei_stat
Service Status"]
        F4["hi_svc_sta_ymd
Service Start Date"]
    end

    subgraph shoSection["Referring Customer Fields (紹介者)"]
        F6["sho_svc_kei_no
Service Key No"]
        F7["sho_prc_grp_nm
Price Group Name"]
        F8["sho_sysid
System ID"]
        F9["sho_cust_nm
Contractor Name"]
    end

    INTR["intr_cd
Intro Code"]
    CPN["coupon_cd
Coupon Code"]

    BEAN --> hiSection
    BEAN --> INTR
    BEAN --> shoSection
    INTR --> CPN
```

### Upstream dependents

| Class | Usage |
|-------|-------|
| `KKW010370PJP.jsp` | The JSP page that renders the referral screen. Creates an instance of this bean, reads/writes its properties via EL (Expression Language), and displays field values in the form. |

### Framework dependencies

The bean depends on several classes from the Fujitsu Futurity X33/X31 framework:

- `X33VViewBaseBean` — Base class (implicitly extended via the generated class hierarchy, providing common view bean behavior)
- `X33VDataTypeBeanInterface` — Interface requiring `loadModelData()`, `storeModelData()`, and `typeModelData()` implementations
- `X33VListedBeanInterface` — Interface for list/iteration support
- `X31CBaseBean` — Base bean from the X31 framework providing `storeModelData()` default implementations
- `X33VDataTypeList`, `X33VDataTypeStringBean`, `X33VDataTypeBooleanBean`, `X33VDataTypeLongBean` — Framework data type wrappers
- `X33SException` — Exception class imported for exception handling paths
- `SelectItem` — JSF component class (imported, likely used by the JSP for dropdowns)

## Usage Example

The bean is typically instantiated in a JSP page via a `<jsp:useBean>` or Spring-managed scope, then bound to form fields:

**In the JSP (reading):**
```jsp
<!-- Read field values via EL -->
<c:out value="${bean.hi_svc_kei_no_value}" />
<input type="text" value="${bean.intr_cd_value}"
       disabled="${!bean.intr_cd_enabled}" />
<span class="error">${bean.sho_cust_nm_state}</span>
```

**In the JSP (listing all fields):**
```jsp
<%
ArrayList<String> fieldNames = KKW01037SF01DBean.listKoumokuIds();
for (String fieldName : fieldNames) {
    Object value = bean.loadModelData(fieldName, "value");
    // ... render each field
}
%>
```

**In the JSP (setting values programmatically):**
```java
// Store data by field name and property key
bean.storeModelData("紹介者契約者名", "value", "Example Corp");
bean.storeModelData("紹介者契約者名", "enable", false);
bean.storeModelData("紹介者契約者名", "state", "Validation error message");

// Store the intro code
bean.storeModelData("紹介コード", "value", "REF-2024-001");
bean.storeModelData("紹介コード", "enable", true);
```

**Typical request flow:**
1. The framework instantiates `KKW01037SF01DBean` in request or session scope.
2. The JSP renders the form, populating fields from bean properties via EL.
3. The user submits the form; the framework calls `storeModelData()` on each field to populate the bean from request parameters.
4. Business logic reads the bean's `_value` fields to process the referral data.
5. The `_state` fields are populated with validation/error messages for display on the next page render.
6. The `_update` fields indicate which fields were changed, allowing selective processing.

## Notes for Developers

### Framework-generated code
This class is generated by the **Web Client tool** (v2.0.39). Do not hand-edit the class directly — edits will be overwritten on regeneration. New fields should be added through the tool's screen definition, not by modifying the Java file. The ANK-4416-00-00 coupon code field was added via an enhancement patch.

### Thread safety
The bean holds mutable instance state and is **not thread-safe**. It should be used in request scope (one instance per HTTP request) rather than as a shared singleton. The framework's scope management should enforce this.

### Naming convention
- `hi_` prefix = **referred customer** (the customer being introduced/referred)
- `sho_` prefix = **referring customer** (the customer making the introduction)
- These are short Japanese abbreviations: 被 (hi = receiving) and 紹 (sho = introducing/introducing)

### Key patterns
- **Four-field bundles** (`_value`, `_enabled`, `_state`, `_update`) are the fundamental unit. Always set all four when changing a field's UI state.
- The dynamic accessor methods (`loadModelData`, `storeModelData`, `typeModelData`) use **exact Japanese string matching** for the `key` parameter. Typos in the display name will silently return `null` instead of throwing an exception.
- The `separaterPoint` local variable (typo of "separator") is assigned but never used in any method — it is likely vestigial from an earlier version that supported hierarchical keys with `/` delimiters.
- The `gamenId` parameter in `storeModelData` is defined but never used in the method body. It was likely intended for screen-specific dispatch logic that was never implemented.
- `isSetAsString` in the four-argument `storeModelData` is accepted but the current implementation ignores it and always casts directly. Subclasses or future versions may use it.

### Data types
All `_value` and `_state` fields are `String`. The `_enabled` fields use `Boolean` (the wrapper type, not the primitive), meaning they can be `null`. However, the constructor defaults all enabled fields to `true`, so `null` should not occur in practice.

### Adding a new field
To add a new field to this bean (via the Web Client tool), you would:
1. Add a new field entry in the screen definition with its display name.
2. The tool generates: `_value`, `_enabled`, `_state`, `_update` fields and their getters/setters.
3. The new field's display name is added to `loadModelData`, `storeModelData`, and `typeModelData` dispatch blocks.
4. The display name is appended to `listKoumokuIds()`.

### Historical revisions
| No. | Date | Description |
|-----|------|-------------|
| 01 | 2014-02-01 | Initial generation by Web Client tool 2.0.39 |
| 02 | 2023-10-06 | Added coupon code field (issue ANK-4416-00-00) for simultaneous entry of intro code and partner enterprise entry code |