# Business Logic — JKKStbUcwkEoTvKktkSvcKeiCC.setNullToMsg() [28 LOC]

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

## 1. Role

### JKKStbUcwkEoTvKktkSvcKeiCC.setNullToMsg()

This method is a **CAANMsg normalization utility** that cleans up error-related fields within a CAAN message object. Its business purpose is to ensure that all message fields whose keys end with the `_err` suffix have well-defined values — specifically, if the corresponding non-suffixed field is either absent from the message or empty (`""`), the error field is explicitly set to `null`. This prevents downstream validation or screen-rendering logic from encountering undefined or blank error markers, which could cause errors in telecom service order processing screens.

The method operates as a **recursive traversal/dispatch pattern** over the CAAN message structure. It handles two service data shapes: flat scalar fields (where a single `_err` field accompanies a data field) and nested array structures (`CAANMsg[]`), where the method recursively invokes itself on each child message. This dual-mode operation makes it a reusable normalization step suitable for any CAANMsg payload in the STB usage/work order television service contract processing domain.

Its **role in the larger system** is that of a shared data hygiene gate. It is invoked within `editInMsg()`, a private method that builds the inbound parameter map for the service contract processing screen (KKSV0169 and related). By being called as part of the inbound message preparation pipeline, `setNullToMsg` guarantees that error fields are in a known state before the message is passed to downstream business logic and presentation layers.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["setNullToMsg(CAANMsg msg)"])
    CAAN_KEY_SET(["Get schema key set from msg.getSchema()"])
    ITERATE_KEYS(["Iterator: caanMsgKeys"])
    CHECK_KEY_CAAN(["key has next?"])
    GET_NEXT_KEY(["String key = caanMsgKeys.next()"])
    CHECK_SUFFIX(["key.endsWith('_err')?"])
    SKIP_TO_NEXT(["Continue to next key"])
    SUBSTR_KEY(["String tmpKey = substring(0, key.length - 4)"])
    CHECK_CONTAINS(["containsKey(tmpKey) OR getObject(tmpKey) != empty?"])
    SET_NULL(["msg.setNull(tmpKey)"])
    SKIP_TO_NEXT_2(["Continue to next key"])
    GET_OBJ(["Object obj = msg.getObject(tmpKey)"])
    CHECK_ARRAY(["obj instanceof CAANMsg[]?"])
    ITERATE_ARRAY(["for each CAANMsg submsg in array"])
    RECURSIVE_CALL(["setNullToMsg(submsg)"])
    END_PROCESS(["End: return (void)"])

    START --> CAAN_KEY_SET
    CAAN_KEY_SET --> ITERATE_KEYS
    ITERATE_KEYS --> CHECK_KEY_CAAN
    CHECK_KEY_CAAN -- true --> GET_NEXT_KEY
    CHECK_KEY_CAAN -- false --> END_PROCESS
    GET_NEXT_KEY --> CHECK_SUFFIX
    CHECK_SUFFIX -- false --> SKIP_TO_NEXT
    CHECK_SUFFIX -- true --> SUBSTR_KEY
    SUBSTR_KEY --> CHECK_CONTAINS
    CHECK_CONTAINS -- false --> SET_NULL
    CHECK_CONTAINS -- true --> GET_OBJ
    SET_NULL --> SKIP_TO_NEXT_2
    SKIP_TO_NEXT --> ITERATE_KEYS
    SKIP_TO_NEXT_2 --> ITERATE_KEYS
    GET_OBJ --> CHECK_ARRAY
    CHECK_ARRAY -- true --> ITERATE_ARRAY
    CHECK_ARRAY -- false --> ITERATE_KEYS
    ITERATE_ARRAY --> RECURSIVE_CALL
    RECURSIVE_CALL --> ITERATE_ARRAY
    ITERATE_ARRAY --> ITERATE_KEYS
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `msg` | `CAANMsg` | The inbound telecom service message object (CAAN envelope) being prepared for screen processing. It carries fields for STB usage/work order television service data along with their associated `_err` error indicator fields. |

**External / Instance State Read:** None — this method is purely stateless and operates entirely on the passed `msg` parameter.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `CAANMsg.getSchema` | CAANMsg | - | Reads schema keys from the CAAN message envelope |
| R | `CAANMsg.containsKeyOfMsgData` | CAANMsg | - | Checks if a data field exists in the message |
| R | `CAANMsg.getObject` | CAANMsg | - | Reads a data field's value from the message |
| U | `CAANMsg.setNull` | CAANMsg | - | Clears a data field by setting it to null |
| - | `CAANMsg[]` iteration | CAANMsg | - | Iterates over nested CAAN message arrays (recursive children) |

