# KKW05601SFLogic ## Purpose `KKW05601SFLogic` is the central business logic controller for the **telephone number porting and call forwarding registration** workflow in the JCC web platform. It orchestrates the full lifecycle of configuring *toki* (転送設定 — call-forwarding settings) for customer telephone lines, including initial screen display, user confirmation, and final registration. This class is one of the most important types in the system because it sits at the intersection of multiple screens, service inquiry APIs, and customer contract state management. ## Design `KKW05601SFLogic` extends `JCCWebBusinessLogic` and functions as a **screen-action controller** in a presentation-tier MVC pattern. It implements the full screen flow for call-forwarding configuration across screens `KKW05601` through `KKW05605`, coordinating with the backend service `KKSV0170` (inquiry) and `KKSV0171` (registration/acceptance). The class uses a facade-like approach: it consolidates multiple database queries (customer info, service contracts, phone reservations, code lookups, address changes, work order status) into a single cohesive initialization routine, then drives the user through a multi-step confirmation flow before committing changes to the backend. The business logic is tightly coupled to the web framework's `X31SDataBeanAccess` data model, operating on bean arrays and data bean access objects rather than domain entities. This is consistent with the broader JCC architecture where business logic classes manipulate screen-bound data beans directly. ## Key Methods ### `actionInit()` → `boolean` [Lines 183–233] **The primary entry point** for the class. Invoked when the screen is first loaded. Routes to one of two initialization routines based on the destination screen ID and `idoDiv` (disruption/diversion category): - If the target is screen `KKW05601` (the main registration screen), it calls `actionTokiAddInit()`, which performs full screen initialization including service inquiries, status checks, and populating display fields. - If the target is screen `KKW05603` (confirmation) and `idoDiv` is null/empty, it calls `actionTokiCfmInit()`, which loads existing data from the database for the confirmation display. Returns `false` if any initialization check fails (e.g., contract status prohibits the action, phone status is invalid), potentially redirecting back to the previous screen with error information set via `setErrorHktgInfo()`. ### `actionTokiAddInit()` → `boolean` [Lines 241–413] **Core initialization for the registration screen.** This is the most comprehensive method in the class. It: 1. Extracts system ID, service contract number, service contract detail number, and `idoDiv` from the inherited item bean. 2. Calls `invokeServiceKKSV0170()` to perform a bulk inquiry (22+ sub-services) against the backend, retrieving customer details, service contract status, phone reservations, code lookups, address change information, work order status, and phone number status judgment. 3. Runs three sequential validation checks: - **`initDispCheck()`** — verifies the service contract is active (status `100` = service ongoing) or terminated (status `910`), or in pause with appropriate pause stop codes. If not, displays an error and returns false. - **`initTelnoStatCheck()`** — checks for port-out/pending status. If a port-out is active, blocks navigation and displays an error. - **`initAddressChangeCheck()`** — only when `idoDiv` is `00046` (phone/porting settings), verifies address change and work order statuses don't conflict. 4. Populates the screen bean with: the target phone number, contract status code, display pattern (1–4 depending on context), phone type, forwarding registration category, start/end dates, previous phone number, contact phone number, reserved phone number pull-down list, and forwarding content text. ### `setRsvTelNoPullDownList()` → `void` [Lines 425–453] Sets up the reserved phone number pull-down list. Only activates when `idoDiv` equals `00019` (from address change screen). Builds a prioritized list of phone numbers based on DN (Direct Number) channel — if DN1, it puts `itnsTel1` first; if DN2, it puts `itnsTel2` first. Each number is added only if it differs from the forwarding target number. The final list is passed to the mapper with a leading blank option enabled. ### `initDispCheck()` → `boolean` [Lines 477–510] Validates that the user can proceed to the main screen based on **service contract status**. Extracts `svcKeiUcwStatus` (service contract detail status) and `pauseStpCd` (pause stop code). Delegates to `isInitDispOk()` for the decision logic. If blocked, sets error message `EKB940_JW` with message values "電話番号" (phone number) and "契約状態" (contract status), and determines the return screen. ### `isInitDispOk()` → `Boolean` [Lines 519–537] The contract status decision method. Navigation is allowed (`true`) when: - Status `100` — service is currently being provided, OR - Status `910` — contract has been terminated, OR - Status `210` (pause) with pause stop code `00` or `01` (pause in progress, SOD not issued / SOD issued) Any other status combination blocks navigation. ### `initTelnoStatCheck()` → `boolean` [Lines 546–574] Checks phone number status (port-out status) during **initial screen display**. Reads `telnoJudgeDiv` and `portOutStatUm` from the `TELNOSTATJUDGECC` data bean array. Delegates to `isInitTelnoStatCheck()` for the decision. If blocked, sets error and redirects to the previous screen. Also handles errors from phone number lookup (e.g., master data not found via `TELNO_SEARCH_ERRFLG`). ### `isInitTelnoStatCheck()` → `Boolean` [Lines 607–643] Phone number status decision method. Navigation is blocked if: - `TELNO_SEARCH_ERRFLG` equals `"0"` — phone number master data not found, OR - `portOutStatUm` equals `"1"` — port-out status exists (port-out/pending) Otherwise, navigation is allowed (the phone number is available for call forwarding setup). ### `initAddressChangeCheck()` → `boolean` [Lines 652–671] Validates navigation when coming from an address change screen (`idoDiv = 00046`). Delegates to `isInitAddressChangeChangeOk()` using `kojiAnkState` (work order status), `mansKojiAkStatCd` (managing work order status code), and `adchgStat` (address change status). If the address change workflow is in a conflicting state (e.g., ongoing relocation construction completed before contract), displays error `EKB0760_NW` and blocks navigation. ### `actionTokiCfmInit()` → `boolean` [Lines 708–811] Initialization for the **contract mode confirmation screen**. Called when the user arrives from the inquiry screen rather than the registration screen. Extracts the same inherited items as `actionTokiAddInit()`, invokes `invokeServiceKKSV0170()`, then calls `setTokiInfoFromDB()` in mode `1` to populate the bean with existing forwarding data from the database. Displays the confirmation screen with pre-filled data. ### `actionCfm()` → `boolean` [Lines 819–958] **Registered confirm button handler.** The most important user-action method. Collects all user-edited fields from the service form bean: forwarding target phone number, forwarding registration category code, forwarding type code, forward/no-forward flag, start date, end date, previous phone number, contact phone number, reserved phone number, and forwarding content. Sets these into the inherited item bean via `setCustKeiHktgiBean()`. Then branches based on `idoKbn`: - If `00019` (address change/registration), calls `actionCfmIdoKbn00019()`. - Otherwise, calls `actionCfmOtherIdoKbn()`. On success, displays the forwarding start timing message via `dispMessageTokiTiming()`. ### `actionCfmOtherIdoKbn()` → `boolean` [Lines 977–1173] Handles confirm processing for non-address-change scenarios. Sets up submission parameters including: - Submission type code `00027` - Operation date-time stamp - Consent status code (`SHONIN` — approved) - Forwarding registration category, forwarding type, forward/no-forward flag, start/end dates - Contact phone number and service contract detail number of the forwarding destination If the forwarding category is `1` (forwarding destination registration), it checks the service contract status of the forwarding destination. If the source is terminated (`910`) and destination is active (`100`), it sets the forwarding start date to the current operation date. Returns `true` on success. ### `actionTokiAddCfmInit()` → `boolean` [Lines 1192–1265] Initialization for the **forwarding registration confirmation screen**. Translates internal codes to display values using `getValueFromCd()` for forwarding registration category, forwarding type, and forward/no-forward flag. Sets start/end dates (formatted as `YYYY/MM/DD`) and reserved phone number. Displays a confirmation message if `idoDiv` is set. ### `actionCfmIdoKbn00019()` → `void` [Lines 1277–1328] Handles confirm processing when the disruption category is `00019` (address change/registration). Extracts inherited data, then sets forwarding destination service contract detail info, forwarding settings, forwarding phone number, forwarding destination service contract number, and forwarding destination status. Prepares the data for submission to the registration service. ### `actionBack()` → `boolean` [Lines 1339–1351] **Go back button handler.** Simple — sets the current screen ID as the next screen ID in the common info bean and returns. The framework handles the actual navigation. ### `actionOpenKKW05607()` → `boolean` [Lines 1358–1393] **Opens a child screen** (`KKW05607`) for contact phone number entry. Stores the current contact phone number in a map passed as screen info, sets the screen ID navigation (`KKW05607` → returns to `KKW05601`), and sets the next screen. ### `actionRetKKW05607()` → `boolean` [Lines 1399–1438] **Returns from the child screen** (`KKW05607`). Reads the result map to get whether the contact input was confirmed. Updates display fields for forwarding registration category, forwarding type, forward/no-forward flag, and reserved phone number. If the result was confirmed, sets the contact phone number from the child screen's result. ### `actionShusei()` → `boolean` [Lines 1448–1485] **Edit button handler.** Rewinds the user back to the registration screen (`KKW05601`) after updating the display text of pull-down selections using `getPullDownSelectCd()`. This allows the user to modify their entries. ### `actionFix()` → `boolean` [Lines 1493–1527] **Commit button handler.** The final action that actually registers the forwarding settings. Calls `invokeServiceKKSV0171()` with `FUNC_CODE_1` (registration/acceptance), which executes the full registration transaction (22+ sub-services including acceptance registration, service contract detail modification, submission detail confirmation, progress registration, SODCC, address change details, work order inquiry, phone number status judgment, and phone number update). After registration, displays a confirmation message and navigates to screen `KKW05605` (completion). ### `actionFin()` → `boolean` [Lines 1534–1554] **Completion button handler.** Sets the next screen to `KKW00130` (the master screen after all processing is done) and returns. ### `invokeServiceKKSV0170()` → `KKSV0170_KKSV0170OPDBMapper` [Lines 1647–1745] The **bulk inquiry service invocation** method. Sets up and executes a comprehensive service call for `KKSV0170` (forwarding registration initial display) with 22 sub-service mappings: | Sub-service | Purpose | |---|---| | `KKSV017001SC` | Customer inquiry | | `KKSV017002SC` | Service contract inquiry | | `KKSV017003SC` | Service contract detail inquiry | | `KKSV017004SC` | Service contract detail (eo optical phone) inquiry | | `KKSV017005SC` | Phone number reservation list inquiry | | `KKSV017006SC` | Code name management (forwarding registration code) | | `KKSV017007SC` | Code name management (forwarding type code) | | `KKSV017008SC` | Code name management (existence code) | | `KKSV017009SC` | Business parameter management (forwarding execution period) | | `KKSV017010SC` | Business parameter management (forwarding content — pause notice) | | `KKSV017011SC` | Business parameter management (forwarding content — number change notice) | | `KKSV017012SC` | Business parameter management (forwarding content — pause notice + contact) | | `KKSV017013SC` | Disruption reservation list inquiry | | `KKSV017014SC` | Service contract detail (eo optical phone) list (contract number) | | `KKSV017015SC` | Disruption reservation list (service contract detail number) | | `KKSV017016SC` | Phone number list (system ID) | | `KKSV017017SC` | Address change details list (pre-change ID number) | | `KKSV017018SC` | Address change inquiry | | `KKSV017019SC` | Address change details list | | `KKSV017020SC` | Service contract — work order list | | `KKSV017021SC` | Work order inquiry | | `TELNOSTATJUDGECC` | Phone number status judgment CC | | `KKSV017022SC` | Phone number inquiry | | `WORK` | Work data | This single service call consolidates all the data needed for the registration screen. ### `invokeServiceKKSV0171()` → `void` [Lines 2318–2384] The **registration service invocation** method. Called by `actionFix()` with `FUNC_CODE_1`. Executes the forward settings registration transaction with 13+ sub-services including acceptance registration, service contract detail modification, submission detail confirmation, progress registration, SODCC, address change details (when `idoDiv = 00019`), phone number status judgment, phone number update, and phone number inquiry. ### `getDispPattern()` → `String` [Lines 1747–1775] Determines the display pattern for the screen. Pattern `3` (pre-activation from relocation) or `4` (post-activation from relocation) based on the `itnMotoSakiFlg` flag. Pattern `1` is the default (normal forwarding setup). Pattern `9` means no display. The value may already be set by lower-level mapping and is returned as-is if present. ### `setTokiInfoFromDB()` → `void` [Lines 2723–2916] Populates the screen bean with existing forwarding data from the database. Reads the forwarding registration status (`getTokiAddCondtion()`), which returns one of: - `"1"` — only cancellation/pause forwarding registered - `"2"` — only forwarding destination forwarding registered - `"3"` — both registered - `"0"` — no forwarding set (in this case, returns early without displaying forwarding info) Then extracts the appropriate set of fields from the service contract detail bean (based on which forwarding is set), sets the phone numbers, dates, and forwarding content, and calls `actionTokiAddCfmInit()` to initialize the confirmation display. ### `getTokiAddCondtion()` → `String` [Lines 2927–2974] Determines the forwarding registration status by checking which forwarding (source cancellation/pause or destination registration) has data. Calls `isTokiAri()` for each, which checks if the registration category code is set AND the end date is not null/`20991231`. ### `setErrorHktgInfo()` → `void` [Lines 3055–3089] Sets inherited item data and error information to return to the previous screen when an error occurs during initialization. Called by `actionInit()` and other methods when navigation checks fail. The `errorKey` parameter (`"KEIYAKU_ERROR"`, `"DENWA_STAT_ERROR"`) determines what error context to pass back. ### `getSelectedCd()` → `String` [Lines 2218–2240] Retrieves the selected code from a pull-down list. Gets the index from the first sub-bean, and if null (indicating the pull-down might be disabled), falls back to the display initialization value. ### `getValueFromCd()` → `String` [Lines 2249–2280] Given a code value, searches through a code list and returns the display name associated with that code. Iterates through the list, comparing codes, and returns the name at the matching index. ### `getPullDownSelectCd()` → `String` [Lines 2290–2315] The inverse of `getValueFromCd()`. Given a display name, searches the code list and returns the associated code. Used when rewinding from a confirmation screen back to the input screen. ### `getCodeValue()` → `String` [Lines 3034–3048] Looks up a display name from code management master data. Iterates through a code list bean and returns the "コード区分名" (code distinction name) for the matching "コード区分" (code distinction). ### `getTikanStr()` → `String` [Lines 2446–2619] Generates the forwarding start timing message text. This is a complex method that considers the `idoDiv`, service contract status, forwarding registration category, address change status, and work order status to determine the correct message to display to the user. Messages include "登録完了" (registration complete) or "광電話の解約" (optical phone cancellation) depending on the combination of states. ## Relationships ```mermaid flowchart TD WebGAMEN["WEBGAMEN XML files
KKW056010, KKW056030, KKW056050"] --> |invoke| KKW05601SFLogic["KKW05601SFLogic"] x31business["x31business_logic
XML"] --> |references| KKW05601SFLogic KKW05601SFLogic --> |extends| JCCWebBusinessLogic["JCCWebBusinessLogic"] KKW05601SFLogic --> |uses| KKSV0170["KKSV0170_KKSV0170OPDBMapper
Inquiry service"] KKW05601SFLogic --> |uses| KKSV0171["KKSV0171_KKSV0171OPDBMapper
Registration service"] subgraph Screens ["Target Screens"] KKW05601["KKW05601 - Toki Registration Screen"] KKW05602["KKW05602 - Toki Edit Screen"] KKW05603["KKW05603 - Confirmation Screen"] KKW05604["KKW05604 - Toki Addition Screen"] KKW05605["KKW05605 - Completion Screen"] KKW05607["KKW05607 - Contact Input Screen"] end KKW05601SFLogic --> KKW05601 KKW05601SFLogic --> KKW05602 KKW05601SFLogic --> KKW05603 KKW05601SFLogic --> KKW05604 KKW05601SFLogic --> KKW05605 KKW05601SFLogic --> KKW05607 ``` ### Inbound Dependencies (4 classes) | Class | Relationship | |---|---| | `WEBGAMEN_KKW056010PJP.xml` | Invokes `KKW05601SFLogic` for the main registration screen | | `WEBGAMEN_KKW056030PJP.xml` | Invokes `KKW05601SFLogic` for the confirmation screen | | `WEBGAMEN_KKW056050PJP.xml` | Invokes `KKW05601SFLogic` for the completion screen | | `x31business_logic_KKW05601SF.xml` | Business logic configuration references | ### Outbound Dependencies | Class/Type | Relationship | |---|---| | `JCCWebBusinessLogic` | Parent class — provides common utilities like `getCommonInfoBean()`, `getServiceFormBean()`, `invokeService()`, and `dumpDatabean()` | | `KKSV0170_KKSV0170OPDBMapper` | Created internally for bulk inquiry | | `KKSV0171_KKSV0171OPDBMapper` | Created internally for registration | | `X31SDataBeanAccess` | Primary data type — used throughout for screen beans, inherited item beans, and code lookups | ### Screen Flow ```mermaid flowchart TD actionInit["actionInit
Entry point"] --> actionTokiAddInit["actionTokiAddInit
Registration screen init"] actionInit --> actionTokiCfmInit["actionTokiCfmInit
Confirmation screen init"] actionTokiAddInit --> initDispCheck["initDispCheck
Contract status check"] initDispCheck --> initTelnoStatCheck["initTelnoStatCheck
Phone status check"] initTelnoStatCheck --> initAddressChangeCheck["initAddressChangeCheck
Address change check"] actionTokiCfmInit --> setTokiInfoFromDB["setTokiInfoFromDB
Populate from DB"] initDispCheck --> actionCfm["actionCfm
Confirm button pressed"] initTelnoStatCheck --> actionCfm actionCfm --> actionCfmOtherIdoKbn["actionCfmOtherIdoKbn
Process non-address-change"] actionCfm --> actionCfmIdoKbn00019["actionCfmIdoKbn00019
Process address-change"] actionCfmOtherIdoKbn --> actionTokiAddCfmInit["actionTokiAddCfmInit
Confirmation screen init"] actionCfmIdoKbn00019 --> actionTokiAddCfmInit actionTokiAddCfmInit --> actionBack["actionBack
Go back"] actionTokiAddCfmInit --> actionFix["actionFix
Commit button pressed"] actionFix --> invokeServiceKKSV0171["invokeServiceKKSV0171
Register toki settings"] invokeServiceKKSV0171 --> actionFin["actionFin
Completion"] actionBack -.-> KKW05601["KKW05601 screen"] actionTokiAddCfmInit -.-> KKW05603["KKW05603 screen"] actionFin -.-> KKW00130["KKW00130 screen"] ``` ## Usage Example A typical call flow looks like this: 1. **User navigates to screen `KKW05601`** — the web framework (via XML config) calls `actionInit()`. 2. **`actionInit()` dispatches to `actionTokiAddInit()`** — the class performs a bulk inquiry via `invokeServiceKKSV0170()`, running all 22+ sub-service lookups in a single backend call. 3. **Validation checks run:** `initDispCheck()` (contract status), `initTelnoStatCheck()` (port-out status), and optionally `initAddressChangeCheck()` (address change conflict check). If all pass, the screen displays with pre-filled data. 4. **User edits the forwarding settings** (registration category, type, start/end dates, contact number) and presses **confirm**. 5. **`actionCfm()` collects and validates** the user's input, then branches based on `idoKbn`: - For address-change scenarios (`00019`), calls `actionCfmIdoKbn00019()`. - For normal scenarios, calls `actionCfmOtherIdoKbn()`. 6. **The confirmation screen initializes** via `actionTokiAddCfmInit()`, showing the user a summary of their selections. 7. **If the user presses commit**, `actionFix()` is called, which invokes `invokeServiceKKSV0171()` to register the forwarding settings to the backend. 8. **Upon success**, the user is navigated to screen `KKW05605` (completion) via `actionFin()`, which then routes to the master screen `KKW00130`. ## Notes for Developers ### Thread Safety The class is **not thread-safe**. It maintains an instance field `TELNO_SEARCH_ERRFLG` (line 118) that is set during `invokeServiceKKSV0170()` and read during `isInitTelnoStatCheck()`. This field is shared across the class instance and should be treated as request-scoped. In the JCC framework, a new instance is likely created per HTTP request, but this is not guaranteed by the class design. ### Error Handling - `actionInit()` and `actionTokiAddInit()` return `false` (not `true`) when initialization checks fail, allowing the caller to decide the navigation behavior. - Error redirection uses `setErrorHktgInfo()` to pass error context back through the inherited item bean to the previous screen. - The `TELNO_SEARCH_ERRFLG` field provides a mechanism to pass search error state between methods that don't share direct call chains. ### Screen Navigation The class uses `setNextScreen()` to set both the next screen ID and screen name in the common info bean. The framework uses these values to determine where to redirect after the action method completes. Screen IDs like `KKW05601`, `KKW05603`, `KKW05605`, `KKW05607`, and `KKW00130` are referenced via `JKKScreenConst` constants. ### Data Model All data manipulation occurs through `X31SDataBeanAccess` objects — there are no domain entities or DTOs. The class treats beans as both input and output, reading fields via `sendMessageString()`/`sendMessage()` and writing via `sendMessageString(..., SET_VALUE)`. Inherited items use `X31SDataBeanAccessArray` accessed via `getDataBeanArray()`. ### Constant Conventions The class uses both self-defined constants and framework-level constants (`KKW05601SFConst`, `JKKCommonConst`, `X31CWebConst`, `JPCOnlineMessageConstant`). Message codes (e.g., `EKB0370__I`, `EKBF990_KW`, `EKB0300_KW`) map to Japanese-language user-facing error and info messages. ### Forwarding Status Codes The forwarding registration status (`TokiAddCond`) can be one of: - `"1"` — Only cancellation/pause forwarding is registered - `"2"` — Only forwarding destination forwarding is registered - `"3"` — Both are registered - `"0"` — No forwarding is set The status is determined by checking whether the forwarding category code is set AND the end date is not null or `20991231` (a sentinel "no end date" value). ### Service Invocation Pattern The class follows a consistent pattern for backend service calls: 1. Create `paramMap`, `inputMap`, `outputMap` HashMaps. 2. Create the appropriate mapper instance. 3. Call `mapper.setXXX(paramBean, inputMap, funcCode)` for each sub-service to populate input. 4. Call `invokeService(paramMap, inputMap, outputMap)` (inherited from `JCCWebBusinessLogic`) to execute. 5. Call `mapper.getXXX(paramBean, outputMap)` for each sub-service to extract results. This pattern appears in both `invokeServiceKKSV0170()` and `invokeServiceKKSV0171()`.