# Business Logic — JKKEmailInfoAddCfmCC.setOptinm() [95 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKEmailInfoAddCfmCC` |
| Layer | CC/Common Component |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKEmailInfoAddCfmCC.setOptinm()

This method registers and reconciles opt-in mail reception settings (opt-in email subscription configuration) for a given customer line (mlad). The Japanese Javadoc states: "Register the opt-in mail reception settings" (オプトインメール受信設定を登録する). It operates as a **dispatch-and-rout**e component within the Fujitsu Futurity business platform, handling the full lifecycle of opt-in mail enrollment: it first fetches the list of existing opt-in mail entries (オプトインメール一覧照会), then for each entry, checks whether the customer's opt-in reception settings are already registered and verified against their consent.

The method implements a **conditional routing pattern** based on the registration status of each opt-in mail entry: if the customer has **not yet registered** opt-in mail reception settings, it **inserts** a new record. If they **are already registered** and their status is "Invalid" (無効, status code "020"), it **restores** the setting to "Valid". This ensures that whenever opt-in mail info is added or confirmed for a service, the customer's opt-in email subscription state is properly synchronized.

The method iterates over a list of opt-in mail entries returned by a batch inquiry, processing each entry sequentially with conditional logic. It serves as a **shared utility component** called by the screen controller (`JKKEmailInfoAddCfmCC.mainProc`), which means it is a reusable business logic bridge between the presentation layer and the service components.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["setOptinm params"])
    START --> INIT["Initialize statusCode=0, optinm_no, optinm_stat"]
    INIT --> CALL1["callECK0141B002SC - Fetch opt-in mail list"]
    CALL1 --> CHECK1{statusCode != 0?}
    CHECK1 -->|Yes| RET1["Return statusCode"]
    CHECK1 -->|No| GET1["Get eCK0141B002Hash from resultHash"]
    GET1 --> CHECK2{Hash not null AND list not null?}
    CHECK2 -->|No| RET2["Return statusCode"]
    CHECK2 -->|Yes| LOOP["For each eCK0141B002List entry"]
    LOOP --> GETMSG["Get msgData from eCK0141B002List[j]"]
    GETMSG --> GETNO["Extract optinm_no"]
    GETNO --> CALL2["callECK0141A010SC - Fetch opt-in mail reception settings"]
    CALL2 --> CHECK3{statusCode != 0?}
    CHECK3 -->|Yes| RET3["Return statusCode"]
    CHECK3 -->|No| CALL3["callECK0011A010SC - Check customer consent"]
    CALL3 --> CHECK4{statusCode != 0?}
    CHECK4 -->|Yes| RET4["Return statusCode"]
    CHECK4 -->|No| CHECK5{eCK0141A010Hash null or empty?}
    CHECK5 -->|Yes - Not registered| CALL4["callECK0141D010SC - Register opt-in mail settings"]
    CHECK5 -->|No - Already registered| GETSTAT["Extract optinm_stat"]
    GETSTAT --> CHECK6{optinm_stat equals 020?}
    CHECK6 -->|Yes| CALL5["callECK0141C040SC - Restore opt-in settings to valid"]
    CHECK6 -->|No| NEXT["Next loop iteration"]
    CALL4 --> RET5{statusCode != 0?}
    RET5 -->|Yes| RET5Y["Return statusCode"]
    RET5 -->|No| NEXT
    CALL5 --> RET6{statusCode != 0?}
    RET6 -->|Yes| RET6Y["Return statusCode"]
    RET6 -->|No| NEXT
    NEXT --> LOOPEND{More entries?}
    LOOPEND -->|Yes| GETMSG
    LOOPEND -->|No| RETFINAL["Return statusCode"]
    RET1 --> END(["End"])
    RET2 --> END
    RET3 --> END
    RET4 --> END
    RET5Y --> END
    RET6Y --> END
    RETFINAL --> END
