# Getting Started

Welcome to the team. This guide will help you find your way around the codebase quickly.

## What This Project Does

This is a Java web application built on the JSF (JavaServer Faces) framework with a custom "Futurity" view-layer. Screens are defined declaratively in XML, which wire up business logic classes (`*Logic`) and managed beans (`*Bean`). Requests pass through encoding filters, land on the FacesServlet, and render JSP pages backed by JSF-managed beans.

## Recommended Reading Order

Start here, then go deeper as needed:

1. **Project Structure** — understand the directory layout below
2. **Key Entry Points** — focus on `ACA001SFBean` first; it is the most referenced class in the codebase
3. **Configuration** — read `web.xml` and a screen definition XML to see how the layers connect
4. **Full Fixture Codebase** — browse `full-fixture-codebase/` for a self-contained example that exercises every layer

## Key Entry Points

### `ACA001SFBean`

**The** most referenced class (6 connections). This is a request-scoped managed bean used by the JSF lifecycle to hold view state. You will find it wired in `faces-config.xml` and referenced from screen definition XMLs.

```
full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java
```

### `ACA001SFLogic`

The business logic class invoked by the screen controller. Screen definition XMLs declare it via the `<BL>` element, and it typically interacts with beans and services.

```
full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java
```

### `X33AppContextListener`

A `ServletContextListener` that runs application startup logic.

```
full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/listener/X33AppContextListener.java
```

### `X33JVRequestEncodingSjisFilter`

A servlet `Filter` that sets the request encoding for Shift-JIS input. It runs before every request hits the FacesServlet.

```
full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java
```

## Project Structure

```
project-root/
  |_ full-fixture-codebase/        # Complete self-contained example
  |    |_ src/java/                 # Java source (logic, beans, filters, listeners)
  |    |_ src/futurity-app/         # Screen/view definition XMLs
  |    |_ koptWebA/WebContent/      # JSP pages + web.xml
  |
  |_ bug-ca-*/                      # Bug regression test fixtures
  |_ xml-*/                         # XML parsing / config test fixtures
  |_ jsp-*/                         # JSP parsing test fixtures
  |_ _manifest.json                 # Fixture manifest listing all files
```

Each `xml-*` and `jsp-*` directory is a self-contained test fixture that exercises a specific parsing scenario. The `full-fixture-codebase/` directory is the canonical end-to-end example and the best place to start reading.

### How to navigate

| Location | Purpose |
|---|---|
| `src/java/` | Java source — logic, beans, filters, listeners |
| `src/futurity-app/webA/env/view/def/` | Screen definition XMLs (`WEBGAMEN_*.xml`) |
| `koptWebA/WebContent/` | JSP pages, fragment files (`.jspf`), `WEB-INF/` |
| `koptWebA/WebContent/WEB-INF/web.xml` | Servlet filter, servlet, and listener registration |
| `koptWebA/WebContent/WEB-INF/faces-config.xml` | JSF managed-bean declarations |
| `src/config/` and `src/app/` | Application config XMLs (`real-config.xml`) |
| `META-INF/sun-ejb-jar.xml` | EJB deployment descriptors (JNDI names, class mappings) |

## Configuration

### `web.xml` — Servlet wiring

Located at `koptWebA/WebContent/WEB-INF/web.xml`. Registers the encoding filter, FacesServlet, and app context listener.

```xml
<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>
<listener>
  <listener-class>
    com.fujitsu.futurity.web.x33.listener.X33AppContextListener
  </listener-class>
</listener>
```

### Screen definition XMLs

Screen definitions live under `futurity-app/webA/env/view/def/`. Each file declares a screen, its business logic, and its bean:

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

Key elements:
- `<SCREEN>` — defines the screen identifier
- `<BL>` — wires the business logic class
- `<SERVICEFORM>` — wires the managed bean and optionally action buttons
- `<BUTTON>` — declares a UI action button and its handler

