# Getting Started

## What This Project Does

This is the **Futurity X33** codebase — a Java EE web application built for the Fujitsu Futurity product line, targeting Japanese-language enterprise use cases. It uses JavaServer Faces (JSF) as its UI framework, a Servlet Filter layer for character encoding (Shift JIS), and a modular MVC pattern where logic classes coordinate with backing beans and JSP views. The application follows a traditional Java EE architecture with explicit XML configuration, characteristic of enterprise applications built in the mid-to-late 2000s.

## Recommended Reading Order

New engineers should read the wiki pages in this order to build mental model progressively:

1. **[Overview](../overview.md)** — The big picture: technology stack, architecture, and how the pieces fit together. Read this first.
2. **[Root Package](../root.md)** — How the three top-level namespaces (`com`, `eo`, `javax`) form the layered web request pipeline.
3. **[Fujitsu Futurity Web Layer](../com/fujitsu/futurity.md)** — The servlet infrastructure (listeners, filters) that sits at the boundary between HTTP clients and the application.
4. **[EO Web / Webview](../eo/web/webview.md)** — The MVC view layer where every business feature is implemented. Read the `ACA001SF` example to understand the pattern used throughout.
5. **[JSF Framework](../javax/faces.md)** — How the JSF front controller (`FacesServlet`) processes requests through its six-phase lifecycle.

After these, dive into specific features by navigating to their individual `eo.web.webview.*` packages.

## Key Entry Points

Start your investigation with these classes. They are the entry points into the three major layers of the system:

### `X33JVRequestEncodingSjisFilter` — Request Entry

```
com.fujitsu.futurity.web.x33.filter.X33JVRequestEncodingSjisFilter
```

Every HTTP request passes through this `javax.servlet.Filter` before reaching the application. Its job is to set the character encoding to Shift JIS (SJIS) for Japanese-language requests. Located in `full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/`.

### `X33AppContextListener` — Application Bootstrap

```
com.fujitsu.futurity.web.x33.listener.X33AppContextListener
```

This `ServletContextListener` runs once at server startup and shutdown. It would load configuration, register shared beans, and manage application-wide state. Located in `full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/listener/`.

### `FacesServlet` — JSF Front Controller

```
javax.faces.webapp.FacesServlet
```

The JSF front controller servlet that dispatches every JSF-managed request through its six-phase lifecycle (Restore View, Apply Request Values, Process Validation, Update Model Values, Invoke Application, Render Response). Located in `full-fixture-codebase/src/java/javax/faces/webapp/`.

### `ACA001SFLogic` — View Controller Pattern

```
eo.web.webview.ACA001SF.ACA001SFLogic
```

The controller class for a web view. Its `execute()` method prepares data, and it populates the corresponding Bean before the JSP renders. Located in `full-fixture-codebase/src/java/eo/web/webview/ACA001SF/`.

### `ACA001SFBean` — View Data Carrier

```
eo.web.webview.ACA001SF.ACA001SFBean
```

A minimal POJO that carries view-scoped data (e.g., a `String value` field). It is populated by the Logic class before the JSP renders.

## Project Structure

The codebase is organized into three distinct concerns across the source tree:

```
full-fixture-codebase/
├── src/java/                              # Java source code
│   ├── com/fujitsu/futurity/web/x33/     # Servlet infrastructure (filters, listeners)
│   │   ├── filter/
│   │   │   └── X33JVRequestEncodingSjisFilter.java
│   │   └── listener/
│   │       └── X33AppContextListener.java
│   ├── eo/web/webview/                   # MVC view components (one sub-package per feature)
│   │   └── ACA001SF/
│   │       ├── ACA001SFBean.java          # View data
│   │       └── ACA001SFLogic.java         # View controller
│   └── javax/faces/webapp/               # JSF framework entry point
│       └── FacesServlet.java
├── koptWebA/                              # Web artifacts
│   ├── WebContent/WEB-INF/
│   │   └── web-full.xml                   # Central deployment descriptor
│   └── WebContent/wsd/                   # JSP view pages
│       ├── fragments/                     # JSP fragment includes
│       │   └── header.jspf
│       ├── ns/jpn/pc/                    # Japanese PC views
│       │   ├── ACA001010PJP.jsp
│       │   ├── FULL_ACA001010PJP.jsp
│       │   └── ShiftJis001.jsp
│       └── *.jsp                          # Other JSP pages
└── src/futurity-app/
    └── webA/env/view/def/
        └── WEBGAMEN_FULL_ACA001.xml       # Per-view XML config (bean + logic wiring)
```

