# Getting Started

> I just joined the team — where do I start reading?

This guide will help you build a working mental model of the codebase in under 15 minutes. Read it top-to-bottom, then dive into whichever section interests you most.

---

## What This Project Does

This is a **Java EE web application** built around **JavaServer Faces (JSF)** for the presentation layer, with servlet filters and XML-driven configuration. It supports Japanese-language interfaces through Shift JIS character encoding. The repository also serves as a **test harness** — dozens of isolated fixture directories validate JSP parsing and XML configuration behavior across edge cases like malformed files, encoding quirks, and directive attribute ordering.

---

## Recommended Reading Order

| Step | Page | Why Read It |
|---|---|---|
| 1 | [`overview.md`](../overview.md) | Big-picture: what the project does, its architecture, and technology stack |
| 2 | [`root.md`](../root.md) | How the four top-level packages relate to each other and to the servlet pipeline |
| 3 | [`eo.md`](../eo.md) | The presentation layer — where the actual user-facing pages live |
| 4 | [`javax.md`](../javax.md) | The JSF front controller and request lifecycle |
| 5 | [`com.md`](../com.md) | Fujitsu scaffolding (stubs) and test fixtures |

After these five pages you'll understand: where HTTP requests arrive, how they flow through filters into JSF, which beans and views render the UI, and how the configuration layer wires it all together.

---

## Key Entry Points

Start your investigation with these classes and files — they are the most connected pieces in the codebase.

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

The most referenced class in the repository (6 connections). This JSF backing bean holds a single `String value` property that bridges the JSP view and the business logic layer. Every JSF page in the `eo.web.webview` package follows this same pattern — a bean with getters/setters wired via XML.

```java
package eo.web.webview.ACA001SF;
public class ACA001SFBean {
    private String value;
    public String getValue() { return value; }
}
```

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

The action handler for the ACA001SF screen. Its `execute()` method is invoked by JSF when the user submits the page. Like the bean, this class follows a "one screen, one logic class" convention.

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

The JSF front controller. Every JSF-bound request passes through this servlet, which orchestrates the six-phase JSF lifecycle (Restore View, Apply Request Values, Process Validations, Update Model Values, Invoke Application, Render Response).

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

The Shift JIS encoding filter. Currently a no-op stub, but the place to look if Japanese-language input produces garbled output (mojibake). It should call `request.setCharacterEncoding("cp932")` before delegating to the next filter.

---

## Project Structure

The repository is organized into two categories: the main application fixture and independent test directories.

```mermaid
flowchart TD
    ROOT["Repository Root"]
    FULL["full-fixture-codebase<br/>Complete Application"]
    JSP_FIXTURES["jsp-* directories<br/>JSP Parser Tests"]
    XML_FIXTURES["xml-* directories<br/>XML Config Tests"]
    BUG_FIXTURES["bug-* directories<br/>Bug Regression Tests"]

    ROOT --> FULL
    ROOT --> JSP_FIXTURES
    ROOT --> XML_FIXTURES
    ROOT --> BUG_FIXTURES

    subg JAVA["Java Source"]
        BEAN["Backing Bean<br/>per screen"]
        LOGIC["Action Logic<br/>per screen"]
        FILTER["Encoding Filter"]
        LISTENER["Context Listener"]
    end

    subg WEB["Web Content"]
        JSP["JSP Views"]
        WEBXML["web.xml<br/>web-full.xml"]
    end

    subg CFG["Futurity Config"]
        FACESXML["faces-config.xml"]
        SCREENCFG["WEBGAMEN_*.xml<br/>x33S_*.xml<br/>external-refs.xml"]
    end

    FULL --> JAVA
    FULL --> WEB
    FULL --> CFG
    JAVA --> BEAN
    JAVA --> LOGIC
    JAVA --> FILTER
    JAVA --> LISTENER
    WEB --> JSP
    WEB --> WEBXML
    CFG --> FACESXML
    CFG --> SCREENCFG
```

### Directory Index

| Directory | Purpose |
|---|---|
| `full-fixture-codebase/` | The most complete application variant. Start here. Contains Java source, JSP views, and all deployment descriptors. |
| `bug-ca-001-unresolved-only/` | Bug regression test for unresolved JSF references. |
| `bug-ca-002-attr-order/` | Bug regression test for JSP page directive attribute ordering. |
| `jsp-*` | Directories that test JSP parsing edge cases (wildcard imports, multi-usebean, Shift JIS encoding, comments, etc.). |
| `xml-*` | Directories that test XML configuration parsing (malformed files, unresolved FQNs, DTD/XSD references, Japanese element names, etc.). |

---

## Configuration

Everything in this project is wired through XML. There are two layers of configuration:

### Deployment Descriptors (Container-Level)

