# Getting Started

## What This Project Does

This is the **eo Customer Base System** — a large-scale Japanese telecommunications customer management platform built by Fujitsu for K-Opticom. It handles customer account management, billing, contract processing, device (STB/set-top box) control, and batch settlement operations across multiple service brands (KK for K-Opticom broadband, CH for cable services, CR for CRM operations, etc.). The system runs as a Java EE 2.5 web application on Sun GlassFish, uses JavaServer Faces (JSF 1.1) for the UI layer, and relies on the proprietary **Futurity X33** web client framework.

## Recommended Reading Order

1. **This guide** — project layout and conventions
2. `source/koptWebR/WebContent/WEB-INF/web.xml` — the filter chain that every request passes through
3. `source/koptWebR/WebContent/WEB-INF/faces-config.xml` — the JSF lifecycle configuration
4. `source/koptWebR/src/eo/web/webview/` — pick a single `SF` (Screen Function) directory to see the full MVC stack
5. `source/koptCommon/src/eo/common/util/` — read `JCCCommonUtil.java` or `JFUCommonUtil.java` for shared utilities
6. `source/koptBatch/src/eo/business/common/` — batch business logic (run nightly for billing/settlement)

## Key Entry Points

These are the best classes to start reading to understand how the system works:

| Entry Point | Location | What It Does |
|---|---|---|
| `X33JVSessionSynchronizingFilter` | `com.fujitsu.futurity.web.x33` | Filter that synchronizes the HTTP session at the start of every `*.faces` request |
| `X33JVAjaxBackRequestFilter` | `com.fujitsu.futurity.web.x33` | Handles AJAX back-button state restoration |
| `X33JVUrlDecodingFilter` | `com.fujitsu.futurity.web.x33` | Decodes URL parameters (response-decode enabled) |
| `X33JVCharEncodingFilter` | `com.fujitsu.futurity.web.x33` | Sets `windows-31j` (Shift-JIS) encoding for all requests/responses |
| `X33VCheckExceptionFilter` | `com.fujitsu.futurity.web.x33` | Catches framework exceptions and routes to error pages |
| `X33JWPhaseListener` | `com.fujitsu.futurity.web.x33` | JSF lifecycle phase listener — hooks into Restore View, Apply Request Values, etc. |
| `X33VViewJSPBean` | `com.fujitsu.futurity.web.x33.beans` | The root session-scoped managed bean; all UI state flows through here |
| `X33VViewBaseBean` | `com.fujitsu.futurity.web.x33.beans` | Base class extended by every screen's Bean; holds form data and view state |
| `JCCBatCommon` | `eo.business.common` | Common batch processing logic — file I/O, DB access, syslog generation |
| `AC0091CBMMsg` | `eo.ejb.cbm.cbmmsg` | Sample CBM (Core Business Message) data model — defines field schemas as `Object[][] CONTENTS` |

## Project Structure

