# Eo / Web / Webview / Kka440sf

## Overview

The `KKA440SF` package provides the view-layer business logic for the **KDDI-facing Subscriber Information Reference API**. It is the web-side entry point that receives subscriber lookup requests (by name, phone number, application number, etc.), validates inputs, and delegates to the `KKSV0637` backend service to retrieve subscriber data. The module formats responses as serialized message strings (common sector + simple sector) for the calling integration layer.

A new team member should understand this module's role immediately: it is the bridge between external KDDI API consumers and the internal subscriber lookup service. When a partner system calls the subscriber lookup endpoint, `KKA440SFLogic.init()` orchestrates the entire flow — validation, service invocation, error handling, and response serialization.

## Key Classes and Interfaces

### [KKA440SFBean](source/koptWebA/src/eo/web/webview/KKA440SF/KKA440SFBean.java)

The data bean for this screen/API. It extends `X33VViewBaseBean` and implements `X33VListedBeanInterface` and `X31CBaseBean`, making it the standard data carrier pattern for the X31/X33 web framework.

#### Purpose and Role

The bean stores the API's response message data and provides the framework with metadata about its data model (types, property lists). Unlike typical screen beans that manage many fields, this bean is notably lean — it carries just four response message properties:

- **`rsp_msg_update`** (`String`) — flags whether a message update occurred
- **`rsp_msg_value`** (`String`) — the serialized response message content
- **`rsp_msg_enabled`** (`Boolean`) — whether the message is enabled/active
- **`rsp_msg_state`** (`String`) — status/state indicator for the message

#### Key Methods

**`loadModelData(String key, String subkey)`** (lines 112-163)

Retrieves data from the bean using a key/subkey addressing scheme. The key system supports several patterns:
- Simple property keys (e.g., `"応答電文"` with subkey `"value"`)
- Root index notation (e.g., `"ItemA/0/ItemB"`) for repeated items
- Common info bean prefixes (keys starting with `//`)

For the response message, it dispatches to `getRsp_msg_value()`, `getRsp_msg_enabled()`, or `getRsp_msg_state()` based on the subkey. If the key is null, it returns null. If the subkey is null, it normalizes to an empty string.

**`storeModelData(String key, String subkey, Object in_value, boolean isSetAsString)`** (lines 196-239)

The write counterpart to `loadModelData`. Stores data using the same key/subkey scheme, dispatching to `setRsp_msg_value()`, `setRsp_msg_enabled()`, or `setRsp_msg_state()`. The `isSetAsString` parameter controls whether Long-type properties should accept string values.

**`typeModelData(String key, String subkey)`** (lines 292-345)

Returns the Java type for a given key/subkey, enabling the framework to properly serialize/deserialize data. For the response message, it returns `String.class` for value and state, and `Boolean.class` for enabled. This is essential for the framework's type-aware data binding.

**`listKoumokuIds(String key)`** (lines 254-270)

Returns a list of property names for this bean. When called with no key, it returns the single property `"応答電文"` (response message). This feeds the framework's introspection for form generation.

**`listServiceFormIds()`** (lines 245-247)

Returns `null`, indicating no named service forms are defined. This is a no-op placeholder inherited from the framework template.

#### Relationship to Other Classes

- Referenced by `KKA440001PJP.jsp` (1 JSP view) and `WEBGAMEN_KKA440001PJP.xml` (1 XML config)
- Consumed by `KKA440SFLogic` via `getServiceFormBean()` to write response data

---

### [KKA440SFLogic](source/koptWebA/src/eo/web/webview/KKA440SF/KKA440SFLogic.java)

The core business logic class for this module. It extends `JCCWebBusinessLogic` and is the heart of the subscriber information lookup API.

#### Purpose and Role

This class handles the complete lifecycle of a subscriber lookup request:

1. **Business restriction check** — verifies the system isn't in maintenance mode
2. **Parameter extraction** — reads 7+ input fields from the request
3. **Input validation** — checks required fields, length constraints, and numeric format
4. **Service invocation** — calls the `KKSV0637` backend service with properly mapped parameters
5. **Response handling** — parses results, handles errors with specific error codes, and serializes the response