| File | Location | Controls |
|---|---|---|
| `web.xml` | `*WebA/WebContent/WEB-INF/web.xml` | Servlet filter and servlet registrations (servlet profile) |
| `web-full.xml` | `*WebA/WebContent/WEB-INF/web-full.xml` | Same registrations but for full Jakarta EE application server profiles. **Always keep in sync with `web.xml`.** |
| `faces-config.xml` | `*WebA/WebContent/WEB-INF/faces-config.xml` | JSF managed bean registration, navigation rules, and page-scoped properties |

### Application Wiring (Screen-Level)

| File | Purpose |
|---|---|
| `WEBGAMEN_FULL_ACA001.xml` | Binds the screen ID, logic class, and bean for the ACA001SF Futurity page |
| `WEBGAMEN_ACA001010PJP.xml` / `WEBGAMEN_ACA001020PJP.xml` | View definition files for individual screen variants |
| `x33S_ACA001.xml` | X33 application-level configuration for the ACA001SF screen |
| `external-refs.xml` | Cross-module external references (logic classes used by views) |
| `sun-ejb-jar.xml` | Sun ONE / GlassFish-specific EJB jar configuration (JNDI bindings) |
| `pom.xml` | Maven build configuration for the web module |

**Key rule:** Changes to servlet-level components (`FacesServlet`, filters, listeners) must be made in **both** `web.xml` and `web-full.xml`. Changes to JSF beans and navigation are made in `faces-config.xml` and screen-specific `WEBGAMEN_*.xml` files.

---

## Common Patterns

### 1. Screen-Scoped Encapsulation

Each JSF screen is a self-contained package. For example, `eo.web.webview.ACA001SF` contains:

```
ACA001SF/
  ACA001SFBean.java    -- Backing bean (data)
  ACA001SFLogic.java   -- Action handler (business logic)
  FULL_ACA001010PJP.jsp -- JSP view (presentation)
```

Screens communicate only through JSF navigation outcomes (string return values from `execute()`), **never** through Java-level imports. This makes screens independently deployable and trivially testable.

### 2. XML-Driven Bean Wiring (JSF 1.x Style)

Beans are not auto-discovered via annotations. Every managed bean must be explicitly registered in `faces-config.xml` or a module-specific XML file. Changing a bean's scope requires an XML update, not a Java annotation change.

```xml
<SCREEN id="FULL_ACA001">
  <BL class="eo.web.webview.ACA001SF.ACA001SFLogic"/>
  <SERVICEFORM bean="eo.web.webview.ACA001SF.ACA001SFBean"/>
</SCREEN>
```

### 3. Servlet Filter Chain

HTTP requests pass through a chain of filters before reaching `FacesServlet`:

```mermaid
flowchart LR
    CLIENT["HTTP Client"] --> FILTER["X33JVRequestEncodingSjisFilter<br/>(Shift JIS encoding)"]
    FILTER --> SERVLET["FacesServlet<br/>(JSF lifecycle)"]
    SERVLET --> BEAN["Managed Bean<br/>(page data)"]
    BEAN --> JSP["JSP View<br/>(HTML rendering)"]
```

### 4. Scaffold-Then-Implement

The `com.fujitsu.futurity` package follows a "declare the hook, leave the body empty" pattern. Listeners and filters are registered in deployment descriptors but perform no work. This allows deployment-time validation of descriptors while deferring implementation. When you encounter a no-op stub:
- Check `web.xml` / `web-full.xml` for how it's wired
- Decide whether to implement it or remove it

### 5. Dual Source Trees

Some classes exist in multiple source trees (`full-fixture-codebase` and `xml-unresolved-fqn`) with minor variations (e.g., presence of a Javadoc comment). When modifying shared code, verify whether the class appears in multiple locations and apply changes consistently to avoid divergence.

---

## Troubleshooting Quick Reference

| Problem | Likely Cause | Where to Look |
|---|---|---|
| Japanese characters display as mojibake | `X33JVRequestEncodingSjisFilter` is a no-op | `com.fujitsu.futurity.web.x33.filter` |
| Bean not found on page | Missing `faces-config.xml` entry or wrong scope | `faces-config.xml`, `WEBGAMEN_*.xml` |
| Navigation not working | Incorrect result string in `execute()` method | `*Logic.java`, `faces-config.xml` |
| Parser test failing | JSP directive attribute order or encoding issue | `com.example.bugca002`, `bug-ca-*` directories |
| XML config parse error | Malformed XML or unresolved FQN | `xml-malformed/`, `xml-unresolved-fqn/` |

---

## Next Steps

- **To add a new screen:** Create a package under `eo.web.webview/`, add a bean, a logic class, and a JSP view. Wire them in `faces-config.xml` and a `WEBGAMEN_*.xml` file.
- **To fix a bug:** Check whether the issue is in the application code (`full-fixture-codebase/`) or in a fixture directory (`xml-*`, `jsp-*`, `bug-*`). Fixtures are test targets — don't modify their expected behavior, add new fixtures instead.
- **To understand the JSF lifecycle:** Read the `javax.md` wiki page, which details the six-phase request lifecycle in `FacesServlet`.