# KKW00801SF01DBean

## Purpose

`KKW00801SF01DBean` is a **data-binding model object** (the "DBean" — Data Bean) for a mail service configuration screen in a Japanese web application. It aggregates all the form fields for a user's mail account settings — including address account/domain, mail aliases, mailbox capacity, virus scanning options, POP credentials, and service start date — into a single, screen-scoped data carrier. Its primary role is to bridge the JSP view layer and the underlying persistence logic via a reflective key/subkey dispatch pattern.

## Design

This class serves as the **central view-model** for the mail setup wizard. It implements three marker/type interfaces:

- `X33VDataTypeBeanInterface` — contracts for reading (`loadModelData`), writing (`storeModelData`), and introspecting (`typeModelData`) typed data fields by key/subkey.
- `X33VListedBeanInterface` — contracts for managing list-based data items (add, remove, clear).
- `Serializable` — allows the bean to be stored in session or transferred across tiers.

The class follows a **field-per-property** pattern: every screen input is backed by one or more Java fields (value, enabled, state, update flag) with standard JavaBean getters and setters. Instead of tightly coupling the view to individual fields, the three `X33V*` interface methods accept string keys (e.g. "メールアドレスアカウント") and subkeys (e.g. "value", "enable", "state"), allowing a generic UI framework to read and write any property without reflection or hard-coded field access.

All state fields are `protected`, meaning subclasses can access them directly, but the public API is exclusively through getters/setters and the three interface methods.

## Fields

The bean manages 12 top-level data categories. Each category (except `mlbox_capa_mb`) exposes four fields:

| Category | Item ID | Purpose | Fields |
|---|---|---|---|
| Mail Address Account | `mlad_account` | Primary email address account | `value`, `enabled`, `state`, `update` |
| Mail Address Domain | `mlad_domain` | Domain part of the email address | `value`, `enabled`, `state`, `update` |
| Mail Alias | `mailalias` | Aliased email addresses | `value`, `enabled`, `state`, `update` |
| Mailbox Capacity | `mlbox_capa_index` | Selected mailbox capacity tier | `value`, `enabled`, `state`, `update` |
| Virus Check | `virus_chk_index` | Virus scanning toggle | `value`, `enabled`, `state`, `update` |
| POP ID | `pop_id` | POP3 authentication ID | `value`, `enabled`, `state`, `update` |
| Start Date Year | `use_staymd_year` | Service start year | `value`, `enabled`, `state`, `update` |
| Start Date Month | `use_staymd_mon` | Service start month | `value`, `enabled`, `state`, `update` |
| Start Date Day | `use_staymd_day` | Service start day | `value`, `enabled`, `state`, `update` |
| Display Mailbox Capacity | `mlbox_capa_value` | Displayed capacity value | `value`, `enabled`, `state`, `update` |
| Display Virus Check | `virus_chk_value` | Displayed virus check setting | `value`, `enabled`, `state`, `update` |
| Register Mail Cap MB | `mlbox_capa_mb` | Registered mailbox capacity in MB | `value`, `state`, `update` (no `enabled`) |

Additionally:

- `mlbox_cap_op_list_list` — `X33VDataTypeList` of `KKW00801SF02DBean` items, representing selectable "Mail POP capacity options."
- `virus_chk_op_list_list` — `X33VDataTypeList` of `KKW00801SF02DBean` items, representing selectable "Virus check options."
- `index` — `int`, a row or sequence index for list positioning.

### Field naming convention

Each primitive property uses a `_<category>_value` for the raw string value, `_<category>_enabled` for a Boolean UI-enable flag, `_<category>_state` for a status/error state string, and `_<category>_update` for an update flag. Value fields default to `""` (empty string); enabled fields default to `false` (except `mlbox_capa_value_enabled` and `virus_chk_value_enabled` which default to `true`).

## Key Methods

### `KKW00801SF01DBean()` — Constructor