#### Key Methods

**`init()`** (lines 196-558)

The main entry point. This method executes the full subscriber lookup workflow:

1. **Service restriction check**: Calls `JKKApiCommon.checkRequestRestriction()` to verify the system isn't under business restriction (e.g., maintenance). If restricted, returns an error with result code `007001` ("business restriction error").

2. **Parameter extraction**: Reads the following fields from the request map:
   | Field | Description |
   |-------|-------------|
   | `KIYKSHA_MI` | Subscriber name (kanji), max 45 chars |
   | `KIYKSHA_MI_KN` | Subscriber name (kana), max 120 chars |
   | `HUZN_KIYK_CHEK` | Legal entity contract check (must be "0" or "1") |
   | `DNW_BNGU` | eo light phone number, max 11 chars, numeric |
   | `MUSKM_BNGU` | Application number, max 10 chars |
   | `RNRKSK_BNGU` | Contact phone number, max 11 chars, numeric |
   | `SINNGP` | Date of birth, max 8 chars, numeric |
   | `TNMT_STBSHO_JUSHO` | Service location address, max 100 chars |

3. **Character conversion**: Applies `JKKApiCommon.charConverter()` to all request parameters (v4.00.03 fix) and converts nulls to blanks (v4.00.01 fix).

4. **Required field validation**:
   - Either `KIYKSHA_MI` (kanji name) OR `KIYKSHA_MI_KN` (kana name) must be present. If neither is set, returns error code `009008` ("required item not set") with status `1010`.
   - At least one of `DNW_BNGU`, `MUSKM_BNGU`, `RNRKSK_BNGU`, or `SINNGP` must be present. If all are empty, returns error code `009008` with status `1020`.

5. **Field-level validation**:
   - `HUZN_KIYK_CHEK` must be "0" or "1". Invalid values return error `009008` with status `1030`.
   - Each field is validated for max length using `isMaxLength()`.
   - Phone numbers and date of birth (`DNW_BNGU`, `RNRKSK_BNGU`, `SINNGP`) must be purely numeric per `isNumber()`.

6. **Service invocation**: Builds a parameter map with use-case ID `KKSV0637`, uses `KKSV0637_KKSV0637OPDBMapper` to map request fields to the service input, invokes the service via `invokeService()`, and captures the output.

7. **Response processing**:
   - On success (result code `000000`): Maps the service output to the simple sector map and writes the serialized response (converted to Shift-JIS encoding per v4.00.02) to the bean.
   - On service error: Logs the error, extracts message info, sets response status to `0` and returns error code `000000` with the simple sector.
   - On fatal exception: Sets response status `9100` and returns the fatal error sector.

**`initSimpleSectorMap()`** (lines 564-577)

Initializes a HashMap for the simple (compact) response sector. Pre-populates all 104 response parameter slots (`PRMT1` through `PRMT100`, plus `KNSK_UKTK_BNGU`, `KNRYO_CD`, `SHOSI_CD`, `NETKNSU`) with empty strings. This map is then populated with actual data or error placeholders before serialization.

**`isMaxLength(String value, String itemNm, int length)`** (lines 587-623)

Validates that a string value does not exceed a maximum length. If the check fails, it builds and sends an error response with result code `009010` ("max length check error") containing the item name and the offending value. Returns `true` for pass, `false` for fail.

**`isNumber(String value, String itemNm)`** (lines 632-673)

Validates that a string value contains only digits. If the value is null or empty, it passes (returns `true`). If non-numeric content is found, it builds and sends an error response with result code `009009` ("number check error"). Returns `true` for pass, `false` for fail.

#### Design Decisions

