# Com / Fujitsu / Futurity

## Overview

The `com.fujitsu.futurity` package contains the core business logic layer for the **K-Opticom (eo brand)** customer base system — an enterprise telecommunications application built on Java EE by Fujitsu. This module serves as the bridge between web-facing client applications and the underlying data persistence infrastructure, handling the full customer lifecycle: new registration, information updates, service contract management, billing inquiries, guarantor coordination, and external system integration.

The codebase is built around the **Fujitsu BPM (Business Process Model) framework** (version 3.2.0.a, BPMXML 2.6) and follows a strict layered architecture where process definitions are authored declaratively and compiled into Java classes via template-driven code generation. This model-driven approach means the business process structure is defined separately from its implementation, and developers modify BPMXML templates rather than hand-writing boilerplate flow code.

The module is organized into four architectural tiers:

1. **Flow layer** — Stateless EJB entry points (`AbstractService` subclasses) that orchestrate process execution
2. **Operation layer** — Business operation classes (`AbstractOperation` subclasses) that execute sequential steps
3. **Common Component (CC) layer** — Reusable business logic classes for shared operations
4. **Mapping layer** — Data transformation classes between the BPM layer and Service Component persistence

## Sub-module Guide

The `bp` sub-module (`com.fujitsu.futurity.bp`) contains the bulk of the business logic, organized into approximately 70+ process definitions and 100+ common component classes.

### Process Definitions (`bpm/`)

The `bpm/` directory groups flows by functional prefix into three sub-packages:

| Sub-package | Prefix | Count | Purpose |
|---|---|---|---|
| `bpm/acsv` | ACSV | ~39 | Application-side CSV processing and registration screens — the largest and most complex group |
| `bpm/ccsv` | CCSV | ~11 | Common and electronic file management screens — typically smaller, focused operations |
| `bpm/chsv` | CHSV | ~22 | High-priority household service operations — includes the most complex operations in the codebase |

The three prefixes (ACSV, CCSV, CHSV) represent distinct functional domains that share the same underlying architecture but serve different customer-facing screens. ACSV flows handle registration and screen data operations, CCSV flows manage system maintenance and electronic file services, and CHSV flows handle guarantor coordination and complex multi-step business transactions.

### Common Components (`common/`)

Over 100 reusable business component classes are organized by functional prefix (JCK*, JCH*, JAC*, JCC*, etc.). A single shared utility — `JCKPmpCommonUtil` — provides standardized patterns for PMP (Customer Information Platform) integration, including service component invocation, result extraction, and debug logging.

### Data Mapping (`mapping/`)

150+ mapper classes handle data transformation between the BPM/CC layer and the Service Component persistence layer. Each mapper converts between BPM request parameter maps and SC-specific message DTOs (e.g., `ECH0011B012CBSMsg`), supporting bidirectional conversion.

### How the Sub-modules Relate

The `bp` sub-module is a self-contained business process engine. Its internal layers form a dependency chain: **Flows orchestrate Operations, Operations delegate to Common Components and Mappers, and Mappers translate data for Service Components**. The three flow groups (ACSV, CCSV, CHSV) share the same Common Component pool and mapping infrastructure — they differ only in their BPMXML process definitions and which specific CC/mapper combinations they invoke. Adding a new process (e.g., ACSV0040) involves defining a new BPMXML template, generating the Flow and Operation classes, and creating any needed mapper or CC classes — no changes to the framework infrastructure are required.

## Key Patterns and Architecture

### Template-Driven Code Generation

Every Flow and OPOperation class carries a header indicating generation by the Fujitsu BPM framework:

```
// GENERATED BY TEMPLATE VERSION 3.2.0.a
// BASED ON BPMXML VERSION 2.6
```

The template engine generates Flow classes extending `AbstractService` (stateless EJBs with `@Stateless`) and Operation classes extending `AbstractOperation`. Business process structure is defined declaratively in BPMXML; developers modify the templates or BPMXML definitions to create or modify flows rather than hand-writing boilerplate.

### Standard Execution Flow

Every process follows a consistent three-phase pattern:

```
Flow.run()
  ├─ Pre-processing: Common CC: mappingInit
  ├─ Operation: OPOperation.execute()
  │   ├─ Step 1: ServiceComponentBroker → SC call
  │   ├─ Step 2: ServiceComponentBroker → SC call (if needed)
  │   ├─ Step 3: CCRequestBroker → CC call (if needed)
  │   └─ ... additional steps
  └─ Post-processing: Common CC: mappingDispose
```

The Flow class orchestrates this via a `BPMOperator`, which manages `DBConnectionInfo` setup, broker invocations, and exception judgment.

### Two Broker Types

The Operation layer uses two broker types:

- **ServiceComponentBroker** — Wraps remote Service Component calls for DB persistence. Bound to a specific SC process name (e.g., `ACSV000101SC`) and requires explicit `DBConnectionInfo` setup per step.
- **CCRequestBroker** — Invokes local Common Component methods directly for business logic that doesn't need direct DB access. References a specific CC class and method name (e.g., `JCHGetPrcKmkCsChgeListCC.getPrcKmkCsChgeList`).

### Conditional Execution and Exception Handling

Some OPOperation classes use `ExeCondition` objects to implement conditional branching within operations — each step can be annotated with conditions (e.g., `cust_type = "カスタム"`) that determine whether the step executes, enabling dynamic process paths from the same code.

Exception handling is granular: each step in an OPOperation specifies its own `ExceptionJudge` class array, with three tiers — `DefaultCCExceptionJudge` for Common Component errors, `DefaultSCExceptionJudge` for Service Component errors, and a mapping-specific exception judge.