This method performs **no database access**. All operations are in-memory manipulations on the `CAANMsg` object — a message envelope class used in the Fujitsu FUTURITY platform for screen-to-CBS data exchange.

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 2 methods (within the same class).
Terminal operations from this method: `getObject` [R], `getObject` [R], `setNull` [-], `getSchema` [-], `containsKeyOfMsgData` [-], `setNullToMsg` [-]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | JKKStbUcwkEoTvKktkSvcKeiCC.editInMsg | `editInMsg(param, msg)` -> `setNullToMsg(msg)` | `setNull [U] CAANMsg`, `getObject [R] CAANMsg`, `containsKeyOfMsgData [R] CAANMsg` |
| 2 | JKKStbUcwkEoTvKktkSvcKeiCC.setNullToMsg (recursive) | `setNullToMsg(msg)` -> `setNullToMsg(submsg)` | `setNull [U] CAANMsg`, `getObject [R] CAANMsg` |

**Notes on callers from the broader codebase:**
The same method name (`setNullToMsg`) is implemented identically across multiple common component classes (JKKPresentCdListCMPCC, JKKSeiKeiKapListCC, JCNCardKssaiYokyuDataSendCC, JKKSpMskmViewCtrlBaseCC, JKKGetSvcIdoRsv, JKKOpsvkeiTelIktAddCC, JKKTVSvcKeiKaihukuCC, JCKSysidIchiiSearchCmpCC) and mapper classes (KKSV0169 KKSV0169OP_EKU0041C010BSMapper, KKSV0169 KKSV0169OP_EKU0031C010BSMapper). Each copy serves the same normalization purpose for its respective message payload. The specific class `JKKStbUcwkEoTvKktkSvcKeiCC`'s version is invoked from `editInMsg()` as part of the STB usage/work order television service contract processing flow.

## 6. Per-Branch Detail Blocks

**Block 1** — [WHILE] `(caanMsgKeys.hasNext())` (L859)

> Iterates over all schema keys defined in the CAAN message. Each key represents a field name in the message envelope.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Iterator<String> caanMsgKeys = msg.getSchema().getSchemaKeySet().iterator();` // Obtain iterator over all message schema keys |
| 2 | WHILE | `while (caanMsgKeys.hasNext())` // Iterate through all keys |

**Block 1.1** — [IF] `(key.endsWith("_err"))` (L862)

> Filters to only process error indicator fields. Fields not ending with `_err` are skipped — these are regular data fields, not error markers, and should not be cleaned.

| # | Type | Code |
|---|------|------|
| 1 | IF | `if (!key.endsWith("_err"))` // Skip non-error keys |
| 1.1 | ELSE-BODY | `continue;` // Skip this key, move to next |
| 2 | SET | `String tmpKey = key.substring(0, key.length() - 4);` // Strip `_err` suffix to get the associated data field name — e.g., `"name_err"` -> `"name"` [-> ENDING_SUFFIX="_err"] |

**Block 1.1.1** — [IF] `(!msg.containsKeyOfMsgData(tmpKey) || "".equals(msg.getObject(tmpKey)))` (L866)

> Checks whether the data field (without `_err` suffix) is either missing from the message or holds an empty string. If so, the error field is set to null because there is no meaningful error to report — the data itself is absent or blank.

| # | Type | Code |
|---|------|------|
| 1 | IF | `if (!msg.containsKeyOfMsgData(tmpKey) || "".equals(msg.getObject(tmpKey)))` // If data field missing or empty |
| 1.1 | IF-BODY | `msg.setNull(tmpKey);` // Set the data field to null (clears any stale error state) |
| 1.2 | IF-BODY | `continue;` // Skip array check, move to next key |

**Block 1.1.2** — [IF] `(obj instanceof CAANMsg[])` (L870)

> If the data field contains a nested array of CAAN messages (e.g., a list of sub-services or child records), recursively clean up error fields in each child message. This handles multi-level message nesting typical in service contract line-item processing.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Object obj = msg.getObject(tmpKey);` // Read the data field value |
| 2 | IF | `if (obj instanceof CAANMsg[])` // Check if the value is a CAAN message array |
| 2.1 | FOR | `for (CAANMsg submsg : (CAANMsg[]) obj)` // Iterate over each child message |
| 2.1.1 | CALL | `setNullToMsg(submsg);` // Recursive call: clean up error fields in the nested message [-> RECURSIVE_DEPTH varies by nesting] |
| 3 | END | `}` // End if block, return to while loop |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| CAANMsg | Technical | CAAN Message envelope — Fujitsu's inter-screen/CBS data exchange object used in the FUTURITY platform. Carries typed fields for all screen parameters and return values. |
| `_err` suffix | Field convention | Error indicator field naming convention — every data field may have a corresponding `<field>_err` field used to carry validation error flags or messages back to the screen. |
| STB | Business term | Set-Top Box — consumer television reception equipment managed in the telecom service order system. |
| svc_kei_ucwk_no | Field | Service detail work number — internal tracking ID for service contract line items related to STB usage and work orders. |
| editInMsg | Method | Inbound message builder — constructs the parameter map from screen input data, populates operational headers (operator ID, date, client info), and invokes `setNullToMsg` for data hygiene before processing. |
| CAANMsg[] | Data structure | Array of nested CAAN message objects, representing a list of child records (e.g., multiple service line items or configuration records within a single parent order). |
| SC Control Map Keys | Technical | Control map data from the CBS invocation framework — includes hostname, client IP, screen ID, operator ID, operation date/time used for audit and routing. |