# Getting Started

Welcome to the **Futurity** web application — a Java EE-based web project built by Fujitsu for the Japanese market. This guide answers "I just joined the team and I'm looking at this codebase for the first time — where do I start reading?"

## What This Project Does

Futurity is a Japanese-market web platform built on Java EE that delivers a browser-based user interface. It handles incoming HTTP requests through servlet filters, processes them via JSF and Struts-style action logic, and renders HTML responses using JSP pages. The codebase focuses on the web presentation tier — request encoding, lifecycle management, view logic, and data beans — with actual business logic delegated to downstream services.

## Recommended Reading Order

If you're exploring this codebase for the first time, follow this order:

1. **[Repository Overview](overview.md)** — Start here for the big picture of what the project does, the tech stack, and how modules relate.

2. **[com.fujitsu.futurity](com/fujitsu/futurity.md)** — Read the web-tier entry point. This package sits at the HTTP boundary and manages request processing infrastructure (filters and listeners).

3. **[eo](eo.md)** — Read the presentation layer documentation. This is where user-facing request routing, view rendering, and MVC patterns live.

4. **[javax.faces](javax/faces.md)** — Read about the FacesServlet and JSF integration. This is the front controller for all JSF-managed pages.

5. **[eo.web](eo/web.md)** — Read the detailed webview module guide, including the ACA001SF reference pattern for how new features should be structured.

6. **`web-full.xml`** — Read the deployment descriptor last, to see how all the pieces are wired together at runtime.

## Key Entry Points

These are the most important classes and files to understand first:

- **`X33JVRequestEncodingSjisFilter`** (`src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java`) — The servlet filter that intercepts HTTP requests for the Japanese locale variant. Implements `javax.servlet.Filter` and currently passes requests through unmodified, but is the primary entry point for request preprocessing.

- **`FacesServlet`** (`src/java/javax/faces/webapp/FacesServlet.java`) — The JSF front controller. Handles all `.jsf`/`.faces` URL patterns and drives the six-phase JSF lifecycle. Defined here as a stub since the real implementation is provided by the application server's JSF runtime.

- **`ACA001SFLogic`** (`src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java`) — The view logic class that processes incoming requests. Its `execute()` method is the first place to add business logic for the ACA001SF feature.

- **`ACA001SFBean`** (`src/java/eo/web/webview/ACA001SF/ACA001SFBean.java`) — A simple JavaBeans data carrier with a single `value` property. Demonstrates the read-only bean pattern used throughout the project.

- **`web-full.xml`** (`koptWebA/WebContent/WEB-INF/web-full.xml`) — The deployment descriptor that ties everything together. Defines the `SjisFilter` servlet filter mapping and the `FacesServlet` servlet configuration.

## Project Structure

The repository is organized around two main source trees:

```mermaid
flowchart TD
    Client["Browser / Client"] --> Dispatcher["Servlet Dispatcher"]
    Dispatcher --> X33Filter["X33 Filter"]
    X33Filter --> TargetServlet["Target Servlet"]
    TargetServlet --> Business["Business Logic"]
    Business --> Service["Service Layer"]
```

```
full-fixture-codebase/
  src/java/
    com/fujitsu/futurity/web/
      x33/
        filter/          -- Servlet filters for Japanese locale
          X33JVRequestEncodingSjisFilter.java
        listener/        -- Application lifecycle stub
          X33AppContextListener.java
    eo/web/webview/
      ACA001SF/          -- MVC feature module (bean, logic)
        ACA001SFBean.java
        ACA001SFLogic.java
    javax/faces/webapp/  -- JSF front controller stub
      FacesServlet.java
  koptWebA/
    WebContent/
      WEB-INF/
        web-full.xml     -- Deployment descriptor
      wsd/ns/jpn/        -- Web service descriptors (Japanese)
  src/futurity-app/
    webA/env/view/def/
      WEBGAMEN_FULL_ACA001.xml  -- Action configuration (XML-driven routing)
```

- **`src/java/com/fujitsu/futurity.web`** — The core web-tier namespace. Contains the X33 filter and listener for Japanese locale support.
- **`src/java/eo.web.webview`** — The MVC webview modules. Each feature gets its own sub-package (e.g., `ACA001SF`) with a matching `*Bean` and `*Logic` class.
- **`src/java/javax.faces.webapp`** — JSF integration layer. The FacesServlet stub here indicates the real JSF runtime is supplied by the application server.
- **`koptWebA/WebContent`** — Web content root. Holds the deployment descriptor (`web-full.xml`) and static web resources.
- **`src/futurity-app/webA/env/view/def`** — XML action configuration files that drive Struts-style routing.