- **Error code convention**: The module uses a consistent error code pattern — `007001` for business restrictions, `009003` for fatal errors, `009008` for required field errors, `009009` for numeric format errors, and `009010` for length limit errors.
- **Response format**: Responses are always serialized as a concatenation of a common sector (metadata, error codes, system info) and a simple sector (data fields or error placeholders). This follows the KDDI API contract.
- **Character encoding**: The v4.00.02 fix introduces Shift-JIS conversion for the response message, indicating the downstream system expects this encoding.
- **Fail-fast validation**: All validation happens before any service call, avoiding unnecessary remote calls with invalid input.
- **Error responses still return `true`**: The `init()` method always returns `true` (indicating the method completed), with actual success/failure communicated through the serialized response message and result codes.

---

### [KKA440SFChecker](source/koptWebA/src/eo/web/webview/KKA440SF/KKA440SFChecker.java)

The GUI check handler for this module. It implements `X31SGuiCheckBase`.

#### Purpose and Role

This class is a placeholder for client-side GUI validation rules. It receives a business logic reference in its constructor and implements the `checkMethod()` interface. Currently, the method body simply returns `true`, meaning no GUI-level validation is performed.

The class exists because the X31 framework expects every business logic module to have a corresponding checker that can handle screen-level validation patterns. Any future GUI-side validation rules (e.g., "field X must be filled when field Y is set") would be added here.

---

### [KKA440SFConst](source/koptWebA/src/eo/web/webview/KKA440SF/KKA440SFConst.java)

A constant holder class for the module. It follows the standard pattern of having a private constructor to prevent instantiation and exposing static final constants.

#### Constants

| Constant | Value | Purpose |
|----------|-------|---------|
| `RSP_MSG` | `"応答電文"` | The key used to identify the response message field in the bean's key/subkey model |

This constant is used throughout `KKA440SFBean` and `KKA440SFLogic` as the key for accessing and storing the serialized response message.

## How It Works

### Request Flow

```mermaid
flowchart TD
    subgraph KKA440SF["KKA440SF Module"]
        direction TB
        JSP["KKA440001PJP.jsp"]
        XML["WEBGAMEN_KKA440001PJP.xml / x31business_logic_KKA440SF.xml"]
        BEAN["KKA440SFBean<br/>X33VViewBaseBean<br/>X31CBaseBean"]
        LOGIC["KKA440SFLogic<br/>JCCWebBusinessLogic"]
        CHECKER["KKA440SFChecker<br/>X31SGuiCheckBase"]
        CONST["KKA440SFConst<br/>RSP_MSG = '応答電文'"]
    end

    XML --> BEAN
    XML --> LOGIC
    JSP --> BEAN
    BEAN --> LOGIC
    LOGIC --> CONST

    subgraph Framework["X31/X33 Framework"]
        X31["X31CBaseBean<br/>X31SDataBeanAccess"]
        X33["X33VViewBaseBean<br/>X33VListedBeanInterface"]
    end

    BEAN --> X31
    BEAN --> X33

    subgraph External["External Services"]
        SVC["KKSV0637 Service<br/>Service Invoke"]
        MAPPER["KKSV0637_KKSV0637OPDBMapper"]
    end

    LOGIC --> SVC
    LOGIC --> MAPPER
```

### Step-by-Step Request Flow

When a KDDI partner system calls the subscriber lookup API:

1. **Framework dispatch**: The XML config (`WEBGAMEN_KKA440001PJP.xml`) routes the request to `KKA440SFLogic`. A `KKA440SFBean` instance is created to hold the response.

2. **Restriction check**: `KKA440SFLogic.init()` first calls `JKKApiCommon.checkRequestRestriction()`. If the system is in maintenance mode, it immediately constructs an error response with code `007001` and returns.

3. **Parameter preparation**: Request parameters are extracted, converted via `JKKApiCommon.charConverter()`, and null values are replaced with blank strings.

4. **Validation pipeline**: The logic layer validates inputs in order:
   - Name fields (`KIYKSHA_MI` or `KIYKSHA_MI_KN`) — at least one required
   - Legal entity check — must be "0" or "1"
   - Search fields (`DNW_BNGU`, `MUSKM_BNGU`, `RNRKSK_BNGU`, `SINNGP`) — at least one required
   - Length limits — each field checked against its max
   - Numeric format — phone numbers and DOB must be digits only
   Any validation failure constructs an appropriate error response and returns early.

