# Business Logic — JKKTvSvcKeiCourceChgCC.editInMsg() [38 LOC]

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

## 1. Role

### JKKTvSvcKeiCourceChgCC.editInMsg()

The `editInMsg` method is an **input message preparation routine** used in the eo optical TV service contract change system (eo光TVコース変更). It assembles a structured parameter map (`paramMap`) and enriches an incoming `CAANMsg` (Canal message envelope) with operational metadata before delegating to a Service Component (SC) call.

This method implements the **builder + delegation pattern**: it constructs the input payload by extracting data from two sources — the telegram header (transaction, usecase, operation, call type) and the user's control map (client hostname, client IP, screen ID, operator ID) — and then injects operational fields directly into the message envelope. It serves as the **input transformation layer** between the screen/business layer and the SC invocation pipeline.

The method is a private helper called exclusively by `callSC(SessionHandle, ServiceComponentRequestInvoker, IRequestParameterReadWrite, String, CAANMsg)`, which wraps the actual SC execution. `callSC` itself is used across multiple TV course change screens (KKSV0311, KKSV0312, KKSV0674, KKSV1059), making `editInMsg` a shared gateway for all inbound SC communication in the TV service contract change subsystem.

No conditional branching exists in this method — it performs a linear, deterministic assembly of all operational and session metadata, clears error state via `setNullToMsg`, and returns the fully prepared parameter map. The method has **no CRUD operations** of its own; it solely prepares data for downstream CBS (Common Business Service) calls.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["editInMsg(param, msg)"])
    START --> STEP1["Create paramMap HashMap"]
    STEP1 --> STEP2["Extract telegram header data
TRANZACTION_ID_KEY = param.getTelegramID()
USECASE_ID_KEY = param.getUsecaseID()
OPERATION_ID_KEY = param.getOperationID()
CALL_TYPE_KEY = param.getCallType()"]
    STEP2 --> STEP3["Extract user control map data
CLIENT_HOST_NAME_KEY = param.getControlMapData(REQ_HOSTNAME)
CLIENT_IP_ADDRESS_KEY = param.getControlMapData(REQ_HOSTIP)
INVOKE_GAMEN_ID_KEY = param.getControlMapData(REQ_VIEWID)
OPERATOR_ID_KEY = param.getControlMapData(OPERATOR_ID)"]
    STEP3 --> STEP4["Set msg fields
msg.set(OPERATOR_ID_KEY, ...)
msg.set(OPERATE_DATE_KEY, ...)
msg.set(OPERATE_DATETIME_KEY, ...)"]
    STEP4 --> STEP5["setNullToMsg(msg)
Clear error fields from message schema"]
    STEP5 --> STEP6["Create template array
CAANMsg[0] = msg
Put TEMPLATE_LIST_KEY into paramMap"]
    STEP6 --> STEP7["Return paramMap"]
    STEP7 --> END(["End"])
```

**Processing Flow:**
The method performs a single linear pass — no conditional branches, no loops (looping is internal to `setNullToMsg`, not within `editInMsg` itself). It first initializes a new `HashMap<String, Object>`, then populates it with eight key-value pairs sourced from the request parameter's header and control map. It then sets three fields directly on the `msg` envelope. Finally, it clears any stale error fields via `setNullToMsg(msg)`, wraps the message into a `CAANMsg[]` template array, and returns the map.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `param` | `IRequestParameterReadWrite` | The request parameter object carrying all screen-level user input and session metadata. It encapsulates the telegram header (transaction ID, usecase ID, operation ID, call type) and the control map (client hostname, client IP address, invoke screen ID, operator ID, operating date/time, error info). This is the primary data carrier between the presentation layer and the business logic layer. |
| 2 | `msg` | `CAANMsg` | The Canal message envelope (request payload) being prepared for the Service Component call. It carries business data fields defined by its schema and is enriched with operational metadata (operator ID, operate date, operate datetime) before being passed downstream. Error fields ending in `_err` are cleared during processing. |

**Instance fields / external state read:**
None — `editInMsg` is purely stateless. It reads from its parameters only.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| U | `JKKTvSvcKeiCourceChgCC.setNullToMsg` | - | - | Clears error fields (`*_err`) in the message schema by setting them to null if not already populated; recursively clears error fields in nested CAANMsg arrays. Operational cleanup step. |
| R | `JKKejbCallTypeChecker.getCallType` | - | - | Reads the call type from `param` via `param.getCallType()` (note: `getCallType` is defined on the `IRequestParameterReadWrite` interface, not a separate SC). Used to classify the service invocation context. |

**Classification notes:**
- This method performs **no database or entity operations** (no Create, Read, Update, Delete against persistent storage).
- The only direct method call is `setNullToMsg(msg)`, which is an **Update**-style operation on the in-memory message envelope.
- The method's return value (`paramMap`) is consumed by the caller `callSC`, which then delegates to actual SC/CBS methods (e.g., `EKK0581A010SC`, `EKK0591B003CBS`) that perform real CRUD against entities like `KK_T_OPSVKEI_ISP`, `KK_T_ODR_HAKKO_JOKEN`, etc.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:KKSV0311 | `KKSV0311OPOperation` -> `callSC` -> `editInMsg` | `setNullToMsg [U] (in-memory msg cleanup)` |
| 2 | Screen:KKSV0312 | `KKSV0312OPOperation` -> `callSC` -> `editInMsg` | `setNullToMsg [U] (in-memory msg cleanup)` |
| 3 | Screen:KKSV0674 | `KKSV0674OPOperation` -> `callSC` -> `editInMsg` | `setNullToMsg [U] (in-memory msg cleanup)` |
| 4 | Screen:KKSV1059 | `KKSV1059OPOperation` -> `callSC` -> `editInMsg` | `setNullToMsg [U] (in-memory msg cleanup)` |

**Call chain detail:**
- `KKSVxxxxOPOperation` classes register `JKKTvSvcKeiCourceChgCC` as a common component.
- They invoke `callSC()`, which internally calls `editInMsg(param, inCAANMsg)` to build the parameter map.
- `callSC` then invokes the actual `ServiceComponentRequestInvoker.run(paramMap, handle)` against a specific SC/CBS.
- The terminal operations from `editInMsg` are limited to `setNullToMsg` (in-memory update) and the read accessors on `param` (`getTelegramID`, `getUsecaseID`, `getOperationID`, `getCallType`, `getControlMapData`).

## 6. Per-Branch Detail Blocks

**Block 1** — SET `(initialization)` (L448)

> Initializes the return parameter map and begins populating it with telegram header data from the request.

| # | Type | Code |
|---|------|------|
| 1 | SET | `paramMap = new HashMap<String, Object>()` // Create empty parameter map |
| 2 | EXEC | `paramMap.put(TRANZACTION_ID_KEY, param.getTelegramID())` // Put transaction ID from telegram header — 【取得元：電文ヘッド(ヘッド)】電文ID |
| 3 | EXEC | `paramMap.put(USECASE_ID_KEY, param.getUsecaseID())` // Put usecase ID from telegram header — 【取得元：電文ヘッド(ヘッド)】ユーケースID |
| 4 | EXEC | `paramMap.put(OPERATION_ID_KEY, param.getOperationID())` // Put operation ID from telegram header — 【取得元：電文ヘッド(ヘッド)】オペレーションID |
| 5 | EXEC | `paramMap.put(CALL_TYPE_KEY, param.getCallType())` // Put call type classification — 【取得元：電文ヘッド(ヘッド)】サービス呼び出し区分 |

**Block 2** — EXEC `(user control map extraction)` (L456)

> Extracts client/session metadata from the control map and stores them in the parameter map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `paramMap.put(CLIENT_HOST_NAME_KEY, param.getControlMapData(REQ_HOSTNAME))` // Get client hostname — 【取得元：ユーザエリア(コントロールマップ)】依頼先ホスト名 |
| 2 | EXEC | `paramMap.put(CLIENT_IP_ADDRESS_KEY, param.getControlMapData(REQ_HOSTIP))` // Get client IP address — 【取得元：ユーザエリア(コントロールマップ)】依頼元IPアドレス |
| 3 | EXEC | `paramMap.put(INVOKE_GAMEN_ID_KEY, param.getControlMapData(REQ_VIEWID))` // Get invoke screen ID — 【取得元：ユーザエリア(コントロールマップ)】依頼元画面ID |
| 4 | EXEC | `paramMap.put(OPERATOR_ID_KEY, param.getControlMapData(OPERATOR_ID))` // Get operator ID — 【取得元：ユーザエリア(コントロールマップ)】オペレータID |

**Block 3** — EXEC `(msg field enrichment)` (L462)

> Sets operational fields directly on the message envelope and then cleans up error state.

| # | Type | Code |
|---|------|------|
| 1 | SET | `msg.set(OPERATOR_ID_KEY, param.getControlMapData(OPERATOR_ID))` // Set operator ID on message — オペレータID |
| 2 | SET | `msg.set(OPERATE_DATE_KEY, param.getControlMapData(OPE_DATE))` // Set operating date on message — 運用日付 |
| 3 | SET | `msg.set(OPERATE_DATETIME_KEY, param.getControlMapData(OPE_TIME))` // Set operating datetime on message — 運用日時 |
| 4 | CALL | `setNullToMsg(msg)` // Clear all *_err fields from message schema — エラー情報の初期化 |

**Block 4** — RETURN `(template preparation and return)` (L468)

> Wraps the enriched message into a template array and returns the completed parameter map for SC invocation.

| # | Type | Code |
|---|------|------|
| 1 | SET | `templates = new CAANMsg[]{msg}` // Create single-element template array |
| 2 | EXEC | `paramMap.put(TEMPLATE_LIST_KEY, templates)` // Register template list in paramMap |
| 3 | RETURN | `return paramMap` // Return complete parameter map to caller (callSC) |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `JKKTvSvcKeiCourceChgCC` | Class | TV Service Contract Line Change Common Component — shared component class handling common logic for eo optical TV course change operations |
| `editInMsg` | Method | Edit Incoming Message — builds the input parameter map and enriches the request message envelope before SC delegation |
| `IRequestParameterReadWrite` | Interface | Request Parameter Read/Write interface — the contract for accessing screen input data, telegram headers, and control map session data |
| `CAANMsg` | Class | Canal Message — Fujitsu's message envelope class carrying structured business data between application layers; supports schema-based field access and nested message arrays |
| `paramMap` | Variable | Parameter Map — a HashMap used to assemble key-value pairs for SC invocation |
| `TRANZACTION_ID_KEY` | Constant | Transaction ID key — maps to the request's unique transaction identifier from the telegram header |
| `USECASE_ID_KEY` | Constant | Usecase ID key — maps to the business usecase identifier from the telegram header |
| `OPERATION_ID_KEY` | Constant | Operation ID key — maps to the operation identifier from the telegram header |
| `CALL_TYPE_KEY` | Constant | Call Type key — classifies the type of service invocation (e.g., screen-initiated, batch-initiated) |
| `CLIENT_HOST_NAME_KEY` | Constant | Client Hostname key — maps to the requesting client's hostname |
| `CLIENT_IP_ADDRESS_KEY` | Constant | Client IP Address key — maps to the requesting client's IP address |
| `INVOKE_GAMEN_ID_KEY` | Constant | Invoke Screen ID key — maps to the originating screen identifier; "gamen" is Japanese for "screen" |
| `OPERATOR_ID_KEY` | Constant | Operator ID key — maps to the ID of the operator/user who initiated the request |
| `TEMPLATE_LIST_KEY` | Constant | Template List key — maps to the CAANMsg[] array used by the SC infrastructure for response message mapping |
| `REQ_HOSTNAME` | Constant | Request Hostname key — control map key for the client hostname |
| `REQ_HOSTIP` | Constant | Request Host IP key — control map key for the client IP address |
| `REQ_VIEWID` | Constant | Request View ID key — control map key for the originating screen ID |
| `OPERATOR_ID` | Constant | Operator ID key — control map key for the operator identifier |
| `OPE_DATE` | Constant | Operation Date key — control map key for the operating date |
| `OPE_TIME` | Constant | Operation Time key — control map key for the operating time |
| `setNullToMsg` | Method | Set Null to Message — recursively clears error fields (those ending in `_err`) from a CAANMsg schema by setting them to null when not already populated |
| `callSC` | Method | Call Service Component — the SC invocation wrapper that calls `editInMsg` to build parameters, then delegates to `ServiceComponentRequestInvoker.run()` |
| EO光TV (eo光TV) | Business term | EO Optical TV — NTT West's fiber-optic bundled TV service; the "course change" (コース変更) business domain covers plan/subscription modifications |
| コース変更 (Kōsu Henkō) | Business term | Course Change — the business operation of modifying an existing TV service plan or subscription |
| 電文ヘッド (Denmu Heddo) | Field | Telegram Header — the metadata portion of a message containing transaction, usecase, operation, and call type identifiers |
| ユーザエリア (Yūza Eria) | Field | User Area — the session context data area containing control map entries like hostname, IP, screen ID, and operator info |
| 運用日付 (Un'yō Hizuke) | Field | Operation Date — the date on which the system operation was performed |
| 運用日時 (Un'yō Nijī) | Field | Operation Date/Time — the full timestamp of the system operation |
| エラー情報 (Erā Jōhō) | Field | Error Information — fields ending in `_err` in the message schema, used to carry error messages back to the screen |
| SC (Service Component) | Acronym | Service Component — a mid-tier business logic component that encapsulates CBS (Common Business Service) calls for specific business functions |
| CBS (Common Business Service) | Acronym | Common Business Service — the data access layer executing CRUD operations against database entities |
| KKSV### | Pattern | Screen class naming convention — KKSV prefixes identify TV course change screen operation classes (e.g., KKSV0311, KKSV1059) |