## Configuration

The project uses XML-driven configuration throughout. Here are the key files:

### `web-full.xml` — Deployment Descriptor

Located at `koptWebA/WebContent/WEB-INF/web-full.xml`, this is the standard Java EE web application descriptor. It currently declares:

- **`SjisFilter`** — Maps to `X33JVRequestEncodingSjisFilter`, the servlet filter for Shift JIS encoding.
- **`FacesServlet`** — Maps to `javax.faces.webapp.FacesServlet`, the JSF front controller.

The actual URL patterns and filter mappings that connect these to specific request paths are defined elsewhere (in the application server's configuration or additional XML files).

### `WEBGAMEN_FULL_ACA001.xml` — Action Configuration

Located at `src/futurity-app/webA/env/view/def/WEBGAMEN_FULL_ACA001.xml`, this XML file maps incoming HTTP requests to the `ACA001SFLogic` class. It is the authoritative definition of how URLs route to view logic.

### Configuration Patterns

- **XML-driven, annotation-free** — Routing, servlet mappings, and action configurations are all defined in XML files, not via annotations. To understand how a URL reaches code, read the XML configs first.
- **Scaffolding status** — Several configuration entries exist as placeholders (the filter is a no-op, the listener is an empty class). The structure is correct; the implementations are deferred.

## Common Patterns

### Server-Side MVC Flow

The web layer follows a classic Struts 1.x MVC pattern:

```mermaid
flowchart TD
    User["User / Browser"] -->|HTTP Request| XMLConf["XML Action Config"]
    XMLConf --> Logic["*Logic class"]
    Logic -->|Populates| Bean["Data Bean"]
    Bean -->|Request scope| JSP["JSP Views"]
    JSP -->|HTML Response| User
```

For every feature:
1. An incoming HTTP request arrives at the application server.
2. The XML action configuration resolves the request path to a specific `*Logic` class.
3. `execute()` on the logic class processes the request (currently a stub, to be implemented).
4. A `*Bean` is placed into request or session scope with prepared data.
5. Control is forwarded to the JSP view, which reads bean properties and renders HTML.
6. The rendered HTML response is returned to the user's browser.

### JavaBeans as the Data Transport

Data flows between the logic and view layers through JavaBeans that follow the standard JavaBeans convention: private fields with public getters. Beans are **read-only** — they define only getters, not setters. This means data moves in one direction: from the logic layer into the view.

Example (`ACA001SFBean`):

```java
public class ACA001SFBean {
    private String value;
    public String getValue() { return value; }
}
```

If a future module needs to accept user input that binds back to a bean, a setter method must be added.

### Filter-Chain Architecture

Incoming requests flow through the standard Java EE filter-chain pattern:

```mermaid
sequenceDiagram
    participant Browser
    participant Container as Servlet Container
    participant Filter as X33 Filter
    participant Chain as Filter Chain
    participant Servlet as Target Servlet
    Browser->>Container: HTTP request
    Container->>Filter: doFilter
    Filter->>Chain: chain.doFilter
    Chain->>Servlet: deliver request
    Servlet-->>Filter: return response
    Filter-->>Browser: respond to client
```

The X33 filter currently passes requests through unmodified (`chain.doFilter(req, res)`), but is structured to handle Shift JIS encoding transformation when implemented.

### Scaffolding Pattern

Many classes in the codebase follow a scaffolding pattern:

- Class structures are defined correctly (implementing `javax.servlet.Filter`, following `ServletContextListener` naming conventions).
- Implementation bodies are deferred (empty `execute()` methods, no-op filter pass-throughs, empty listener classes).
- This approach establishes correct integration points before the actual business logic is filled in.

When you encounter an empty or stub method, look for the corresponding module's wiki page — it will indicate whether the functionality is planned, in progress, or awaiting upstream dependencies.

### Feature Module Naming Convention

New features follow the `ACA` prefix pattern:

- Bean: `ACA001SFBean` — Data carrier for the feature.
- Logic: `ACA001SFLogic` — Request handler for the feature.
- XML config: `WEBGAMEN_FULL_ACA001.xml` — Action mapping.
- JSP views: Named under the same `ACA001SF` package path.

When adding a new feature (e.g., `ACA002SF`), mirror this structure exactly in its own sub-package under `eo.web.webview`.