# Eo / Ejb

## Overview

The `eo.ejb` package is the **Enterprise Java Bean (EJB) service layer** of the eo customer core system (`eo顧客基幹システム`), a telecommunications customer management platform originally developed by Fujitsu for K-Opticom (now part of KDDI's "eo" brand). It sits between the BPM (Business Process Management) operations layer and the underlying data/external service infrastructure, serving as the central business logic engine for customer account management operations.

This module implements a **message-driven, template-based architecture** where each business operation (identified by a template ID) defines its own message schema, implements its own processing logic, and is invoked by BPM operations through a standardized `CAANMsg` container. The package is organized into several major sub-modules, each addressing a different operational concern:

- **CBS (Customer Business Service)** -- Core customer-facing business operations such as contract management, account changes, customer information updates, and service plan modifications. This is the primary entry point for most customer management operations.
- **CBM (Customer Business Message)** -- An expanded message-oriented variant of CBS, with more granular message schemas and parallel processing pipelines. It mirrors the CBS architecture but appears to support newer or more complex operations.
- **Check** -- Validation and correlation rules that govern item-level and cross-item constraints. It defines what data is permissible before processing begins.
- **Domain** -- Shared domain logic utilities, including super-class helpers for field formatting, type checking, and reference classification.
- **Common** -- Cross-cutting utilities used throughout the system: character conversion, encryption, access logging, pagination, model constants, and shared control logic for various data domains (AC, CC, CH, CK, CN, CR, DK, KK, KU, WC, ZM).

All sub-modules follow the same fundamental pattern: **define a message schema, implement processing logic against it, and invoke through a BPM operation**. This repetition is deliberate -- it enables each service to be developed, versioned, and deployed independently.

## Sub-module Guide

### Customer Business Service (cbs)

The `cbs` package is the heart of the `eo.ejb` layer. It handles the vast majority of customer-facing business operations.

#### Sub-structure

| Sub-package | Purpose |
|---|---|
| `cbsmsg` | Hundreds of Java classes defining request/response message schemas. Each CBS service typically has a message class (e.g., `EKKA1880001CBSMsg`) and one or more list classes (e.g., `EKKA1880001CBSMsg1List`, `CBSMsg2List`). |
| `mainproc` | Implementation classes for each service's processing logic. Each class (e.g., `JEKKA1880001TPMA`) implements the `TemplateMainHandler` interface, reads input from a `CAANMsg`, performs validation and external service calls, and writes results back. |
| `msgconv` | Message conversion utilities that transform data between representations. |
| `sqlf` | SQL-related formatting utilities. |

#### Domain Naming Convention

Message and handler classes encode the service domain in their names:

- **E** prefix -- Customer Business Service message
- **AC** -- Account domain
- **CC** -- Contract domain
- **CH** -- Customer home domain
- **CK** -- Service plan domain
- **CN** -- Network access domain
- **CR** -- Registration domain
- **CNA** -- Network access (expanded)
- **DK** -- Various operational domain
- **CKA** -- Service plan (expanded)
- **Numeric segment** -- Unique service identifier
- **Suffix** -- `CBSMsg` (top-level message), `CBSMsg1List` (detail list), `CBSMsg2List` (nested list), `TPMA` (processing handler)

#### How CBS Operations Work

1. A BPM operation constructs a `CAANMsg` (the Fujitsu Futurity framework message container) populated with input data, referencing the appropriate `cbsmsg` class for field definitions.
2. The `CAANMsg` is passed to the corresponding `mainproc` handler.
3. The handler performs field-level validation (mandatory checks, format checks, row count checks).
4. Configuration values (URLs, auth tokens, timeouts) are read from system settings tables.
5. External services are invoked -- typically via HTTP REST APIs -- with JSON payloads built from `CAANMsg` fields.
6. Response data is parsed and mapped back into the `CAANMsg`.
7. Error codes are standardized: E1 (mandatory check), E2 (domain check), E3 (row count check), EA (config error), EB (response error), EC (runtime error).
8. The populated `CAANMsg` is returned to the BPM operation, which reads the results.

### Customer Business Message (cbm)

The `cbm` package mirrors the CBS architecture with some important distinctions:

#### Sub-structure

| Sub-package | Purpose |
|---|---|
| `cbmmsg` | Message schema definitions similar to `cbsmsg`, but with a different naming convention (e.g., `AC0091CBMMsg`, `CH0391CBMMsg`) and generally more detailed field structures. |
| `mainproc` | Main processing implementations for CBM operations. |
| `check` | CBM-specific check logic. |
| `msgconv` | Message conversion for CBM. |
| `entity` | Entity mappings specific to CBM operations. |

#### How CBM Differs from CBS

CBM appears to be an evolution or parallel track of the CBS architecture. Key differences:

- CBM message classes tend to have more fields and more complex nested structures (some reach `CBSMsg3List`/`CBSMsg4List` depth).
- CBM has a dedicated `entity` sub-package, suggesting a more explicit object-relational mapping layer.
- CBM has its own `check` sub-package, whereas CBS relies more heavily on the shared `eo.ejb.check` package.
- CBM classes use a simpler naming convention without the `E` prefix and version suffixes (e.g., `AC0091CBMMsg` vs. `EAC0091B010CBSMsg`), suggesting a cleaner, more modern design.

In practice, CBS and CBM coexist and serve different subsets of operations. They share the same underlying architecture patterns, message flow, and `CAANMsg` container format, but maintain separate code paths for compatibility and gradual migration.

### Validation Layer (check)

The `check` package provides the validation and constraint-checking infrastructure that underpins both CBS and CBM operations.

#### Sub-structure

| Sub-package | Purpose |
|---|---|
| `correlate` | Cross-item correlation rules (e.g., `JSYejbEKK0191D010SKCK`). Validates relationships between different items. |
| `item` | Item-level validation rules (e.g., `JSYejbEAC0621B010TMCK`). Validates individual field values against business rules. |
| `itemrelation` | Item-to-item relationship constraints. |
| `state` | State machine or status transition rules. |

The check classes follow a naming convention: `JSYejbE` + domain code + service ID + `TMCK` (Item check) or `SKCK` (Correlation check). These are referenced by CBS/CBM processing handlers to enforce data integrity before external API calls are made.

### Domain Logic (domain)

The `domain` package contains shared domain utilities.

- **`JSYejbBaseDomain`** -- The base class providing constants and helper methods for field formatting, type classification (fixed-length, variable-length, numeric, precision, binary), reference classification, and other domain-specific logic.
- **`JSYejbC#####Domain`** -- Hundreds of numbered domain utility classes (e.g., `JSYejbC0000001Domain` through `JSYejbC0000199Domain`), each providing specific field validation or formatting logic. These are small, focused classes (~2.9 KB each) that implement specific domain rules.
- **`JSYejbM#####Domain`** -- Message-level domain classes for more complex multi-field validations.

### Common Utilities (common)

The `common` package is the largest and most varied, providing cross-cutting concerns used throughout the entire `eo.ejb` package:

| Category | Examples |
|---|---|
| **Model constants** | `JACModelCommon`, `JCCModelCommon`, `JCHModelCommon`, `JCKModelCommon`, `JCNModelCommon`, `JCRModelCommon`, `JDKModelCommon`, `JKKModelConst`, `JKUModelCommon`, `JTUModelCommon`, `JWCCtrlTnInfo`, `JZMModelCommon` -- Constants and shared logic per data domain |
| **Character/encryption** | `JCCejbConvertCharacter`, `JCCejbEncryptionUtil` |
| **Access logging** | `JCCAccessLogEventCache`, `JCCPrintAccessLog`, `EventIDList` (313 KB) |
| **Security/authority** | `JCCAuthorityCtrlCache` |
| **Database** | `JKKCtrlTnInfoImpl` (88 KB), `JCRejbCreateQueryCondition` (185 KB), `JKKCtrlPaygentAuthInfoStb` |
| **Pagination** | `JKKejbPagingUtil` |
| **Date utilities** | `JSYejbSysDate`, `JCCejbGetOperationDateUtil` |
| **Equipment control** | `JKKUejbTaknkikiCtrlUtil`, `JKKUejbGetTekkyoKiki`, `JKKUejbOnuKknKojiMngnAdd` |
| **Exception handling** | `JKKejbBusinessException` |

## Key Patterns and Architecture

### Message-Driven Template Architecture

Every operation in the `eo.ejb` package follows the same template:

1. **Schema Definition** -- A message class in `cbsmsg` or `cbmmsg` defines the request and response structure by extending `CAANSchemaInfo` and mapping field names to types.
2. **Handler Implementation** -- A processor class in `mainproc` implements the business logic, reading fields by their constant keys and populating output fields.
3. **BPM Orchestration** -- BPM operations in `koptBp` (the BPM module) assemble messages, call handlers, and interpret results.

This creates a clean separation of concerns: message schemas are stable contracts, handlers are focused implementations, and BPM operations orchestrate the workflow.

### CAANMsg Data Flow

All messages flow through the `CAANMsg` object, a structured message container from the Fujitsu Futurity framework:

```
BPM Operation -> CAANMsg (input) -> Handler -> CAANMsg (output) -> BPM Operation
```

The handler reads input data from the `CAANMsg`, performs business logic (often HTTP API calls), and writes results back. Field access uses constant strings defined in the corresponding message class.

### External Service Integration Pattern

The main processing classes follow a consistent pattern for external service calls:

1. Read configuration parameters (URL, auth token, timeouts) from system settings tables.
2. Build a JSON payload from the `CAANMsg` fields using Jackson JSON libraries.
3. Set HTTP headers (`Authorization`, `Content-Type: application/json`).
4. Execute an HTTP POST to the target service URL.
5. Parse the JSON response and map fields back to the `CAANMsg`.
6. Handle errors with standardized error codes (E1-E3 for validation, EA for config errors, EB for response errors, EC for runtime errors).

Several handlers include stub mode support (`STUB_HTTP_STATUS_KEY`, `DUMMY_AUTHORIZATION`) for development and testing without hitting real external endpoints.

### Validation Architecture

The check sub-packages (`eo.ejb.check`) provide a layered validation approach:

- **Item-level checks (`item`)** validate individual field values against business rules.
- **Correlation checks (`correlate`)** validate relationships between different items or records.
- **Item-relation checks (`itemrelation`)** validate parent-child or sibling relationships within message structures.
- **State checks (`state`)** validate state transitions.

These checks are invoked by CBS/CBM handlers before making external service calls, ensuring that invalid data never reaches downstream systems.

### Domain Class Hierarchy

The domain package provides a shared base (`JSYejbBaseDomain`) from which all domain utility classes inherit. The base class provides:

- Constants for null and empty representations
- Field type classifications (fixed, variable, numeric, precision, binary, significant digits)
- Field count check attribute references
- Reference classification rules (independent, subordinate, none, input)

Numbered subclasses (`JSYejbC####Domain`) implement specific domain rules, each as a small, focused class.

### Module Interaction

```mermaid
flowchart TD
    BPM["BPM Operations
koptBp"] -->|Delegates| CBS["Customer Business Service
eo.ejb.cbs"]
    BPM -->|Delegates| CBM["Customer Business Message
eo.ejb.cbm"]
    BPM -->|Validates via| CHECK["Validation Layer
eo.ejb.check"]
    CBS -->|Defines schemas| CBSMSG["CBS Message Layer
eo.ejb.cbs.cbsmsg"]
    CBS -->|Implements logic| CBSMAIN["CBS Main Handlers
eo.ejb.cbs.mainproc"]
    CBS -->|Converts messages| CBSMSGCONV["CBS Message Conversion
eo.ejb.cbs.msgconv"]
    CBM -->|Defines schemas| CBMMSG["CBM Message Layer
eo.ejb.cbm.cbmmsg"]
    CBM -->|Implements logic| CBMMAIN["CBM Main Handlers
eo.ejb.cbm.mainproc"]
    CBM -->|Validates| CBMCHECK["CBM Check Logic
eo.ejb.cbm.check"]
    CBM -->|Converts messages| CBMMSGCONV["CBM Message Conversion
eo.ejb.cbm.msgconv"]
    CBM -->|Maps to entities| CBMENTITY["CBM Entities
eo.ejb.cbm.entity"]
    CBSMAIN -->|Invokes| EXT["External Services
REST/HTTP APIs"]
    CBSMAIN -->|Depends on| COMMON["Common Utilities
eo.ejb.common"]
    CBMMAIN -->|Depends on| COMMON
    CHECK -->|Correlation rules| CHECKCORR["Correlate
eo.ejb.check.correlate"]
    CHECK -->|Item checks| CHECKITEM["Item
eo.ejb.check.item"]
    DOMAIN["Domain Logic
eo.ejb.domain"] -->|Supports| CBS
    DOMAIN -->|Supports| CBM
    CBSMSG -->|Referenced by| VIEW["Web View Layers
koptWebR"]
```

## Dependencies and Integration

### External Dependencies

- **Fujitsu Futurity Framework** -- `CAANMsg`, `CAANSchemaInfo`, `StatusCodes`, `TemplateMainHandler`, and the BPM operation framework are provided by the Fujitsu Futurity application platform.
- **Jackson JSON** -- Used for building and parsing JSON payloads in external service calls.

### Upstream Consumers

The `eo.ejb` module is consumed by a wide range of modules:

- **BPM Operations** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/bpm/`) -- Dozens of operation classes that define workflow steps, import CBS/CBM message classes, and call mainproc handlers.
- **Mapping Classes** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/mapping/`) -- Bridge classes implementing `IInputMessageEditor`/`IOutputMessageEditor` that map between BPM structures and CBS message schemas.
- **Common Components** (`koptBp/ejbModule/com/fujitsu/futurity/bp/custom/common/`) -- Shared component classes that invoke CBS handlers for reusable functionality.
- **Web View Layers** (`koptWebR/src/eo/web/webview/`) -- Many web view logic classes reference `*CBSMsg1List` constants from the parent package for data binding.

