# Com / Fujitsu / Futurity / Bp / Custom

## Overview

The `com.fujitsu.futurity.bp.custom` package is a large, template-generated business process management (BPM) module within the K-Opticom / Fujitsu Futurity telecommunications operations support system. It implements a comprehensive suite of custom business processes for managing services, contracts, customer data, billing, dispatch, and related operational tasks.

All code in this module is generated from BPMXML definitions (version 2.6) using a template engine (version 3.2.0.a). The module consists primarily of EJB stateless session beans organized as BPM flow classes, each implementing a specific business process through a two-layer architecture: a **Flow** layer that orchestrates the overall process and a corresponding **OP (Operation)** layer that executes individual business steps.

The module also contains a shared `common` sub-package with reusable Common Class (CC) components, and a `mapping` sub-package that routes operations to the appropriate data mappers. This separation of generated flow/control logic from hand-authored or semi-automated data access and mapping code is a key architectural pattern.

## Sub-module Guide

The module is organized into several structural layers that work together:

### BPM Process Modules (`bpm/`)

This is the core of the package. It contains approximately **270+ individual process modules**, each consisting of a pair of classes:

- `XxxFlow.java` — The entry-point class that extends `AbstractService` and is annotated as an EJB `@Stateless` session bean. It defines the process lifecycle, including pre-processing (init) and post-processing (dispose) exception handling via `DefaultCCExceptionJudge` classes.
- `XxxOPOperation.java` — The operation class that extends `AbstractOperation` and executes the actual business logic. It references CC (Common Class) components via `CCRequestBroker` and Service Components (SC) via `ServiceComponentBroker`, both of which are routed through mapper classes.

The processes are grouped by a two-letter prefix (e.g., `ACSV`, `CHSV`, `CKSV`) followed by a unique number, following a naming convention that likely encodes the business domain and process ID. Each directory is self-contained but participates in the shared framework.

### Common Components (`common/`)

Contains shared Common Class (CC) classes — reusable data access and utility components such as:

- `JKKDslLetterAddUpdCC` — DSL letter add/update operations
- `JFUKhriSmbcfsResultCC` — Account transfer contract application result (transaction search)
- `JCHGetPrcKmkCsChgeListCC` — Proxy right change list retrieval
- `JZMRoleInfSearchCC` — Role information search
- `JKKWribAutoAddBatchCC` — Writing auto-add batch operations

These CC classes encapsulate the lowest-level business logic — database lookups, data transformations, and shared cross-cutting operations — and are invoked by OP classes through `CCRequestBroker` instances.

### Mapping Components (`mapping/`)

Contains mapper classes (e.g., `BpOperationMapping`, `ACSV0001_ACSV0001OP_EKK0321B011BSMapper`) that map between business data objects. These are referenced by `ServiceComponentBroker` instances within OP classes to translate input parameters into the format expected by downstream service components.

### Operation Routing (`BpOperationMapping`)

The `BpOperationMapping` class (referenced by the `OperationBroker` in Flow classes) serves as a central routing mechanism, determining which operation implementation should handle a given business request. This enables the Flow class to remain template-generated and minimal while delegating to custom operation logic.

## Relationships Between Sub-modules

These sub-modules form a strict **top-down dependency chain**:

1. **Flow classes** (generated) are the public entry points, exposed as EJB stateless beans. They don't contain business logic — they wire together components.
2. **OP classes** (generated) act as coordinators, invoking CC and SC components via brokers.
3. **Common CC classes** (hand-authored/shared) provide reusable data access and utility logic used across multiple processes.
4. **Mapper classes** (hand-authored/generated) handle data transformation between layers.

The key insight is that the `bpm/` process modules are **thin orchestration layers** — the real business value lives in the `common/` CC classes and the `mapping/` mappers, while the Flow and OP classes provide the structured framework for process execution.

## Key Patterns and Architecture

### Two-Layer BPM Architecture

Every process module follows a consistent pattern:

```
Client → @Stateless Flow → AbstractService → OperationBroker → @Stateless OP → AbstractOperation → CC/SC
```