5. **Service call**: On passing validation, the mapper (`KKSV0637_KKSV0637OPDBMapper`) transforms the input fields into the service's expected format via `setKKSV063701CC()`. The service is invoked via `invokeService()` with use-case ID `KKSV0637`.

6. **Response serialization**:
   - On success (`result_cd == "000000"`): The mapper extracts results via `getKKSV063701CC()`, populates the simple sector map, and the response is converted to Shift-JIS encoding before being stored in the bean.
   - On service error: A simplified error response is built with the common sector and the simple sector (with empty data fields).
   - On fatal error: Status `9100` is set with a fatal error sector.

7. **Response delivery**: The bean's `rsp_msg_value` field contains the complete serialized response, which the framework serializes back to the caller.

### Error Code Reference

| Code | Meaning | When |
|------|---------|------|
| `000000` | Success | Service returned successfully |
| `007001` | Business restriction | System in maintenance mode |
| `009003` | Fatal error | Unexpected exception during processing |
| `009008` | Required item not set | Name fields missing OR all search fields empty |
| `009009` | Number check error | Phone number or DOB contains non-numeric chars |
| `009010` | Max length error | Any field exceeds its character limit |

## Data Model

### Response Message Properties (KKA440SFBean)

The bean carries a single logical concept — the response message — split into four sub-properties accessed via the key/subkey model:

| Key | Subkey | Java Type | Purpose |
|-----|--------|-----------|---------|
| `応答電文` | `value` | `String` | Serialized response content |
| `応答電文` | `enable` | `Boolean` | Whether the message is active |
| `応答電文` | `state` | `String` | Status/state indicator |
| `応答電文` | (empty) | `String` | Defaults to `value` |

### Request Parameters (Input to init())

| Field | Type | Max Len | Constraints | Description |
|-------|------|---------|-------------|-------------|
| `KIYKSHA_MI` | String | 45 | At least one of this or `KIYKSHA_MI_KN` required | Subscriber name (kanji) |
| `KIYKSHA_MI_KN` | String | 120 | At least one of this or `KIYKSHA_MI` required | Subscriber name (kana) |
| `HUZN_KIYK_CHEK` | String | 1 | Must be "0" or "1" | Legal entity contract flag |
| `DNW_BNGU` | String | 11 | Numeric | eo light phone number |
| `MUSKM_BNGU` | String | 10 | — | Application number |
| `RNRKSK_BNGU` | String | 11 | Numeric | Contact phone number |
| `SINNGP` | String | 8 | Numeric | Date of birth |
| `TNMT_STBSHO_JUSHO` | String | 100 | — | Service location address |

### Response Parameters (Output in Simple Sector)

The response contains up to 104 parameter slots (`PRMT1` through `PRMT100`) plus four special fields. Key response fields include:

| Index | Field | Description |
|-------|-------|-------------|
| [0] | `KNSK_UKTK_BNGU` | Search request number |
| [1] | `KNRYO_CD` | Completion code |
| [2] | `SHOSI_CD` | Detail code |
| [3] | `NETKNSU` | Number of net records found |
| [4] | `PRMT1` | Application number |
| [5] | `PRMT2` | Subscriber name (kanji) |
| [6] | `PRMT3` | Subscriber name (kana) |
| [7] | `PRMT4` | Date of birth |
| [10] | `PRMT7` | Customer phone number |
| [15] | `PRMT12` | Net smart contract status |
| [16] | `PRMT13` | Post-disconnection eo light smart eligibility |
| [21] | `PRMT18` | eo light 1 smart eligibility |
| [22] | `PRMT19` | eo light 1 application rejection reason |
| [32] | `PRMT28` | Disconnection service provider name |
| [23-26] | `PRMT20-23` | eo light 1-4 phone numbers |
| [29] | `PRMT25` | TW contract status |

## Dependencies and Integration

### Inbound Dependencies (what uses this module)

