# Getting Started

## What This Project Does

This repository is a Java EE web application test fixture suite built on the JavaServer Faces (JSF) stack. It provides a realistic sample application structure — servlet filters for Japanese Shift JIS encoding, JSF backing beans wired through XML deployment descriptors, and dozens of JSP and XML edge-case fixtures used to stress-test build tooling and import resolution. Whether you're tracing request flows or hunting down a JSP import quirk, this guide will help you find your way.

## Recommended Reading Order

Start here to build a mental model of the codebase:

1. **[Repository Overview](../overview.md)** — Big-picture map of the entire codebase, technology stack, and architecture.
2. **[Root Package](../root.md)** — How the three sub-modules (`javax`, `eo`, `com`) fit together into a layered web application.
3. **[com Namespace](../com.md)** — The application and infrastructure layer (X33 filter, context listener, test fixtures).
4. **[javax Namespace](../javax.md)** — The JSF framework integration and deployment descriptor wiring.
5. **[eo Namespace](../eo.md)** — The JSF presentation layer with backing beans and view logic.
6. **[eo.web.webview.ACA001SF](../eo/web/webview/ACA001SF.md)** — The most complete module: the JSF view flow from managed bean to view logic.

## Key Entry Points

The most important classes to understand first, ordered by how frequently they are referenced across the codebase:

### `ACA001SFBean` — JSF Managed Bean (highest connectivity)

This is the most referenced class in the entire codebase with 6 cross-references. It is a standard JSF managed bean with a single `String value` property (getter only, no setter). Registered in `faces-config.xml` and referenced by multiple XML screen definitions and JSP views.

### `ACA001SFLogic` — View Logic Controller

A view logic controller class with a single `execute()` method. It appears in two source trees (`full-fixture-codebase` and `xml-unresolved-fqn`), suggesting one is canonical and the other is a mirror artifact.

### `X33JVRequestEncodingSjisFilter` — Character Encoding Filter

Implements `javax.servlet.Filter` for setting Shift JIS (MS932) encoding on incoming requests to the X33 application module. Currently a pass-through no-op stub.

### `FacesServlet` — JSF Front Controller

Declared in `javax.faces.webapp` and registered in both `web.xml` and `web-full.xml`. Empty stub representing the JSF front controller that drives the six-phase JSF lifecycle.

### `X33AppContextListener` — Application Context Listener

A `ServletContextListener` stub for X33 startup/shutdown hooks. Currently empty — no interface is declared and no methods are implemented.

### `KnownClass` — Test Fixture Stub

A minimal class in the `com.example.bugca002` package. Has no fields and an empty `execute()` method. Exists solely as a resolvable import target for JSP pages to verify build tooling works.

## Project Structure

```
root/
├── full-fixture-codebase/        # Main Java source tree
│   ├── src/java/                 # All Java classes
│   │   ├── eo/web/webview/ACA001SF/
│   │   │   ├── ACA001SFBean.java
│   │   │   └── ACA001SFLogic.java
│   │   ├── com/fujitsu/futurity/web/x33/
│   │   │   ├── filter/
│   │   │   │   └── X33JVRequestEncodingSjisFilter.java
│   │   │   └── listener/
│   │   │       └── X33AppContextListener.java
│   │   └── javax/faces/webapp/
│   │       └── FacesServlet.java
│   ├── koptWebA/WebContent/      # JSP views + deployment descriptor
│   │   ├── WEB-INF/
│   │   │   ├── web-full.xml
│   │   │   └── faces-config.xml
│   │   └── wsd/                  # JSP view pages
│   └── src/futurity-app/         # View definition XML files
├── xml-unresolved-fqn/           # Mirror source tree
│   ├── src/java/
│   │   └── eo/web/webview/ACA001SF/
│   │       └── ACA001SFLogic.java
│   └── src/config/
│       └── external-refs.xml
├── xml-build-excluded/           # Build exclusion fixture (has pom.xml)
├── xml-web-xml-multi-pattern/    # Multiple web.xml patterns
├── xml-faces-config/             # faces-config.xml fixture
├── xml-sun-ejb-jar/              # Sun EJB JAR config fixture
├── jsp-* /                       # JSP edge-case fixtures
│   ├── jsp-multi-import/
│   ├── jsp-shift-jis/
│   ├── jsp-usebean/
│   └── ...
├── bug-ca-001-unresolved-only/   # Bug regression fixture
├── bug-ca-002-attr-order/        # Attribute ordering test
└── _manifest.json                # Index of all 52 fixture files
```

### Directory Categories

| Directory Group | Purpose |
|---|---|
| `full-fixture-codebase/` | Canonical Java sources and a full webapp with JSPs, servlet config, and JSF config |
| `xml-unresolved-fqn/` | Mirror tree for testing unresolved fully-qualified name resolution |
| `xml-* /` | XML configuration fixtures testing schema, encoding, DTD/XSD, and Japanese element handling |
| `jsp-* /` | JSP edge-case fixtures: multi-import, Shift JIS, wildcard imports, usebean variants |
| `bug-ca-* /` | Regression test fixtures for known build/tooling bugs |