- The **Flow** class handles EJB lifecycle, transaction management, and pre/post-processing exception handling.
- The **OP** class coordinates individual business steps by invoking CC and SC components through broker objects.

### Broker-Based Component Invocation

The module uses a broker pattern for all cross-component communication:

- **`OperationBroker`** — Routes from Flow to OP, delegating to `BpOperationMapping` for the actual operation resolution.
- **`SubOperationBroker`** — Enables nested/recursive operation invocation within a process.
- **`CCRequestBroker`** — Invokes Common Class methods (e.g., `getSvcKeiHzkIfShkKjKapOps`) with exception handling context.
- **`ServiceComponentBroker`** — Invokes Service Component classes with mapper class pairs for data transformation.

### Exception Handling Strategy

Each CC, SC, and OP component declares its own exception judge class (e.g., `DefaultCCExceptionJudge`, `DefaultSCExceptionJudge`). This allows fine-grained error handling per component, with the Flow layer also defining shared init/dispose exception handling via `exceptionJudgeClassNameMappingInit` and `exceptionJudgeClassNameMappingDispose`.

### Conditional Execution

OP classes use `ExeCondition` arrays (e.g., `execondition1`, `execondition2`) to control whether specific CC/SC invocations should execute based on runtime conditions. These are injected via `@Inject` from `ExeConditionReqChk`.

### Generated Code Pattern

All Flow and OP classes carry the header:
```
// GENERATED BY TEMPLATE VERSION 3.2.0.a
// BASED ON BPMXML VERSION 2.6
```

This indicates the code is generated from BPMXML definitions, which means the business process logic is likely defined declaratively in BPMXML files and compiled into Java at build time. The generated classes are structured to be stable across template updates.

### Process Prefix Groups

Processes are organized by two-letter prefix groups that correspond to business domains:

| Prefix | Count | Domain (inferred) |
|--------|-------|-------------------|
| CHSV   | ~96   | Core business processes (contract, proxy rights, work info, etc.) |
| CKSV   | ~59   | Customer/contract management (customer registration, changes, cancellations) |
| ACSV   | ~39   | Temporary registration / service data acquisition (temporary money, screen data retrieval) |
| CCSV   | ~11   | Communication/file management (electronic file management, service agreement) |
| KKS*   | ~10   | Service contract attached information (construction, assignment, operator support) |
| CRSV   | ~6    | Settlement/billing processes |
| CNSV   | ~3    | Billing/account processes |
| DKSV   | ~5    | Dispatch management |
| FUSV   | ~5    | Account transfer / contract result processing |
| TUSV   | ~4    | Telecom services (telephone, transmission) |

## Dependencies and Integration

### Internal Dependencies

The module depends heavily on the `com.fujitsu.futurity.bp.x21` framework package, specifically:

- `AbstractService` / `AbstractOperation` — Base classes for all flow and operation classes.
- `IBPRunnable` / `IOperation` / `IBPM` — Interfaces implemented by Flow and OP classes.
- `OperationBroker`, `SubOperationBroker`, `CCRequestBroker`, `ServiceComponentBroker` — Component invocation brokers.
- `BPMFlowException`, `DBLookupException`, `DBSystemException`, `ReqChkException` — Exception types.
- `RequestParameter`, `StatusInfo`, `ErrorLevel` — Parameter and status objects.
- `DefaultCCExceptionJudge`, `DefaultSCExceptionJudge` — Exception handling.
- `ExeCondition`, `ExeConditionReqChk` — Conditional execution support.
- `BeanFactory`, DI annotations — Dependency injection framework.
- Various value constants — `ERROR_MESSAGE`, `RETURNCODE_SYSTEM`, `OUTBREAK_AREA`, `MessageID`.

### External Dependencies

- **EJB 3.x** — All Flow classes are `@Stateless` session beans with `TransactionManagement(TransactionManagementType.BEAN)`.
- **Fujitsu proprietary framework** — The `com.fujitsu.futurity.common` package provides logging (`JSYbpmLog`, `JSYLogBase`) and cross-cutting utilities.
- **Database** — CC classes perform database lookups through the `DBLookupException` framework.

