# Getting Started

Welcome to the team! This guide will help you orient yourself quickly. Read on to understand what this project is, where to start reading, and how the pieces fit together.

---

## What This Project Does

This repository is a **stub-first Java EE web application** built around JavaServer Faces (JSF) for the presentation layer, with several supporting fixtures for static-analysis rule validation. At its core is a classic JSF MVC web app — complete with a front-controller servlet, a character-encoding filter, context listeners, and JSF-backed views — all scaffolded and wired into deployment descriptors but awaiting real business logic. Alongside the main application code, the repo contains a collection of small, self-contained test fixtures targeting specific SonarQube-style linting rules (e.g., JSP import ordering, XML configuration edge cases).

In short: **the infrastructure is in place, the wiring is correct, and the methods are empty.** Your job, once you're onboarded, will likely be to implement the logic behind those stubs.

---

## Recommended Reading Order

Follow these pages in sequence to build a solid mental model of the codebase:

1. **`root.md`** — Start here. It gives you the big-picture architecture, the three major package areas, and how they interact.
2. **`javax/faces.md`** — Understand the `FacesServlet` as the central request dispatcher. This is the foundation: every JSF request flows through it.
3. **`com/fujitsu.md`** — Read about the servlet web tier (filter + listener). This is where HTTP requests enter the system before reaching JSF.
4. **`eo.md`** — Dive into the JSF MVC presentation layer. This is the main application module with the most activity: backing beans, logic handlers, and JSP views.
5. **`com/example.md`** — Finish with the test-fixture package. It's tiny and self-contained, showing how the project uses minimal stubs for static-analysis validation.

---

## Key Entry Points

These are the classes and files you should look at first. They are the most-referenced entry points into the codebase.

### Classes

| Class | Package | Why It Matters |
|-------|---------|----------------|
| **[ACA001SFBean](../src/java/eo/web/webview/ACA001SF/ACA001SFBean.java)** | `eo.web.webview.ACA001SF` | **Most referenced class** (6 connections). JSF backing bean that carries data from the logic handler to the JSP view. Only has a getter — no setter — so data flows one way. |
| **[ACA001SFLogic](../src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java)** | `eo.web.webview.ACA001SF` | The view logic handler. Its `execute()` method is the primary extension point for implementing futurity view data. |
| **[X33JVRequestEncodingSjisFilter](../src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java)** | `com.fujitsu.futurity.web.x33.filter` | Servlet filter that intercepts all HTTP requests. Currently a no-op stub. When implemented, it normalizes character encoding for Shift JIS clients. |
| **[X33AppContextListener](../src/java/com/fujitsu/futurity/web/x33/listener/X33AppContextListener.java)** | `com.fujitsu.futurity.web.x33.listener` | Context listener for application bootstrap/teardown. Currently empty. |
| **[FacesServlet](../src/java/javax/faces/webapp/FacesServlet.java)** | `javax.faces.webapp` | The JSF front controller. Orchestrates the six-phase JSF lifecycle. This is a minimal stub; a production implementation would follow the full Jakarta Faces spec. |

### Configuration Files

| File | Purpose |
|------|---------|
| **`koptWebA/WebContent/WEB-INF/web.xml`** | Standard deployment descriptor. Registers the filter, FacesServlet, and context listener. |
| **`koptWebA/WebContent/WEB-INF/web-full.xml`** | Full deployment profile. Registers the same components — should be audited to avoid duplicate runtime registration. |
| **`faces-config.xml`** | JSF-specific config. Declares managed beans (including `ACA001SFBean`) and navigation rules. |

---

## Project Structure