```

**CRITICAL - Constant Resolution:**

| Constant | Actual Value | Business Meaning |
|----------|-------------|-----------------|
| `TEMPLATE_ID_ECK0141B002` | `"ECK0141B002"` (L280) | Template key for opt-in mail list inquiry result stored in resultHash |
| `TEMPLATE_ID_ECK0141A010` | `"ECK0141A010"` (L278) | Template key for opt-in mail reception settings inquiry result stored in resultHash |
| `OPTINM_RCV_SETTE_STAT_MK` | `"020"` (L296) | Status code meaning "Invalid" (無効) - used to detect when opt-in settings need restoration |

**Processing Flow Summary:**

1. **Initialize** local variables: `statusCode`, `optinm_no` (opt-in mail number), `optinm_stat` (opt-in mail reception settings status).
2. **Fetch opt-in mail list** (オプトインメール一覧照会) via `callECK0141B002SC`. If this fails, return early with the error status code.
3. **Extract the result list** from `resultHash` using the template key `"ECK0141B002"`. If the hash or its list contents are null, skip processing and return.
4. **Iterate over each opt-in mail entry** in the list:
   a. Extract `optinm_no` from the current entry's message data.
   b. **Fetch opt-in reception settings** (オプトインメール受信設定一意照会) for this `optinm_no` via `callECK0141A010SC`. Return early on error.
   c. **Check customer consent** (お客様一意照会) via `callECK0011A010SC`. Return early on error.
   d. **Conditional routing based on registration status:**
      - **If NOT registered** (resultHash is null or empty): **Register** the opt-in mail reception settings (オプトインメール受信設定登録) via `callECK0141D010SC`.
      - **If already registered**: Extract the current `optinm_stat` from the result. **If the status is "020" (Invalid/無効)**: **Restore** the opt-in settings to valid (オプトインメール受信設定恢复) via `callECK0141C040SC`.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `param` | `IRequestParameterReadWrite` | Request parameter carrier that holds input data sent from the screen/batch entry point. Used to read and write request-level data for the service component calls. |
| 2 | `handle` | `SessionHandle` | Session management handle providing access to the current user session, transaction context, and application state. Passed through to all service component calls. |
| 3 | `requestParam` | `HashMap<String, Object>` | Input conditions hash containing filtering criteria and parameters for the opt-in mail registration process. Used as the conditions hash (条件用Hash) for SC calls. |
| 4 | `resultHash` | `HashMap<String, Object>` | Results hash that accumulates data returned from service component calls. Contains template-keyed results (e.g., `"ECK0141B002"`, `"ECK0141A010"`) with opt-in mail list and reception settings data. Used as the results hash (結果のハッシュ). |
| 5 | `mlad` | `String` | Multiple Line Access Delineator — a unique customer line identifier used to specify which customer's opt-in settings are being processed. Each line represents a distinct service subscription for a customer. |

**External/Instance Fields Read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `TEMPLATE_ID_ECK0141B002` | `static final String` = `"ECK0141B002"` | Template key constant for the opt-in mail list inquiry result stored in resultHash |
| `TEMPLATE_ID_ECK0141A010` | `static final String` = `"ECK0141A010"` | Template key constant for the opt-in mail reception settings inquiry result stored in resultHash |
| `OPTINM_RCV_SETTE_STAT_MK` | `static final String` = `"020"` | Status marker constant meaning "Invalid" (無効) — used to detect when existing opt-in settings need to be restored to valid |

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `JKKEmailInfoAddCfmCC.callECK0141B002SC` | ECK0141B002SC | (DB: Opt-in mail master table) | Calls `callECK0141B002SC` — Opt-in mail list inquiry (オプトインメール一覧照会). Reads the list of opt-in mail entries associated with the customer. |
| R | `JKKEmailInfoAddCfmCC.callECK0141A010SC` | ECK0141A010SC | (DB: Opt-in reception settings table) | Calls `callECK0141A010SC` — Opt-in mail reception settings single-record inquiry (オプトインメール受信設定一意照会). Queries whether opt-in settings are already registered for a specific `optinm_no`. |
| R | `JKKEmailInfoAddCfmCC.callECK0011A010SC` | EKK0011A010SC | (DB: Customer master table) | Calls `callECK0011A010SC` — Customer single-record inquiry (お客様一意照会). Verifies customer existence and consent state before proceeding with opt-in registration. |
| C | `JKKEmailInfoAddCfmCC.callECK0141D010SC` | ECK0141D010SC | (DB: Opt-in reception settings table) | Calls `callECK0141D010SC` — Opt-in mail reception settings registration (オプトインメール受信設定登録). Inserts a new opt-in reception settings record when the customer has not previously registered. |
| U | `JKKEmailInfoAddCfmCC.callECK0141C040SC` | ECK0141C040SC | (DB: Opt-in reception settings table) | Calls `callECK0141C040SC` — Opt-in mail reception settings restoration (オプトインメール受信設定恢复). Updates an existing record's status from "Invalid" (020) back to "Valid". |

**Classification Rationale:**

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `callECK0141B002SC` | ECK0141B002SC | Opt-in mail master | Reads all opt-in mail entries for the customer line — batch list inquiry (一覧照会) |
| R | `callECK0141A010SC` | ECK0141A010SC | Opt-in reception settings | Reads single opt-in reception settings record by optinm_no — single-record inquiry (一意照会) |
| R | `callECK0011A010SC` | EKK0011A010SC | Customer master | Reads customer record — single-record inquiry (一意照会) for consent verification |
| C | `callECK0141D010SC` | ECK0141D010SC | Opt-in reception settings | Creates a new opt-in reception settings record — registration (登録) |
| U | `callECK0141C040SC` | ECK0141C040SC | Opt-in reception settings | Updates existing record status from Invalid to Valid — restoration (恢复) |

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 2 methods.
Terminal operations from this method: `callECK0141C040SC` [R], `callECK0141D010SC` [R], `callECK0011A010SC` [R], `callECK0141A010SC` [R], `callECK0141B002SC` [R]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `JKKEmailInfoAddCfmCC.mainProc()` | `mainProc` -> `setOptinm` | `callECK0141B002SC [R] opt-in-mail-master`, `callECK0141A010SC [R] opt-in-reception-settings`, `callECK0011A010SC [R] customer-master`, `callECK0141D010SC [C] opt-in-reception-settings`, `callECK0141C040SC [U] opt-in-reception-settings` |

**Instructions:**
- The direct caller is `JKKEmailInfoAddCfmCC.mainProc()`, which is the main processing entry point of the `JKKEmailInfoAddCfmCC` class. This class is a common component (CC) that handles email information addition confirmation logic.
- The `mainProc` method serves as the screen/batch coordinator, delegating to `setOptinm` for opt-in mail registration processing.

## 6. Per-Branch Detail Blocks

**Block 1** — [VARIABLE DECLARATION / INITIALIZATION] (L4890-L4895)

> Initialize local variables and status flags before processing begins.

| # | Type | Code |
|---|------|------|
| 1 | SET | `statusCode = 0` // Initialize return status code to success |
| 2 | SET | `optinm_no = ""` // Opt-in mail number (オプトインメール番号) |
| 3 | SET | `optinm_stat = ""` // Opt-in mail reception settings status (オプトインメール受信設定ステータス) |
| 4 | SET | `eCK0141B002Hash = null` // Hash to hold opt-in mail list inquiry result |
| 5 | SET | `eCK0141B002List = null` // Array of opt-in mail list entries |
| 6 | SET | `eCK0141B002SubHash = null` // Sub-hash for current list entry's message data |
| 7 | SET | `eCK0141A010Hash = null` // Hash to hold opt-in reception settings inquiry result |

**Block 2** — [IF] `(statusCode != 0) [after callECK0141B002SC]` (L4897-L4901)

> Call the opt-in mail list inquiry (オプトインメール一覧照会). If the service component returns a non-zero status code, the method immediately returns the error status, short-circuiting all further processing.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `statusCode = callECK0141B002SC(param, handle, requestParam, resultHash)` |
| 2 | IF | `statusCode != 0` — Early return on failure |
| 3 | RETURN | `return statusCode` |

**Block 3** — [IF] `(eCK0141B002Hash != null && eCK0141B002Hash.get(ECK0141B002CBSMsg.ECK0141B002CBSMSG1LIST) != null)` (L4905-L4981)

> Retrieve the opt-in mail list result from resultHash using template key `TEMPLATE_ID_ECK0141B002 = "ECK0141B002"`. If the result hash or its message list is null, skip all opt-in mail processing and proceed to return the status code.

| # | Type | Code |
|---|------|------|
| 1 | SET | `eCK0141B002Hash = (HashMap)resultHash.get(TEMPLATE_ID_ECK0141B002)` — `[-> TEMPLATE_ID_ECK0141B002="ECK0141B002"]` |
| 2 | IF | `eCK0141B002Hash != null AND list != null` — Proceed with list processing |

**Block 3.1** — [FOR LOOP] `(j = 0; j < eCK0141B002List.length; j++)` (L4910-L4980)

> Iterate over each opt-in mail entry from the list inquiry result. This is the main processing loop that handles each entry independently.

| # | Type | Code |
|---|------|------|
| 1 | SET | `j = 0` — Loop index initialization |
| 2 | SET | `eCK0141B002SubHash = (HashMap)eCK0141B002List[j].getMsgData()` — Extract message data from current list entry |
| 3 | SET | `optinm_no = (String)eCK0141B002SubHash.get(ECK0141B002CBSMsg1List.OPTINM_NO)` — Extract opt-in mail number |
| 4 | CALL | `statusCode = callECK0141A010SC(param, handle, requestParam, resultHash, optinm_no, mlad)` — Fetch opt-in reception settings |
| 5 | SET | `eCK0141A010Hash = (HashMap)resultHash.get(TEMPLATE_ID_ECK0141A010)` — `[-> TEMPLATE_ID_ECK0141A010="ECK0141A010"]` |
| 6 | CALL | `statusCode = callECK0011A010SC(param, handle, requestParam, resultHash)` — Check customer consent |

**Block 3.1.1** — [IF] `(statusCode != 0) [after callECK0141A010SC]` (L4915-L4918)

> After fetching opt-in reception settings for the current entry, return immediately if an error occurred.

| # | Type | Code |
|---|------|------|
| 1 | IF | `statusCode != 0` — Early return on settings inquiry failure |
| 2 | RETURN | `return statusCode` |

**Block 3.1.2** — [IF] `(statusCode != 0) [after callECK0011A010SC]` (L4922-L4925)

> After checking customer consent, return immediately if an error occurred.

| # | Type | Code |
|---|------|------|
| 1 | IF | `statusCode != 0` — Early return on customer inquiry failure |
| 2 | RETURN | `return statusCode` |

**Block 3.1.3** — [IF/ELSE] `(null == eCK0141A010Hash || 0 == eCK0141A010Hash.size())` (L4928-L4975)

> **Conditional routing: is the opt-in reception settings already registered?**
> - **TRUE (Not registered)**: The hash is null or empty, meaning this customer has no existing opt-in reception settings. **Register** a new record.
> - **FALSE (Already registered)**: The hash contains data. Check the current status and potentially restore it.

| # | Type | Code |
|---|------|------|
| 1 | IF | `eCK0141A010Hash == null || eCK0141A010Hash.size() == 0` — Not registered |
| 2 | ELSE | Already registered — check status |

**Block 3.1.3.1** — [IF BRANCH] `Not registered` (L4930-L4936)

> Opt-in reception settings are not yet registered for this optinm_no. **Register** the settings by calling the registration service component with the current list entry's data and the mlad parameter.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `statusCode = callECK0141D010SC(param, handle, requestParam, resultHash, eCK0141B002SubHash, mlad)` — Register opt-in mail reception settings (オプトインメール受信設定登録) |
| 2 | IF | `statusCode != 0` — Early return on registration failure |
| 3 | RETURN | `return statusCode` |

**Block 3.1.3.2** — [ELSE BRANCH] `Already registered` (L4938-L4975)

> Opt-in reception settings are already registered. Extract the current status and determine if restoration is needed.

| # | Type | Code |
|---|------|------|
| 1 | SET | `optinm_stat = (String)eCK0141A010Hash.get(ECK0141A010CBSMsg1List.OPTINM_RCV_SETTE_STAT)` — Extract current status |
| 2 | IF | `OPTINM_RCV_SETTE_STAT_MK.equals(optinm_stat)` — `[-> OPTINM_RCV_SETTE_STAT_MK="020" (Invalid)]` |

**Block 3.1.3.2.1** — [IF BRANCH] `optinm_stat == "020"` (L4947-L4954)

> The opt-in reception settings status is "020" which means "Invalid" (無効). **Restore** the settings to a valid state by calling the restoration service component. This ensures that when opt-in mail info is added/confirmed, any previously invalid opt-in settings are reactivated.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `statusCode = callECK0141C040SC(param, handle, requestParam, resultHash, optinm_no, mlad)` — Restore opt-in mail reception settings (オプトインメール受信設定恢复) |
| 2 | IF | `statusCode != 0` — Early return on restoration failure |
| 3 | RETURN | `return statusCode` |

**Block 4** — [RETURN] (L4979-L4980)

> After completing all processing (either through the full loop or early exit), return the final status code to the caller.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return statusCode` — Return final status to caller |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `optinm_no` | Field | Opt-in mail number — unique identifier for each opt-in mail entry in the customer's subscription list |
| `optinm_stat` | Field | Opt-in mail reception settings status — indicates the current state of the opt-in settings (e.g., valid or invalid) |
| `mlad` | Field | Multiple Line Access Delineator — a unique customer line identifier that distinguishes different service subscriptions within a single customer account |
| `statusCode` | Field | Return status code — integer indicating success (0) or failure (non-zero) for the service operation |
| `requestParam` | Field | Input conditions hash — map of filtering criteria and parameters passed from the calling screen/batch |
| `resultHash` | Field | Results hash — map that accumulates data returned from service component calls, keyed by template ID |
| OPTINM_RCV_SETTE_STAT_MK | Constant | Opt-in mail reception settings status marker — value `"020"` meaning "Invalid" (無効), used to detect records that need restoration |
| TEMPLATE_ID_ECK0141B002 | Constant | Template ID key `"ECK0141B002"` — used to store/retrieve opt-in mail list inquiry results in resultHash |
| TEMPLATE_ID_ECK0141A010 | Constant | Template ID key `"ECK0141A010"` — used to store/retrieve opt-in reception settings inquiry results in resultHash |
| ECK0141B002CBSMSG1LIST | Constant | Message list key for the opt-in mail list array within the CBS response |
| ECK0141A010CBSMSG1LIST | Constant | Message list key for the opt-in reception settings single record within the CBS response |
| OPTINM_NO | Constant | Field name key for the opt-in mail number in the ECK0141B002CBSMsg1List message structure |
| OPTINM_RCV_SETTE_STAT | Constant | Field name key for the opt-in reception settings status in the ECK0141A010CBSMsg1List message structure |
| CC | Acronym | Common Component — a shared business logic component class in the Fujitsu Futurity framework, extending AbstractCommonComponent |
| SC | Acronym | Service Component — a service-tier business logic module that performs specific database operations |
| CBS | Acronym | Central Business System — the core business processing system providing transactional services |
| CAANMsg | Type | Canonical message object — a standardized message container used to pass structured data between CC and SC layers |
|オプトインメール一覧照会 | Japanese term | Opt-in mail list inquiry — business operation to retrieve all opt-in mail entries for a customer |
|オプトインメール受信設定一意照会 | Japanese term | Opt-in mail reception settings single-record inquiry — business operation to check if opt-in settings exist for a specific optinm_no |
|オプトインメール受信設定登録 | Japanese term | Opt-in mail reception settings registration — business operation to insert a new opt-in settings record |
|オプトインメール受信設定恢复 | Japanese term | Opt-in mail reception settings restoration — business operation to restore an invalid opt-in settings record to valid |
|お客様一意照会 | Japanese term | Customer single-record inquiry — business operation to verify customer data and consent |
|無効 | Japanese term | Invalid — the status value `"020"` indicating opt-in settings have been deactivated |
|一意 | Japanese term | Single/unique — indicates an inquiry that retrieves exactly one record by a unique key |
|一覧 | Japanese term | List/batch — indicates an inquiry that retrieves a list (array) of records |
|登録 | Japanese term | Registration — indicates a create/insert operation |
|恢复 | Japanese term | Restoration — indicates an update operation that restores a previous state |