### Architecture Diagram

The following diagram shows how the web application layer, EJB module, and external systems interact:

```mermaid
flowchart TD
    subgraph Client["Web Application Layer"]
        WebA["WebA
(eo customer front)"]
        WebB["WebB
(enterprise front)"]
        WebR["WebR
(resident front)"]
        WebF["WebF
(finance front)"]
        WebRest["WebRest
(REST API)"]
    end

    subgraph EJB["EJB Module
koptBp"]
        subgraph BPM["Business Process Model"]
            Flow["Flow classes
ACSV/CCSV/CHSV
entry points"]
            Op["Operation classes
OPOperation
execute steps"]
        end

        subgraph CC["Common Component Layer"]
            CC_Base["Shared utilities
JCKPmpCommonUtil
JCCBPCommon etc."]
            CC_Business["Business logic
JCKSV902201CC
customer registration
JCH* customer info
JCK* customer management"]
        end

        subgraph Mapping["Data Mapping Layer"]
            Mapper["BSMapper classes
ACSV0001_*Mapper
convert between BPM
and Service Components"]
        end

        Flow --> Op
        Op --> CC
        Op --> Mapper
        Mapper --> CC
        CC --> CC_Base
    end

    subgraph External["External Systems"]
        PMP["PMP Platform
(customer info platform)"]
        SC["Service Components
DB persistence"]
    end

    CC --> PMP
    CC --> SC
    Mapper --> SC
```

### Flow Execution Detail

```mermaid
flowchart LR
    Client["Web Screen
Request"] --> Flow["Flow Class
@Stateless
AbstractService"]

    subgraph FlowPhases["Flow Execution Phases"]
        MI["Pre-processing
mappingInit"]
        OP["Operation
OPOperation
AbstractOperation"]
        MD["Post-processing
mappingDispose"]
    end

    Flow --> MI --> OP --> MD

    subgraph OpSteps["Operation Internal Steps"]
        SC1["ServiceComponent
Broker to SC"]
        SC2["ServiceComponent
Broker to SC"]
        CC1["CC Request
Broker to CC"]
        CC2["CC Request
Broker to CC"]
    end

    OP --> SC1 --> SC2
    OP --> CC1 --> CC2

    SC1 --> DB[(Database)]
    SC2 --> DB
    CC1 --> DB
    CC2 --> DB
```

## Dependencies and Integration

### Internal Dependencies

- **Fujitsu BPM Framework** (`com.fujitsu.futurity.bp.x21.*`) — Core process engine providing `AbstractService`, `AbstractOperation`, `BPMOperator`, `ServiceComponentBroker`, `CCRequestBroker`, `RequestParameter`, and exception handling.
- **Fujitsu Model Layer** (`com.fujitsu.futurity.model.*`) — Data transfer objects used throughout.
- **eo Common Layer** (`eo.common.*`, `eo.ejb.*`) — Utility classes for string handling, date manipulation, logging, and shared constants from the broader K-Opticom platform.

### External Integration

- **PMP Platform** — External Customer Information Platform for customer data synchronization. The `JCKPmpCommonUtil` class provides the standardized integration layer, including service component invocation, result extraction, and debug logging.
- **Service Components** — The mapping layer translates BPM data into SC messages (classes like `ECH*CBSMsg`, `ECK*CBSMsg`, `EKK*CBSMsg`, `EZM*CBSMsg`) which handle actual database operations.

### Transaction Management

Flow classes are `@Stateless` EJBs with `TransactionManagementType.BEAN`, meaning transaction boundaries are controlled explicitly through the BPM framework. The `DBConnectionInfo` constructed for each step determines the transaction scope — each broker invocation can participate in its own transaction boundary.

## Notes for Developers

### Working with Generated Code

- Flow and OPOperation classes are **generated from BPMXML templates**. Do not hand-edit these files directly — changes will be overwritten on the next generation. If you need to modify a business process, update the BPMXML or template definitions.
- Common Components (CC), mapping classes, and utility classes are **hand-written** and can be modified freely.

### Adding a New Process

To add a new process (e.g., `ACSV0040`):

1. Define the process in BPMXML — this generates `bpm/acsv0040/ACSV0040Flow.java` and `bpm/acsv0040/ACSV0040OPOperation.java`
2. Add the corresponding Service Component calls to the generated OPOperation class (or define them in BPMXML)
3. Create `ACSV0040_ACSV0040OP_*BSMapper.java` files in the `mapping/` directory for data transformation
4. If new business logic is needed, create a new CC class in `common/`

### Naming Conventions

| Component Type | Pattern | Example |
|---|---|---|
| Flow classes | `{PREFIX}{NNNN}Flow` | `ACSV0001Flow` |
| Operation classes | `{PREFIX}{NNNN}OPOperation` | `ACSV0001OPOperation` |
| Mappers | `{PREFIX}{NNNN}_{OPNAME}_{TARGET}Mapper` | `ACSV0001_ACSV0001OP_ECH0401B010BSMapper` |
| CC classes | `J{AREA}{DESCRIPTION}CC` | `JCKSV902201CC` |

### Large Files

Several Common Component classes exceed 100,000 bytes — for example, `JCHTushinSvcPrcChohyoCC` at ~500KB, `JCHZuijiNkinAddCC` at ~299KB, and `JACSeikyUpdCC` at ~105KB. These handle complex, multi-step business operations and are high-coupling classes touching many data paths. Exercise caution when modifying these.

### Logging

All Flow and Operation classes use `JSYbpmLog` for process-level logging. Standard log levels include `JSYLogBase.EXECUTION` for service start/end messages and `JSYLogBase.DEBUG` for step-level debug information.