## Configuration

This project uses **XML-driven configuration exclusively** — no annotation-based discovery (`@WebServlet`, `@ManagedBean`). All components are explicitly declared in XML files, which must be coordinated across deployment profiles.

### Key Config Files

| File | Location | Purpose |
|---|---|---|
| **`web.xml`** | `full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml` | Primary deployment descriptor: registers `FacesServlet`, `X33JVRequestEncodingSjisFilter`, `X33AppContextListener` |
| **`web-full.xml`** | `full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml` | Full Java EE profile deployment descriptor — mirrors `web.xml` |
| **`faces-config.xml`** | `full-fixture-codebase/koptWebA/WebContent/WEB-INF/faces-config.xml` | JSF bean wiring: registers `ACA001SFBean` as a managed bean, defines navigation rules |
| **`sun-ejb-jar.xml`** | `xml-sun-ejb-jar/koptBp/ejbModule/META-INF/sun-ejb-jar.xml` | Sun-specific EJB JAR configuration (JNDI bindings) |
| **`external-refs.xml`** | `xml-unresolved-fqn/src/config/external-refs.xml` | External reference resolution fixture |
| **`WEBGAMEN_*.xml`** | `full-fixture-codebase/src/futurity-app/webA/env/view/def/` | View screen definitions for the Futurity application |
| **`x33S_ACA001.xml`** | `xml-japanese-elements/src/futurity-app/webA/env/def/` | X33 screen definition with Japanese XML elements |
| **`pom.xml`** | `xml-build-excluded/pom.xml` | Maven build exclusion fixture |

### Deployment Descriptor Coordination

Both `web.xml` and `web-full.xml` register the same components. Any implementation or configuration changes must be reflected in **both files** to avoid environment-specific bugs. Divergence between these profiles is a common source of issues.

## Common Patterns

### 1. Stub-and-Fill Architecture

Everything is a stub. `FacesServlet`, `X33JVRequestEncodingSjisFilter`, `X33AppContextListener`, and `ACA001SFLogic.execute()` are all declared and wired through XML but contain empty or no-op bodies. This is deliberate: build the plumbing first, then fill in the pipes. Adding implementation is safe — there is no existing behavior to break.

### 2. XML-Driven Wiring

No module uses annotation-based discovery. All components (servlets, filters, listeners, managed beans) are explicitly declared in deployment descriptors. This is flexible but means refactoring requires auditing all XML files — not just source code references.

### 3. Lifecycle vs. Request Separation

The X33 module cleanly separates concerns:

- **`X33AppContextListener`** — fires once at application deployment (singleton)
- **`X33JVRequestEncodingSjisFilter`** — fires per HTTP request (repeated)

This is the standard Java EE servlet pattern and applies the same separation everywhere else.

### 4. Thin Presentation Data Model

`ACA001SFBean` exposes only a single read-only string property. This follows JSF best practices where the web tier should be thin and delegate to service layers.

### 5. Dual Source Trees

`ACA001SFLogic` exists in both `full-fixture-codebase` and `xml-unresolved-fqn`. One appears canonical; changes may need to be propagated to the other. Be aware of which tree you are editing.

### 6. Fixture Isolation

Each `jsp-*`, `xml-*`, and `bug-ca-*` directory is an independent test case. They do not import or reference each other. Create new fixtures as new subdirectories, not by modifying existing ones.

## Request Flow

When the application is fully implemented, a typical request follows this path:

```
Browser → X33 Filter (encoding) → FacesServlet → JSF Lifecycle → ACA001SFLogic → ACA001SFBean → JSP View → HTML Response
```

```mermaid
flowchart LR
    browser["Browser"] --> filter["X33JVRequestEncodingSjisFilter"]
    filter --> servlet["FacesServlet"]
    servlet --> lifecycle["JSF 6-phase Lifecycle"]
    lifecycle --> logic["ACA001SFLogic"]
    logic --> bean["ACA001SFBean"]
    bean --> jsp["JSP View"]
    jsp --> response["HTML Response"]
```

## Things to Know Before You Start

- **Character encoding**: If the X33 application handles Japanese content, implementing `X33JVRequestEncodingSjisFilter` is likely one of the first practical tasks. Check `req.getCharacterEncoding() == null` before setting to avoid overriding explicit client headers.
- **Servlet API version**: The code references `javax.servlet` (Java EE / Servlet 3.x). Confirm whether the project has migrated to `jakarta.servlet` (Jakarta EE / Servlet 5.x+) before implementing interface methods.
- **XML density**: The `eo.web.webview` module references the same bean and logic classes across six XML files. Before refactoring or renaming, audit all configuration files.
- **Stub classes are intentional**: Classes in `com.example` (e.g., `KnownClass`) are deliberately sparse by design. Do not assume missing fields, methods, or logic are oversights — they exist to test the build tooling pipeline.
- **Dual deployment profiles**: Changes to `web.xml` should be mirrored in `web-full.xml`.