# Business Logic — JKKSmtvlYoSanshoFukaInfCC.callSC() [43 LOC]

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

## 1. Role

### JKKSmtvlYoSanshoFukaInfCC.callSC()

The `callSC` method is the centralized, private service-component invocation gateway within the K-Opticom Smart BSS custom common component library. It encapsulates the entire lifecycle of calling a downstream service component — including input preparation, execution, result extraction, error translation, and status validation — into a single reusable call path. The method implements a **delegation + facade pattern**: it hides the boilerplate of building parameter maps, dispatching to the `ServiceComponentRequestInvoker`, interpreting return codes and status flags, and converting raw service results into structured `CAANMsg` objects that callers can consume directly. Its role in the larger system is as the **shared SC dispatch utility** for the `JKKSmtvlYoSanshoFukaInfCC` class, which retrieves supplementary service information for reference in Smart BSS workflows (e.g., customer-facing service contract lookups, old ICS code conversion, and telephone number resolution). All service calls originating from `getSmtvlYoSanshoFukaInf` and `getSvcKeiNoToTelSvc` funnel through this single method, ensuring consistent error handling, result parsing, and mapping behavior across the class.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["callSC params"])
    START --> EDIT["editInMsg: create paramMap from param, svcIfId, funcCode, svcIfMapData"]
    EDIT --> SCRUN["scCall.run(paramMap, handle)"]
    SCRUN --> EXTRACT["Extract result map"]
    EXTRACT --> GETTEMPLATE["Get CAANMsg[] templates from result[TPL_KEY]"]
    GETTEMPLATE --> GETRETCD["Get return code from result[RET_CD_INT_KEY]"]
    GETRETCD --> ERRTRANS["editErrorInfo(param, templates, retCdInt)"]
    ERRTRANS --> GETERRLIST["Get errList from param.getControlMapData(ERROR_INFO)"]
    GETERRLIST --> ERRLISTNULL{"errList == null?"}
    ERRLISTNULL -->|Yes| NEWERRLIST["errList = new ArrayList"]
    ERRLISTNULL -->|No| SETERRINFO
    NEWERRLIST --> SETERRINFO["param.setControlMapData ERROR_INFO with TemplateErrorUtil.getErrorInfo"]
    SETERRINFO --> GETSTATUS["Get status from templates[0] STATUS_INT_KEY"]
    GETSTATUS --> CHECKERR{"Return code equals 0 and status == 0?"}
    CHECKERR -->|No| THROW["throw SCCallException ReturnValue Incorrect"]
    CHECKERR -->|Yes| RETURN["Return templates[0]"]
    THROW --> END(["Exception Propagated"])
    RETURN --> END