### Cross-Module Integration

The `BpOperationMapping` class serves as a central routing hub, enabling the Flow layer to delegate to operations defined either within this custom module or in other modules. Similarly, Service Components referenced by the `ServiceComponentBroker` likely exist in other packages, with the mappers in this package handling the translation.

```mermaid
flowchart TD
    Client["Client / Frontend"] --> EJB["EJB Container
(@Stateless)"]

    subgraph BPM["BPM Custom Module
com.fujitsu.futurity.bp.custom"]
        direction TB
        Flow["Flow Class
(AbstractService)"] --> OP["OP Class
(AbstractOperation)"]
        OP --> CC["Common CC
(JxxCC)"]
        OP --> SC["Service Component
(xxSC)"]
        OP --> Map["Mapper
(BpOperationMapping)"]
    end

    subgraph BPMX21["BPM Framework
com.fujitsu.futurity.bp.x21"]
        Broker["OperationBroker
SubOperationBroker"] --> CC
        CCBroker["CCRequestBroker"] --> CC
        SCBroker["ServiceComponentBroker"] --> SC
    end

    subgraph Support["Support Packages"]
        ExeCond["ExeCondition
(Conditional execution)"] -.-> OP
        Mapping["BpOperationMapping
(Operation routing)"] -.-> OP
    end

    EJB --> Flow

    subgraph Prefixes["BPM Process Groups (by code prefix)"]
        direction LR
        CH["CHSV
~96 processes
Core business"]
        CK["CKSV
~59 processes
Customer/contract"]
        AC["ACSV
~39 processes
Temporary registration"]
        CC_["CCSV
~11 processes
Communication/file"]
        KK["KKS*"]
        CR["CRSV"]
        CN["CNSV"]
        DK["DKSV"]
        FU["FUSV"]
        TU["TUSV"]
    end

    Flow --> CH
    Flow --> CK
    Flow --> AC
    Flow --> CC_
```

## Notes for Developers

### Template-Based Development

Since all Flow and OP classes are generated from BPMXML templates, **directly editing** generated files will be lost on the next build. New business processes should be defined by:

1. Creating or updating the BPMXML definition.
2. Updating the `common/` CC classes and `mapping/` mapper classes with hand-authored logic.
3. Regenerating the Flow and OP classes via the template engine.

### Adding a New Process

To add a new BPM process:

1. Create a new package under `bpm/` following the naming convention (e.g., `bpm/xysv0001/`).
2. The template generates both `XySV0001Flow.java` and `XySV0001OPOperation.java`.
3. If additional common logic is needed, add a new CC class to `common/`.
4. If new data mapping is needed, add a new mapper class to `mapping/`.
5. Register the operation in `BpOperationMapping`.

### Component Broker Selection

When implementing OP classes:

- Use **`CCRequestBroker`** for invoking shared Common Class components (database lookups, cross-cutting logic).
- Use **`ServiceComponentBroker`** for invoking domain-specific Service Components that require data mapping.
- Use **`OperationBroker`** in Flow classes to delegate to the OP.

### Exception Handling

Each component should declare its exception judge class. The default `DefaultCCExceptionJudge` and `DefaultSCExceptionJudge` provide standard exception handling. Custom exception judges can be implemented if the default behavior needs to be extended for specific processes.

### Scale and Maintenance

With approximately **270+ process modules** across 10 domain groups, this is one of the largest packages in the codebase. When making changes:

- Be aware that many CC classes (e.g., in `common/`) are likely shared across multiple processes.
- Changes to common components should be tested across all dependent processes.
- The prefix-based organization can be used to scope impact analysis (e.g., changes to CHSV* processes likely only affect the ~96 CHSV* processes).
- Process numbers are not strictly sequential (gaps exist), suggesting processes may be deprecated, split, or repurposed over time.

### Logging

The module uses Fujitsu's proprietary logging classes (`JSYbpmLog`, `JSYLogBase`) from the `com.fujitsu.futurity.common` package. Business events should be logged through these classes rather than generic SLF4J/Java Util Logging to ensure consistent log format and integration.