Initializes the two `X33VDataTypeList` collections (`mlbox_cap_op_list_list` and `virus_chk_op_list_list`) to empty lists. This is essential because `addListDataInstance` later checks `if (list == null)` and only creates the list if it's absent.

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

This is the **central read dispatch method**. Given a property key (the Japanese human-readable name, such as "メールアドレスアカウント") and a subkey ("value", "enable", or "state"), it returns the corresponding field value.

- For primitive categories, it matches the key against all 12 categories and the subkey against "value", "enable", or "state", returning the appropriate getter result.
- For list categories ("メールPOP容量選択リスト" and "ウィルスチェック選択リスト"), it parses a slash-delimited remainder of the key (e.g. `"リスト/0/propertyName"`) to extract a list index, then recursively delegates to `((X33VDataTypeBeanInterface)item).loadModelData(key, subkey)` on the indexed child bean. If the subkey remainder is `"*"`, it returns the list's element count as an `Integer`.
- Returns `null` for unknown keys, null inputs, or out-of-bounds indices.

**Key format for lists**: The key for a list item follows the pattern `<CategoryName>/<index>/<remainingKey>`. For example, to read the "property" field of the 3rd mail POP capacity option, the key might be `"メールPOP容量選択リスト/2/property"`.

### `storeModelData(...)` — Write dispatch (3 overloads)

- `storeModelData(String gamenId, String key, String subkey, Object in_value)` — A 4-argument overload that delegates to the 3-argument version, ignoring `gamenId` (reserved for future use).
- `storeModelData(String key, String subkey, Object in_value)` — Delegates to the 4-argument version with `isSetAsString = false`.
- `storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)` — **The core write dispatch**. Mirrors `loadModelData` exactly: matches the key and subkey, then calls the appropriate setter on the bean. For list categories, it parses the index from the key and recursively calls `storeModelData` on the child `KKW00801SF02DBean` item.

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

Returns the Java type for a given key/subkey pair. This is the **type introspection** method:

- For `"value"` subkeys: returns `String.class`.
- For `"enable"` subkeys: returns `Boolean.class`.
- For `"state"` subkeys: returns `String.class`.
- For list categories: if the subkey remainder is `"*"`, returns `Integer.class` (representing list count); otherwise, recursively delegates to the child bean's `typeModelData`.
- Returns `null` for unknown keys or null inputs.

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

A **static factory method** that returns a hardcoded list of all 13 property keys as Japanese strings. This is used by the UI framework to enumerate which fields are available on the screen. The list includes:

1. メールアドレスアカウント (Mail Address Account)
2. メールアドレスドメイン (Mail Address Domain)
3. メールエイリアス (Mail Alias)
4. メールボックス容量 (Mailbox Capacity)
5. ウィルスチェック (Virus Check)
6. ＰＯＰＩＤ (POP ID)
7. 利用開始日（年）(Start Date Year)
8. 利用開始日（月）(Start Date Month)
9. 利用開始日（日）(Start Date Day)
10. 表示用メールボックス容量 (Display Mailbox Capacity)
11. 表示用ウィルスチェック (Display Virus Check)
12. 登録用メールボックス容量ＭＢ値 (Register Mail Cap MB)
13. メールPOP容量選択リスト (Mail POP Capacity Selection List)
14. ウィルスチェック選択リスト (Virus Check Selection List)

### `addListDataInstance(String key) → int`

Dynamically appends a new `KKW00801SF02DBean` instance to one of the two list collections and returns the new element's index (or `-1` if the key is unrecognized). If the target list is null, it initializes an empty list first.

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

Removes the element at the given index from the specified list, with bounds checking.

### `clearListDataInstance(String key) → void`

Nulls out the entire list collection for the given key, effectively clearing all items.

### Getter/Setter pairs

Every field has a standard JavaBean getter and setter. The value getters return `String`, the enabled getters return `Boolean`, and the state/update getters return `String`. These provide fine-grained access for individual properties when the generic dispatch is not appropriate (e.g., when the JSP page binds directly to a field).

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