### Namespace Summary

| Namespace | Layer | Purpose |
|-----------|-------|---------|
| `com.fujitsu` | Infrastructure | Servlet lifecycle and request preprocessing |
| `eo.web.webview` | Application | Business-facing views (Bean + Logic + JSP) |
| `javax.faces` | Framework | JSF front controller and API |

## Configuration

### `web-full.xml`

```
koptWebA/WebContent/WEB-INF/web-full.xml
```

The **central deployment descriptor**. It registers all servlets, filters, and listeners with the servlet container. Every HTTP request enters the application through this file. Key sections:

- `<filter>` — Declares the `X33JVRequestEncodingSjisFilter` for character encoding.
- `<servlet>` — Declares the `FacesServlet` as the JSF front controller.

All new servlet components must be registered here (this application uses XML-based registration, not annotations).

### `WEBGAMEN_FULL_ACA001.xml`

```
src/futurity-app/webA/env/view/def/WEBGAMEN_FULL_ACA001.xml
```

A per-view XML configuration file that wires a Logic class to a Bean. It declares the `<BL>` (business logic) class and the `<SERVICEFORM>` bean, effectively defining what controller handles a given URL pattern.

Each webview has its own config file following this convention: `WEBGAMEN_FULL_<SCREEN_ID>.xml`.

### Naming Convention

- Bean classes end with `Bean` (e.g., `ACA001SFBean`).
- Logic classes end with `Logic` (e.g., `ACA001SFLogic`).
- JSP views follow the pattern `<SCREEN_ID>PJP.jsp` (e.g., `ACA001010PJP.jsp`).
- `X33JV` prefix indicates Japanese (JV) build scoping.

## Common Patterns

### MVC Pattern per Feature

Every web feature follows a strict four-artifact pattern. To add or modify a feature, you create/update these four files:

| Artifact | Convention | Role |
|----------|------------|------|
| **Bean** | `ACAxxyyBean.java` | Simple POJO with fields + getters for view data |
| **Logic** | `ACAxxyyLogic.java` | Controller with `execute()` method that prepares data |
| **XML Config** | `WEBGAMEN_FULL_ACAXXY.xml` | Wires Bean + Logic, maps URL patterns |
| **JSP View** | `<SCREEN_ID>PJP.jsp` | Renders HTML using JSP EL to read from the Bean |

### Request Processing Flow

Understanding the request pipeline helps you debug any feature:

```
HTTP Request
    -> X33JVRequestEncodingSjisFilter (set encoding)
    -> FacesServlet (JSF lifecycle)
    -> ACA001SFLogic.execute() (business logic)
    -> ACA001SFBean (data population)
    -> FULL_ACA001010PJP.jsp (HTML render)
```

### No Cross-View Dependencies

Each webview is self-contained. There is no shared logic base class, no cross-view bean composition, and no direct communication between views. If multiple views need the same data preparation, the Logic classes are duplicated rather than shared.

### XML Over Annotations

This application uses explicit XML configuration (`web-full.xml`, per-view XML configs) rather than Java annotations for component registration. When adding a new filter, servlet, or listener, you must update the deployment descriptor manually.

### Stub-First Development

Some components are currently structural stubs (empty class bodies) that implement the correct interfaces but contain no operational logic. This may indicate:

1. Logic delegated to framework-level equivalents elsewhere.
2. Intentional scaffolding awaiting implementation.
3. Relics of Japanese-specific deployments no longer actively maintained.

Before removing stubs, verify they are still referenced in the deployment descriptor or used by other components.

## Quick Start: Tracing a Request

To understand how the system works end-to-end, trace a request through these steps:

1. Open `koptWebA/WebContent/WEB-INF/web-full.xml` to see what filters and servlets are registered.
2. Open `full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java` to see the encoding layer.
3. Open `full-fixture-codebase/src/futurity-app/webA/env/view/def/WEBGAMEN_FULL_ACA001.xml` to find which Logic and Bean a view uses.
4. Open `full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java` to see the controller logic.
5. Open `full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java` to see the data model.
6. Open `koptWebA/WebContent/wsd/ns/jpn/pc/FULL_ACA001010PJP.jsp` to see the rendered output.

This gives you the complete flow from HTTP request to HTML response.

## Related Documentation

- [Repository Overview](../overview.md)
- [Root Package](../root.md)
- [com.fujitsu](../com/fujitsu.md)
- [com.fujitsu.futurity](../com/fujitsu/futurity.md)
- [eo.web.webview](../eo/web/webview.md)
- [javax.faces](../javax/faces.md)