```

**Processing Sequence:**

1. **Input Map Preparation (Edit In-Mapping):** The method delegates to `editInMsg` to construct a `HashMap<String, Object>` parameter map from the request parameter, service interface ID, function code, and service interface map data. This step translates raw input parameters into a flat key-value structure consumable by the service component runtime.

2. **Service Component Dispatch:** The prepared parameter map and session handle are passed to `scCall.run(paramMap, handle)`, which invokes the underlying service component identified by `svcIfId`.

3. **Result Extraction:** The raw return map is decomposed into three pieces:
   - The `CAANMsg[]` template array (retrieved via `JCMConstants.TEMPLATE_LIST_KEY`).
   - The integer return code (retrieved via `JCMConstants.RET_CD_INT_KEY`).
   - The status flag from `templates[0]` (via `JCMConstants.STATUS_INT_KEY`).

4. **Error Information Translation:** `editErrorInfo` is called to translate the service component's error state into the application's error-tracking map under the control parameter.

5. **Error List Initialization and Aggregation:** The existing error list is fetched from the control map. If absent, a new `ArrayList` is created. Then `TemplateErrorUtil.getErrorInfo` enriches the error list with details from the result map, and the updated list is stored back into the control map under `SCControlMapKeys.ERROR_INFO`.

6. **Status Validation:** The return code (as string) and status integer are evaluated. Only when **both** conditions are met — return code equals `"0"` **and** status equals `0` — does processing proceed. If either condition fails, an `SCCallException` is thrown with the literal Japanese error message "返回值不正" (meaning "Invalid Return Value" / "Return Value Incorrect"), along with the raw return code and status for diagnostic purposes.

7. **Return:** The first element of the template array (`templates[0]`) is returned to the caller as the structured business result.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `handle` | `SessionHandle` | Database session handle carrying the current transaction context, connection, and user session metadata. Used by the service component runtime to scope its database operations. |
| 2 | `param` | `IRequestParameterReadWrite` | Request parameter object carrying business input data (e.g., service contract numbers, customer identifiers) and control data (e.g., error lists, work maps). Modified in-place via `editInMsg`, `editErrorInfo`, and `setControlMapData`. |
| 3 | `scCall` | `ServiceComponentRequestInvoker` | The service component dispatcher instance. Acts as a generic executor that takes a parameter map and session handle and returns a result map containing CAANMsg templates, return codes, and status flags. |
| 4 | `svcIfId` | `String` | Service component interface identifier — a template ID string (e.g., `EKK0081A010`, `EKK0161B004`, `EKK2141B001`, `EKK0191A010`) that identifies which service component schema to use for deserialization of the result. |
| 5 | `funcCode` | `String` | Function code passed through to `editInMsg` — used to categorize or route the mapping logic. In practice, callers pass `"1"` or `"2"` to distinguish between different service invocation modes. |
| 6 | `svcIfMapData` | `Object[][]` | Two-dimensional array of input key-value pairs passed to the service component. Each row is an `{ key, value }` tuple where the key is a field name constant and the value is the field value. Defines the business data payload of the service call. |

**External state / instance fields read:** None. This method is stateless — it reads no instance fields from `JKKSmtvlYoSanshoFukaInfCC`.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `ServiceComponentRequestInvoker.run` | (dynamic per svcIfId) | - | Dispatches to the service component identified by `svcIfId` (e.g., EKK0081A010, EKK0161B004, etc.) |
| U | `JKKSmtvlYoSanshoFukaInfCC.editErrorInfo` | - | - | Translates the service component's return status into the application's error-tracking control map |
| U | `JKKSmtvlYoSanshoFukaInfCC.editInMsg` | - | - | Prepares the input parameter map from raw parameters, service interface ID, function code, and map data |
| R | `TemplateErrorUtil.getErrorInfo` | - | - | Extracts enriched error information from the result map and appends it to the error list |
| R | `SCControlMapKeys.ERROR_INFO` access | - | - | Reads and writes error list control data in the request parameter's control map |

**CRUD Analysis:**

This method does **not** directly perform C/R/U/D operations against database tables. Instead, it acts as an **orchestration wrapper** around a dynamically selected service component (`scCall.run()`). The actual CRUD operations against database tables are internal to the invoked service component (e.g., `EKK0081A010CBS`, `EKK0161B004CBS`, `EKK2141B001CBS`, `EKK0191A010CBS`), not visible within the `callSC` method itself. The method's own CRUD footprint consists of **2 Update (U) operations** — writing to `param` via `editInMsg` and `editErrorInfo` — and **2 Read (R) operations** — extracting from the `result` map and calling `getErrorInfo`.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| U | `editInMsg` | - | - | Prepares input parameter map for the service component call |
| R | `scCall.run` | (dynamic per svcIfId) | (internal to called SC) | Dispatches service component; actual table operations are opaque to this method |
| U | `editErrorInfo` | - | - | Populates error tracking data in the request parameter control map |
| R | `getErrorInfo` | - | - | Reads error detail from the service component result map |
| U | `param.setControlMapData` | - | - | Writes aggregated error list back to the request parameter |
| R | `result.get` (TEMPLATE_LIST_KEY, RET_CD_INT_KEY) | - | - | Extracts return code and template array from the service result map |
| R | `templates[0].getInt` (STATUS_INT_KEY) | - | - | Reads status code from the first result template |

## 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: `run` [-], `editErrorInfo` [U], `getErrorInfo` [R], `setControlMapData` [U], `editInMsg` [U]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS:JKKSmtvlYoSanshoFukaInfCC.getSmtvlYoSanshoFukaInf | `getSmtvlYoSanshoFukaInf` -> `callSC` (EKK2141B001, EKK0191A010) | `scCall.run` [R] (dynamic SC); `editErrorInfo` [U]; `editInMsg` [U] |
| 2 | CBS:JKKSmtvlYoSanshoFukaInfCC.getSvcKeiNoToTelSvc | `getSvcKeiNoToTelSvc` -> `callSC` (EKK0081A010) | `scCall.run` [R] (dynamic SC); `editErrorInfo` [U]; `editInMsg` [U] |

**Call Chain Details:**

- **`getSmtvlYoSanshoFukaInf`** — The public entry point that retrieves supplementary service information for Smart BSS reference. It first calls `getSvcKeiNoToTelSvc` to obtain the service contract number, then issues multiple `callSC` invocations: one for `EKK2141B001` (Old ICS code conversion reference) and one for `EKK0191A010` (Service contract details — eo optical telephone agreement). Each call routes through `callSC`.

- **`getSvcKeiNoToTelSvc`** — Retrieves the telephone service contract number. It issues a single `callSC` invocation for `EKK0081A010` (Service contract agreement search). This method is itself called by `getSmtvlYoSanshoFukaInf`, forming a nested call chain.

## 6. Per-Branch Detail Blocks

**Block 1** — [SET / EXEC] `(Input Map Preparation)` (L398-400)

> Creates the input parameter map by delegating to `editInMsg`.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `editInMsg(param, svcIfId, funcCode, svcIfMapData)` |
| 2 | SET | `paramMap = editInMsg(...)` // HashMap<String, Object> for SC input |

**Block 2** — [EXEC] `(Service Component Dispatch)` (L402)

> Invokes the service component runtime with the prepared parameter map and session handle.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `scCall.run(paramMap, handle)` |
| 2 | SET | `result = scCall.run(...)` // Map<?, ?> containing templates, return code, status |

**Block 3** — [SET] `(Result Extraction — Templates)` (L404)

> Extracts the `CAANMsg[]` array from the result map using the template list key constant.

| # | Type | Code |
|---|------|------|
| 1 | SET | `templates = (CAANMsg[])result.get(JCMConstants.TEMPLATE_LIST_KEY)` // Template list array |

**Block 4** — [SET] `(Result Extraction — Return Code)` (L407-408)

> Extracts the integer return code and converts it to a string for comparison.

| # | Type | Code |
|---|------|------|
| 1 | SET | `rtnCode = result.get(JCMConstants.RET_CD_INT_KEY).toString()` // Return code as String |

**Block 5** — [EXEC] `(Error Information Translation)` (L411)

> Translates the service component's error state into the application's error tracking structure.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `editErrorInfo(param, templates, (Integer)result.get(JCMConstants.RET_CD_INT_KEY))` |

**Block 6** — [SET / EXEC] `(Error List Retrieval)` (L414-419)

> Fetches existing error list from the control map; initializes if absent.

| # | Type | Code |
|---|------|------|
| 1 | SET | `errList = (ArrayList<Object>)param.getControlMapData(SCControlMapKeys.ERROR_INFO)` |
| 2 | IF | `errList == null` |
| 2.1 | [Block 6.1] — [SET] `(null branch — L416)` |
| | 1 | SET | `errList = new ArrayList<Object>()` // Initialize empty error list |

**Block 7** — [EXEC] `(Error List Aggregation and Storage)` (L421)

> Enriches the error list with detail from the service result and stores it back.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `TemplateErrorUtil.getErrorInfo(result, errList)` // Enriches error list with result details |
| 2 | EXEC | `param.setControlMapData(SCControlMapKeys.ERROR_INFO, ...)` // Stores updated error list |

**Block 8** — [SET] `(Status Extraction)` (L423)

> Reads the status code from the first template in the result array.

| # | Type | Code |
|---|------|------|
| 1 | SET | `status = templates[0].getInt(JCMConstants.STATUS_INT_KEY)` // Status code from first template |

**Block 9** — [IF-ELSE] `(Error Condition Check — L425)`

> Validates that the service component returned success: both return code must be `"0"` and status must be `0`.
> Condition: `!("0".equals(rtnCode) && 0 == status)`

| # | Type | Code |
|---|------|------|
| 1 | IF | `!("0".equals(rtnCode) && 0 == status)` |
| 1.1 | [Block 9.1] — [THROW] `(Error branch — L427)` |
| | 1 | THROW | `throw new SCCallException("返回值不正", rtnCode, status)` // Throws on non-success: returns invalid value |

**Block 10** — [RETURN] `(Success Return — L432)`

> Returns the first template from the result as the business result object.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return ((CAANMsg[])result.get(JCMConstants.TEMPLATE_LIST_KEY))[0]` // First CAANMsg template |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `callSC` | Method | Service Component call — generic dispatcher that wraps the full lifecycle of calling a downstream service component |
| `svcIfId` | Field | Service Interface ID — template identifier string (e.g., `EKK0081A010`) identifying the service component schema to use |
| `funcCode` | Field | Function code — routing code passed to the input mapping logic to distinguish invocation modes |
| `svcIfMapData` | Field | Service Interface Map Data — two-dimensional array of input key-value pairs defining the service call payload |
| `TEMPLATE_LIST_KEY` | Constant | Key for extracting the `CAANMsg[]` result array from the service component response map |
| `RET_CD_INT_KEY` | Constant | Key for extracting the integer return code from the service component response map |
| `STATUS_INT_KEY` | Constant | Key for extracting the status code from a `CAANMsg` template |
| `ERROR_INFO` | Constant | Control map key under which error detail lists are stored in the request parameter |
| `editInMsg` | Method | Edit In-Mapping — prepares the input parameter map from raw request parameters |
| `editErrorInfo` | Method | Error info translation — converts the service component's return state into application error tracking data |
| `getErrorInfo` | Method | `TemplateErrorUtil.getErrorInfo` — extracts enriched error information from the result map |
| `SCCallException` | Class | Service Component Call Exception — thrown when the service component returns a non-success return code or status |
| `CAANMsg` | Class | Custom message object — structured result wrapper carrying typed field accessors for service component responses |
| `SessionHandle` | Class | Database session handle — carries transaction context, connection, and user session for service component operations |
| `IRequestParameterReadWrite` | Interface | Request parameter interface — provides access to business data and control data for a service invocation |
| `ServiceComponentRequestInvoker` | Class | Service component dispatcher — executes service components with parameter maps and session handles |
| Smart BSS | Business term | Smart Business Support System — Fujitsu's telecom business support platform |
| K-Opticom | Business term | Japanese telecommunications service provider; the system being documented serves K-Opticom's operations |
| EKK0081A010 | SC Code | Service Contract Agreement Search — retrieves service contract details by service contract number |
| EKK0161B004 | SC Code | Service Contract Details List Reference — retrieves list of service contract line items |
| EKK0191A010 | SC Code | Service Contract Details — eo Optical Telephone Agreement — retrieves detailed service contract information for eo optical telephone |
| EKK2141B001 | SC Code | Old ICS Code Conversion Reference — converts legacy ICS (Internal Contract System) codes to current format |
| EKK0241B002 | SC Code | Supplementary Service Information (template ID reference) |
| EKK0241B003 | SC Code | Supplementary Service Information (template ID reference) |
| KKSV065102CC | Constant | Service ID constant identifying the Smart BSS screen/context that consumes this component |
| 返回值不正 | Japanese string | "Invalid Return Value" — literal error message thrown when return code or status is non-success |
| SOD | Acronym | Service Order Data — telecom order fulfillment entity |
| ICS | Acronym | Internal Contract System — legacy contract management system; EKK2141B001 handles migration of its codes |