Simple accessor for the `index` field, used to track the position of this bean within a list or iteration context.

## Relationships

```mermaid
flowchart LR
    A["KKW008010PJP.jsp
(View 1 - Account/Dates)"] -->|"creates"| B["KKW00801SF01DBean"]
    C["KKW008020PJP.jsp
(View 2 - Volume Lists)"] -->|"creates"| B["KKW00801SF01DBean"]
    B -->|"contains"| D["X33VDataTypeList mlbox_cap_op_list_list"]
    B -->|"contains"| E["X33VDataTypeList virus_chk_op_list_list"]
    B -->|"instantiates"| F["KKW00801SF02DBean
(item type)"]
    B -->|"implements"| G["X33VDataTypeBeanInterface"]
    B -->|"implements"| H["X33VListedBeanInterface"]
```

### Inbound: who uses this class

| Consumer | File | How |
|---|---|---|
| View 1 | `KKW008010PJP.jsp` | Creates and populates a `KKW00801SF01DBean` instance; binds form fields to it for account, date, and basic configuration data. |
| View 2 | `KKW008020PJP.jsp` | Creates and populates a `KKW00801SF01DBean` instance; binds form fields to it for capacity lists and virus selection options. |

### Outbound: what this class depends on

- `X33VDataTypeBeanInterface` — the interface defining `loadModelData`, `storeModelData`, and `typeModelData`.
- `X33VListedBeanInterface` — the interface defining `addListDataInstance`, `removeElementFromListData`, `clearListDataInstance`.
- `X33VDataTypeList` — a custom typed list used to hold child bean items.
- `KKW00801SF02DBean` — the child bean type instantiated when building list data.
- `ArrayList`, `SelectItem` — standard collections and JSF components used internally.
- `Serializable` — Java's standard serialization interface.

```mermaid
flowchart TD
    subgraph DataTypes["Primitive Data Types (value / enable / state)"]
        A1["mlad_account
Mail Address Account"]
        A2["mlad_domain
Mail Address Domain"]
        A3["mailalias
Mail Alias"]
        A4["mlbox_capa_index
Mailbox Capacity"]
        A5["virus_chk_index
Virus Check"]
        A6["pop_id
POP ID"]
        A7["use_staymd_year
Start Date Year"]
        A8["use_staymd_mon
Start Date Month"]
        A9["use_staymd_day
Start Date Day"]
        A10["mlbox_capa_value
Display Mailbox Cap"]
        A11["virus_chk_value
Display Virus Check"]
        A12["mlbox_capa_mb
Register Mail Cap MB"]
    end

    subgraph Lists["List Data Types"]
        B1["mlbox_cap_op_list
Mail POP Cap Selection List"]
        B2["virus_chk_op_list
Virus Check Selection List"]
    end

    A1 -->|"field"| B["KKW00801SF01DBean"]
    A2 -->|"field"| B
    A3 -->|"field"| B
    A4 -->|"field"| B
    A5 -->|"field"| B
    A6 -->|"field"| B
    A7 -->|"field"| B
    A8 -->|"field"| B
    A9 -->|"field"| B
    A10 -->|"field"| B
    A11 -->|"field"| B
    A12 -->|"field"| B
    B1 -->|"field"| B
    B2 -->|"field"| B
```

## Usage Example

### Typical call flow from a JSP page

```java
// 1. Create the bean in a JSP
KKW00801SF01DBean bean = new KKW00801SF01DBean();

// 2. Pre-populate with default options (lists initialized in constructor)
KKW00801SF01DBean.addListDataInstance("メールPOP容量選択リスト");
KKW00801SF01DBean.addListDataInstance("ウィルスチェック選択リスト");

// 3. Read a field via the generic dispatch
Object value = bean.loadModelData("メールアドレスアカウント", "value");
// → returns getMlad_account_value()

// 4. Write a field via the generic dispatch
bean.storeModelData("メールアドレスアカウント", "value", "user@example.com");
// → calls setMlad_account_value("user@example.com")

// 5. Introspect type
Class<?> type = bean.typeModelData("メールアドレスアカウント", "enable");
// → returns Boolean.class

// 6. Access fields directly for JSF binding
bean.getMlad_account_value();       // "user@example.com"
bean.getMlad_account_enabled();     // Boolean.TRUE/FALSE
bean.getMlad_account_state();       // status string or ""
```