| Consumer | Type | What It Uses |
|----------|------|-------------|
| `KKA440001PJP.jsp` | JSP view | `KKA440SFBean` |
| `WEBGAMEN_KKA440001PJP.xml` | XML config | `KKA440SFBean`, `KKA440SFLogic` |
| `x31business_logic_KKA440SF.xml` | XML config | `KKA440SFLogic` |

### Outbound Dependencies (what this module uses)

| Dependency | Package | Purpose |
|------------|---------|---------|
| `JKKApiCommon` | `eo.web.webview.common` | API utilities (restriction check, character conversion, response serialization) |
| `JCCWebCommon` | `eo.web.webview.common` | Common utilities (e.g., `getOpeDate` for operation date) |
| `JCCWebBusinessLogic` | `eo.web.webview` | Parent class for web business logic |
| `KKSV0637_KKSV0637OPDBMapper` | `eo.web.webview.mapping` | Maps request/response fields for the KKSV0637 service |
| `JPCEditString` | `eo.common.util` | String utilities (e.g., zero-padding line numbers) |
| `X31SDataBeanAccess` | X31 framework | Service form bean access |
| `X31CWebConst` | X31 framework | Web framework constants |
| `X33VViewBaseBean` | X33 framework | Parent bean class |
| `eo.business.service` | Business layer | Service invocation |
| `eo.ejb.common` | EJB common | Enterprise JAR utilities |

### Key Framework Relationships

The module is built on the Fujitsu Futurity X31/X33 web framework. The bean (`KKA440SFBean`) implements both `X33VViewBaseBean` (for view data management) and `X31CBaseBean` (for business bean interfacing). The logic (`KKA440SFLogic`) extends `JCCWebBusinessLogic`, which in turn extends the X31 business logic base class.

Service invocation happens through the framework's `invokeService()` method, passing a use-case ID (`KKSV0637`) and parameter maps. The mapper class handles the field translation between the web API's field naming convention and the service's internal format.

## Notes for Developers

### Character Encoding Gotcha

The v4.00.02 fix introduced Shift-JIS encoding for the response message. The response is converted via `JKKApiCommon.charConverter(rspMsg.toString(), "Shift-JIS")` before being stored in the bean. If you're working with this response in tests or integration scenarios, ensure your test harness expects Shift-JIS encoding.

### Error Handling Pattern

All errors within `init()` are handled internally — the method returns `true` regardless of whether processing succeeded or failed. The actual result is communicated through the serialized response message and result codes embedded in it. This is by design: from the web framework's perspective, the method "completed" even if the business result was an error.

The response always contains two parts concatenated:
1. **Common sector** — system metadata (error code, class name, line number, business logic name, component name)
2. **Simple sector** — actual data fields or error placeholders

### Validation Is Client-Facing

The `KKA440SFChecker` exists but has no validation logic implemented (its `checkMethod` always returns `true`). If GUI-side validation rules need to be added (for web UI consumers of this API), they should be implemented in this class. However, the primary validation happens server-side in `KKA440SFLogic.init()`.

### Response Parameter Indexing

The response parameter arrays in `KKA440SFLogic` are indexed by position (array index 0 = `KNSK_UKTK_BNGU`, array index 1 = `KNRYO_CD`, etc.) while the simple sector map uses field names (`PRMT1`, `PRMT2`, etc.). The comments in the source document the mapping between indices and field names. Be careful not to add or reorder entries in the `KEY_RES_PARAM_NM` array without updating all related code.

### Extending This Module

To add a new search criterion to the subscriber lookup:
1. Add the new field name to the `KEY_REQ_PARAM_NM` array
2. Extract the field from `reqMap` in `init()`
3. Add length/numeric validation calls as appropriate
4. Add the field mapping to the `KKSV0637_KKSV0637OPDBMapper`
5. If the service returns new data, add the field to `KEY_RES_PARAM_NM`

### Version History Highlights

- **v4.00.01**: Added comprehensive input validation for required fields and the legal entity contract check
- **v4.00.02**: Introduced Shift-JIS character conversion for response serialization
- **v4.00.03**: Added character conversion for all request parameters
- **v39.00.00**: Added support for eo light equipment removal (service start response)