```
root/
├── src/java/                            # Java source
│   ├── eo/                              # JSF MVC presentation layer
│   │   └── web/
│   │       └── webview/
│   │           └── ACA001SF/            # Main JSF view module
│   │               ├── ACA001SFBean.java
│   │               └── ACA001SFLogic.java
│   ├── com/
│   │   ├── fujitsu/                     # Servlet web tier (stub-only)
│   │   │   └── futurity/
│   │   │       └── web/
│   │   │           └── x33/
│   │   │               ├── filter/
│   │   │               │   └── X33JVRequestEncodingSjisFilter.java
│   │   │               └── listener/
│   │   │                   └── X33AppContextListener.java
│   │   └── example/                     # Static-analysis test fixtures
│   │       └── bugca002/                # Import-ordering rule anchor
│   │           └── KnownClass.java
│   └── javax/
│       └── faces/
│           └── webapp/
│               └── FacesServlet.java
├── src/futurity-app/                    # XML view definition files
├── koptWebA/WebContent/                 # Web resources
│   └── WEB-INF/
│       ├── web.xml                      # Basic deployment profile
│       └── web-full.xml                 # Full deployment profile
├── full-fixture-codebase/               # Full integration test fixture
├── xml-*/                               # XML configuration fixtures
├── jsp-*/                               # JSP test fixtures
└── bug-ca-*/                            # Bug-rule test fixtures
```

**Package Summary:**

- **`eo.web`** — The JSF MVC layer. Backing beans, logic handlers, JSP views. This is where you'll do most of your work.
- **`com.fujitsu.futurity.web.x33`** — The servlet-level web tier. Filter (encoding normalization) and listener (lifecycle events). Stub-only.
- **`javax.faces.webapp`** — The JSF framework API surface. `FacesServlet` is the central dispatcher.
- **`com.example.bugca002`** — Test fixtures for static-analysis. Not production code.

---

## Configuration

### Deployment Descriptors

The application uses a **dual deployment profile** pattern. Both `web.xml` and `web-full.xml` register the same filter, servlet, and listener:

```xml
<!-- web.xml excerpt -->
<filter>
  <filter-name>SjisFilter</filter-name>
  <filter-class>com.fujitsu.futurity.web.x33.filter.X33JVRequestEncodingSjisFilter</filter-class>
</filter>
<servlet>
  <servlet-name>FacesServlet</servlet-name>
  <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>
```

**What to watch for:** If both descriptors are deployed simultaneously, the servlet container may issue warnings or behave unpredictably due to duplicate registrations. Audit whether this dual registration is intentional.

### JSF Configuration

Bean registration is **entirely XML-driven** (`faces-config.xml`). This is consistent with JSF 1.x / early JSF 2.x:

- Managed beans are declared in `faces-config.xml`, not annotated with `@ManagedBean` or `@Named`.
- When adding new components, check whether the project has migrated to annotation-based config or if XML wiring is still required.
- The `ACA001SFBean` default EL name would be the uncapitalized form (e.g., `aca001sFBean`). The exact name in `faces-config.xml` may override this.

### View Definitions

XML view definition files (prefixed `WEBGAMEN_`, `x33S_`) in `src/futurity-app/webA/env/view/def/` declare page structure and component bindings. They reference `ACA001SFBean` and `ACA001SFLogic` to wire the view to the logic layer.

---

## Common Patterns

### 1. Stub-and-Wire

This is the **dominant pattern** across the codebase. Classes are registered in deployment descriptors and wired into the application before any business logic is implemented:

- Filter and listener methods are no-ops (they pass through immediately).
- `ACA001SFLogic.execute()` is an empty method body.
- `ACA001SFBean` has only a getter — no setter — so data is one-way.

**What this means for you:** Do not treat empty `execute()` methods as complete implementations. They are scaffolding. Treat them as extension points waiting for real logic.

### 2. JSF MVC (Back Bean + Logic Handler)

The `eo.web.webview.ACA001SF` module follows a uniform two-class MVC pattern:

```
[ACA001SFBean]  <-->  [ACA001SFLogic]
       ^                       |
       |                       | prepares data
       |                       v
       +------- [JSP View] <---+
```