```
source/
├── koptWebR/                        <-- Main web application (radio/customer portal)
│   ├── WebContent/
│   │   ├── WEB-INF/
│   │   │   ├── web.xml              <-- Servlet filter chain definition
│   │   │   ├── faces-config.xml     <-- JSF 1.1 config (managed beans, lifecycle)
│   │   │   ├── sun-web.xml          <-- GlassFish-specific deployment (EJB refs, sessions)
│   │   │   └── gyomu.tld            <-- Custom JSP tag library
│   │   ├── wsd/ns/jpn/pc/           <-- JSP pages (e.g. FUW009010PJP.jsp)
│   │   ├── js/                      <-- JavaScript per-screen (FUW00916.js, etc.)
│   │   ├── js/common/               <-- Shared JS (FUcommon.js, checkFieldF.js)
│   │   ├── popup/                   <-- Fancybox popup dialogs
│   │   ├── errorContents/           <-- Error display JSPs
│   │   └── healthCheck.html         <-- Load balancer health check
│   ├── src/eo/web/webview/          <-- Java MVC controllers (SF = Screen Function)
│   │   ├── FUW00901SF/              <-- One screen: Bean + Checker + Logic
│   │   ├── FUW00902SF/
│   │   ├── ACW00101SF/
│   │   └── ... (80+ screen packages)
│   └── KankyoIzon/Context/          <-- Environment-specific deploy configs
│       ├── k0/ (production)
│       ├── k1, k2, k3 (staging/dev)
│       ├── it2-01 .. it2-08 (integration tests)
│       └── eo (environment-agnostic)
│
├── koptWebA/                        <-- Alternate web app (same structure as koptWebR)
├── koptWebB/                        <-- Another web app (same structure)
│
├── koptCommon/                      <-- Shared Java library (all modules)
│   └── src/eo/
│       ├── common/constant/         <-- String constants per-brand (JFUStrConst, JKKStrConst...)
│       └── common/util/             <-- Shared utilities (encryption, CSV, FTP, mail, dates)
│
├── koptBatch/                       <-- Batch processing application
│   └── src/eo/business/
│       ├── common/                  <-- Batch common (JCCBatCommon, JKKBatCommon, etc.)
│       └── service/                 <-- Batch service logic (billing, settlement, etc.)
│
├── koptModel/                       <-- Data models & EJB messages
│   └── src/eo/ejb/cbm/cbmmsg/       <-- CBMMessage classes (AC*, CH*, CK*, CN*, CR*)
│
├── koptBp/                          <-- Business process / EJB module
│   └── ejbModule/com/fujitsu/futurity/bp/
│
├── koptKVBatch/                     <-- Separate batch module (key-value?)
│
└── futurity-app/                    <-- Runtime deploy bundle (no Java source)
    ├── batch/def/                   <-- Batch job definition files (.def)
    ├── batch/sql/                   <-- Batch SQL scripts
    ├── batch/shl/                   <-- Batch shell scripts
    ├── rule/                        <-- XML rule definitions (RULE0049001.xml, etc.)
    ├── consumer/nas/                <-- Consumer-side configs
    ├── service/prop/                <-- Service property files
    ├── webA/env, webB/env, webF/env <-- Per-web-app env configs
    └── lc/                          <-- Large catalog/archive zip files
```

### How a Request Flows

```
Web Client
    │
    ▼
*.faces Request
    │
    ▼
Filter Chain (web.xml order):
  1. SessionSynchronizingFilter  — syncs session state
  2. AjaxBackRequestFilter       — restores AJAX state
  3. UrlDecodingFilter           — decodes URL params
  4. CharacterEncodingFilter     — sets windows-31j charset
  5. upload-check-gamen-filter   — upload page validation
  6. CheckExceptionFilter        — exception routing
    │
    ▼
JSF Lifecycle (via X33JWPhaseListener)
    │
    ▼
Managed Bean (X33VViewJSPBean → screen-specific X33VViewBaseBean subclass)
    │
    ├── Checker  (input validation)
    ├── Logic    (business processing)
    └── Data     (CBMMessage models, common utils)
    │
    ▼
JSP View Rendering (wsd/ns/jpn/pc/...PJP.jsp)
```

## Configuration

### web.xml — Servlet Filters

File: `source/koptWebR/WebContent/WEB-INF/web.xml`

Defines the filter chain applied to every `*.faces` request:

| Filter | Class | Purpose |
|---|---|---|
| `SessionSynchronizingFilter` | `X33JVSessionSynchronizingFilter` | Session synchronization across requests |
| `AjaxBackRequestFilter` | `X33JVAjaxBackRequestFilter` | AJAX back-button support |
| `UrlDecodingFilter` | `X33JVUrlDecodingFilter` | URL parameter decoding (`response-decode=true`) |
| `CharacterEncodingFilter` | `X33JVCharEncodingFilter` | Charset `windows-31j` (Shift-JIS) |
| `upload-check-gamen-filter` | `X33VUploadCheckGamenFilter` | Upload page validation |
| `CheckExceptionFilter` | `X33VCheckExceptionFilter` | Exception handling and error page routing |

### faces-config.xml — JSF Configuration

File: `source/koptWebR/WebContent/WEB-INF/faces-config.xml`

- Uses **JSF 1.1** DTD (legacy — very old)
- Default locale: `ja_JP` (Japanese)
- Registers `X33JWPhaseListener` on the lifecycle
- Root managed bean: `X33VViewJSPBean` (session scope)

### sun-web.xml — GlassFish Deployment

File: `source/koptWebR/WebContent/WEB-INF/sun-web.xml`

- Cookie-based sessions enabled
- EJB reference `ejb/AgentCBS` mapped to a remote JNDI lookup via IIOP

### context.xml — Environment-Specific Deployments

Located at `source/koptWebR/KankyoIzon/Context/<env>/context.xml`:

Each environment directory (`k0`, `k1`, `k2`, ..., `it2-01`..`it2-08`) contains a Tomcat/GlassFish `context.xml` that declares external JARs mounted into `WEB-INF/lib`. The JARs reference is external to the source tree — they live on the deployment server at `/apl/<env>/futurity-app/jar/`. Key JARs include:

- `x33_jsf.jar` — the Futurity X33 JSF framework
- `futurity-common.jar` — shared application JAR
- `futurity-ejb.jar` — EJB session beans
- `futurity-fw.jar` / `futurity-fw-ejb.jar` — framework layer
- `ardus.jar` / `ardusobj.jar` — database/ORM layer
- `axis2-*.jar` — Apache Axis2 SOAP web services client

## Common Patterns

### Screen Function (SF) Package Structure

Every web screen is a self-contained package under `src/eo/web/webview/`:

```
FUW00901SF/
  ├── FUW00901SFBean.java      extends X33VViewBaseBean
  ├── FUW00901SFChecker.java   Input validation logic
  └── FUW00901SFLogic.java     Business processing logic
```

The naming convention is `XXWWNNNN` where:
- `XX` = brand prefix (`FU` = Futurity radio, `AC` = Account, `CH` = Cable Home, `CK` = K-Opticom, `CN` = Contract, `CR` = CRM)
- `WW` = module/workflow identifier
- `NNNN` = sequential number

### Bean Pattern

Screen Beans extend `X33VViewBaseBean` and implement `X33VListedBeanInterface`. They use typed data beans:

- `X33VDataTypeStringBean` — string fields
- `X33VDataTypeLongBean` — numeric (long) fields
- `X33VDataTypeBooleanBean` — boolean fields

Data is managed via `X33VDataTypeList`, loaded/saved through the framework's serialization system.

### Checker Pattern

Every Bean has a corresponding `*Checker.java` that validates form input. Checkers are lightweight (typically ~2KB) and follow a uniform interface.

### Logic Pattern

The `*Logic.java` class contains the business processing for a screen. It is where database calls, file I/O, and external service invocations happen. Logic classes call into shared utilities from `koptCommon`.

### Constant Classes

String literals are centralized in constant classes under `koptCommon/src/eo/common/constant/`:

| Constant Class | Brand |
|---|---|
| `JFUStrConst` | Futurity Radio (largest — ~476KB) |
| `JKKStrConst` | K-Opticom broadband |
| `JCHStrConst` | Cable Home |
| `JACStrConst` | Account system |
| `JCRStrConst` | CRM |
| `JKUStrConst` | WiMAX mobile |
| `JTUStrConst` | TBCU services |
| `JZMStrConst` | Marketing/promotion |
| `JPCStrConst` | Payment processing |

### Batch Processing

Batch jobs are defined by `.def` files in `futurity-app/batch/def/` (job definitions) and `.sql` files in `futurity-app/batch/sql/`. Shell scripts live in `futurity-app/batch/shl/`. The Java batch code in `koptBatch` reads these definitions and executes jobs.

### Rule Engine

XML rule files (`RULE0049001.xml` through `RULE0089002.xml`) in `futurity-app/rule/` define business rules for pricing, eligibility checks, and validation logic.

### Message Schema Pattern

CBM messages (`AC0091CBMMsg`, `CH0051CBMMsg`, etc.) extend `CAANSchemaInfo` and define their fields as a static `Object[][] CONTENTS` array: `{ "fieldName", "type" }`. This is the project's data contract format for service interfaces.

### Character Encoding

The entire application uses **Windows-31J** (Japanese Shift-JIS). All character conversion utilities are in `koptCommon` (`JBAEbcdicConv`, `JBAsjisConv`, etc.). Be careful when modifying — mixing encodings will corrupt data.

### Naming Conventions

- **Java classes**: `J` prefix for business layer, `X33` prefix for framework classes, `*SF` suffix for screen packages
- **JSP pages**: `XXWWNNNNPJP.jsp` (e.g. `FUW009010PJP.jsp`)
- **JavaScript files**: `XXWWNNNN.js` matching the JSP screen ID
- **Constants files**: `J<Brand>StrConst.java` or `J<Brand>...Constant.java`
- **Batch constants**: `J<Brand>BatConst.java`
- **Environment dirs**: `k0` (prod), `k1`-`k6` (staging/dev), `it2-XX` (integration)