### `faces-config.xml` — JSF managed beans

Located at `koptWebA/WebContent/WEB-INF/faces-config.xml`. Declares bean names, classes, and scopes (request, session, etc.).

### `sun-ejb-jar.xml` — EJB deployment

Located at `koptBp/ejbModule/META-INF/sun-ejb-jar.xml`. Maps EJB names, implementation classes, and JNDI bindings.

### `real-config.xml` — Application config

Located at `src/config/` or `src/app/`. Simple XML config files that declare class mappings for the application layer.

## Common Patterns

### Screen definition → logic → bean flow

Every request follows this chain:

```
web.xml filters request → FacesServlet → screen XML → *Logic → *Bean → JSP view
```

```mermaid
flowchart TD
    WEB["web.xml"] --> FILTER["X33JVRequestEncodingSjisFilter"]
    WEB --> SERVLET["FacesServlet"]
    WEB --> LISTENER["X33AppContextListener"]
    FILTER --> REQUEST["HTTP Request"]
    SERVLET --> FACES["JSF Lifecycle"]
    FACES --> SCREEN["Screen Def XML"]
    SCREEN --> BL["*Logic"]
    SCREEN --> BEAN["*Bean"]
    BEAN --> VIEW["JSP Page"]
    LISTENER --> APP["App Context Init"]
```

### Naming conventions

- **Beans** are named `*SFBean` (e.g., `ACA001SFBean`)
- **Logic** is `*SFLogic` (e.g., `ACA001SFLogic`)
- **Actions** are `*SFAction` (e.g., `ACA001SFAction`)
- **Screen IDs** follow a `XXXX_NNNNPP` pattern (e.g., `ACA001010P`)
- **File names** mirror screen IDs (e.g., `WEBGAMEN_ACA001010PJP.xml`)

### Filter pattern

Every request passes through `X33JVRequestEncodingSjisFilter` first, which sets the character encoding. This ensures Shift-JIS input is handled correctly before reaching the JSF lifecycle.

### XML-driven view layer

The view layer is driven by XML, not by Java annotations. Screen definitions map one-to-one with JSP pages. Adding a new screen means:

1. Create the screen XML in `futurity-app/webA/env/view/def/`
2. Create the `*Logic`, `*Bean`, and optional `*Action` classes
3. Register the bean in `faces-config.xml` if it has a new scope
4. Create the JSP page under `koptWebA/WebContent/wsd/`

### Encoding awareness

The project handles multiple character encodings. Shift-JIS is the primary concern:

- The `X33JVRequestEncodingSjisFilter` sets request encoding
- Some XML files use Shift-JIS encoding declarations (`<?xml encoding="Shift_JIS"?>`)
- Screen definition XMLs can use Japanese element names (e.g., `<画面定義>`)

### Test fixtures

The `xml-*`, `jsp-*`, and `bug-ca-*` directories are self-contained test fixtures. Each one exercises a specific parsing edge case:

| Fixture prefix | What it tests |
|---|---|
| `xml-probe/` | Basic XML parsing for screen and config elements |
| `xml-futurity-view-def/` | Full Futurity screen definition XML parsing |
| `xml-faces-config/` | JSF `faces-config.xml` managed-bean parsing |
| `xml-sun-ejb-jar/` | EJB deployment descriptor parsing |
| `xml-web-xml-multi-pattern/` | `web.xml` filter/servlet/listener registration |
| `xml-japanese-elements/` | XML with Japanese element names |
| `xml-malformed/` | Tolerance for broken XML |
| `xml-unresolved-fqn/` | References to classes not in the local index |
| `xml-build-excluded/` | Config files that should be excluded from parsing |
| `jsp-*` | Various JSP import and useBean patterns |

## Next Steps

- Open `full-fixture-codebase/` and trace a single request through the layers
- Read `xml-futurity-view-def/` to understand screen definitions in isolation
- Review the `bug-ca-*` fixtures to understand known edge cases the parser handles