- **Backing Bean** (`ACA001SFBean`): Lightweight POJO visible to the JSP view via JSF Expression Language. Currently holds a single `String value` property.
- **Logic Handler** (`ACA001SFLogic`): Controller object with an `execute()` method that prepares data and writes it to the bean.
- **JSP View**: Renders the bean's properties using JSF EL tags.

**Extension point:** When implementing business logic, `ACA001SFLogic.execute()` is where you add service calls or data-access logic. Write results to the bean's `value` field for rendering.

### 3. Front Controller + Encoding Filter

The request flow through the system:

1. Servlet container receives an HTTP request.
2. `X33JVRequestEncodingSjisFilter` intercepts all requests (currently a no-op).
3. Requests matching the JSF URL pattern flow to `FacesServlet`.
4. `FacesServlet` orchestrates the six-phase JSF lifecycle.
5. `eo.web` backing beans participate in the lifecycle phases.
6. The response is rendered as HTML to the browser.

### 4. Fixture-Based Testing

Test fixtures in directories like `xml-*`, `jsp-*`, and `bug-ca-*` are minimal, self-contained code samples designed to trigger specific static-analysis rules. They are **not production code**. Key principles:

- Fixtures are intentionally minimal — empty classes, no dependencies.
- Each rule gets its own directory (e.g., `bug-ca-002-attr-order` for import-ordering checks).
- Do not add business logic or side effects to fixtures; they must remain deterministic anchors for linting.

### 5. Japanese Enterprise Conventions

Several signals point to this being a Japanese-market enterprise application:

- Shift JIS (SJIS) character encoding support in `X33JVRequestEncodingSjisFilter`.
- JSP files in `jsp-shift-jis/` fixture with `ShiftJis001.jsp`.
- XML files in `xml-japanese-elements/` with Japanese XML element names.
- The `X33` subsystem name (common in Japanese enterprise software naming).

When working with these files, be aware of encoding considerations — the codebase should ideally be migrated to UTF-8.

---

## Request Flow Diagram

Here's how an HTTP request flows through the system once fully implemented:

```mermaid
flowchart TD
    subgraph config[Web Configuration]
        webConfig["web.xml / web-full.xml<br/>Deployment Descriptors"]
    end
    subgraph container[Servlet Container]
        filter["X33JVRequestEncodingSjisFilter<br/>(Filter - no-op)"]
        facesServlet["FacesServlet<br/>(JSF Front Controller)"]
    end
    subgraph tier[Application Web Tier]
        listener["X33AppContextListener<br/>(ContextListener - no-op)"]
    end
    subgraph viewLayer[JSF View Layer]
        bean["ACA001SFBean<br/>Backing Bean"]
        logic["ACA001SFLogic<br/>View Logic Handler"]
        jsp["JSP Views<br/>*.jsp"]
    end
    webConfig --> filter
    webConfig --> facesServlet
    webConfig --> listener
    filter --> facesServlet
    facesServlet --> bean
    facesServlet --> logic
    logic -->|"prepares data"| bean
    bean -->|"renders via EL"| jsp
```

---

## Next Steps

1. **Read the wiki pages in order** (see Recommended Reading Order above).
2. **Trace the ACA001SF module** — open `ACA001SFBean.java`, `ACA001SFLogic.java`, and a JSP view file. Follow how data flows from logic to bean to view.
3. **Check `faces-config.xml`** — see how beans are wired into the JSF lifecycle.
4. **Pick an implementation task** — the intended extension points are:
   - `X33JVRequestEncodingSjisFilter.doFilter()` — implement Shift JIS encoding normalization.
   - `X33AppContextListener.contextInitialized()` — implement bootstrap logic.
   - `ACA001SFLogic.execute()` — implement futurity view data preparation.

If you get stuck, the [root overview](../root.md) and [eo.web module guide](../eo.md) are the best places to look for detailed explanations.

---

*Last updated: 2026-06-24*