### Reading a list item via dispatch

```java
// Read the "name" property of the first item in the Mail POP capacity list
Object itemValue = bean.loadModelData("メールPOP容量選択リスト/0/propertyName", "value");
// → internally: mlbox_cap_op_list_list.get(0).loadModelData("propertyName", "value")

// Get list count
Object count = bean.loadModelData("メールPOP容量選択リスト/*", null);
// → returns Integer.valueOf(mlbox_cap_op_list_list.size())
```

## Notes for Developers

### Thread safety
The bean is **not thread-safe**. It maintains mutable state (`String` values, `Boolean` flags, `X33VDataTypeList` collections) that can be modified concurrently by multiple requests if the bean is stored in a shared scope (e.g., application session). Each HTTP request should receive its own instance.

### Null handling
All three dispatch methods (`loadModelData`, `storeModelData`, `typeModelData`) defensively return `null` (or no-op for `storeModelData`) when `key` or `subkey` is `null`. This means callers should not assume the return value is always non-null — always check before casting.

### Key/subkey contract
The key names are hardcoded Japanese strings — they are not constants defined as `public static final`. The `listKoumokuIds()` static method is the authoritative source. If you introduce new fields, you must add the corresponding key string to `listKoumokuIds()` and update all three dispatch methods (`loadModelData`, `storeModelData`, `typeModelData`) with matching branches.

### List item type
Both list collections hold `KKW00801SF02DBean` instances (as cast by `(X33VDataTypeBeanInterface)`). The actual runtime type is `KKW00801SF02DBean` — this is known from the `addListDataInstance` method where `new KKW00801SF02DBean()` is called.

### `isSetAsString` flag
The 4-argument `storeModelData` has an `isSetAsString` parameter that controls whether `Long`-type properties should be set from a `String` value. In practice this bean's primitive fields are all `String`/`Boolean`, so this flag likely has no effect for this specific bean, but is inherited from the parent interface contract.

### No superclass
The class does not extend any base class. All behavior is built from scratch, relying only on interface implementations. This means `protected` access does not expose any inherited fields.

### `mlbox_capa_mb` exception
The "Register Mail Cap MB" category (`mlbox_capa_mb`) has no `enabled` field — it only has `value`, `state`, and `update`. Similarly, `typeModelData` only handles `"value"` and `"state"` subkeys for this category (no `"enable"` branch). This appears intentional — the MB value is likely always enabled and computed or derived rather than user-toggled.

### Default values
- String value fields default to `""` (empty string).
- `enabled` fields default to `false`, except `mlbox_capa_value_enabled` and `virus_chk_value_enabled` which default to `true`.
- `state` and `update` fields default to `null`.
- Both list collections are initialized in the constructor (not left null).

### Adding new properties
To add a new top-level property to this bean, you must:
1. Declare the new `protected` fields (`_value`, `_enabled`, `_state`, `_update`).
2. Add corresponding getter/setter pairs.
3. Add the Japanese key string to `listKoumokuIds()`.
4. Add matching branches to `loadModelData()`, `storeModelData()`, and `typeModelData()`.
5. Ensure the JSP pages (`KKW008010PJP.jsp`, `KKW008020PJP.jsp`) bind to the new fields.

### Adding new list item types
To support a new list category, you must:
1. Declare a new `X33VDataTypeList` field.
2. Add matching branches in all five methods: `loadModelData`, `storeModelData`, `typeModelData`, `addListDataInstance`, `removeElementFromListData`, and `clearListDataInstance`.
3. Determine the child bean type (currently `KKW00801SF02DBean` for both lists).
4. Update `listKoumokuIds()` with the new category's Japanese key.