### Internal Dependencies

Within the `koptModel` module, `eo.ejb` depends on:

- `eo.common` -- String utilities, constants, shared model logic
- `eo.ejb.common` -- Database security processing, common EJB utilities
- `com.fujitsu.futurity.model` -- `CAANMsg`, `CAANSchemaInfo`, `StatusCodes`, `TemplateMainHandler`, Jackson JSON libraries

## Notes for Developers

- **Two parallel architectures** -- Both CBS and CBM exist in this package. They follow the same patterns but maintain separate code paths. When working on a new operation, determine whether it belongs to CBS or CBM based on the business domain and existing patterns.
- **Coordinated changes are required** -- When adding or modifying a message field, you must update the `cbsmsg` or `cbmmsg` schema class and every `mainproc` handler that reads or writes that field. The schema class acts as the contract between layers.
- **CBS messages are generated** -- The `cbsmsg` classes are generated from BPMXML templates (version 2.6). The `cbmmsg` classes appear to follow a similar generation process. The `mainproc` classes are hand-written implementations.
- **Error codes are standardized** -- Each handler uses the same error flag convention: E1 (mandatory check), E2 (domain check), E3 (row count check), EA (config error), EB (response error), EC (runtime error).
- **The module is part of a large, long-lived codebase** -- Source files date back to 2011 and have undergone continuous updates through 2025. The version history headers (e.g., `v75.00.00 2025/03/26`) reflect incremental feature additions (NTT decommissioning, home gateway changes, Netflix integration, etc.) rather than major refactors.
- **Hundreds of small domain classes** -- The `domain` package contains nearly 200 numbered domain utility classes, each ~2.9 KB. Do not look for inheritance hierarchies here; each class is independently focused on specific field rules.
- **Common utilities are domain-scoped** -- The `JCCModelCommon`, `JCKModelCommon`, `JKKModelConst`, etc. files are each ~20-270 KB and contain extensive constants and shared logic for their respective data domains. Know which domain-scoped utility to use for the operation you are working on.
- **Stub mode exists for testing** -- Several handlers support stub mode (`STUB_HTTP_STATUS_KEY`, `DUMMY_AUTHORIZATION`) that allows testing without real external endpoints. Check the handler source for stub support before setting up test infrastructure.
- **The `EventIDList.java` file is large (313 KB)** -- It contains event ID definitions used across access logging. Changes to it affect the entire system's event tracking.