# Getting Started

> You just joined the team — this guide helps you build a working mental model of the codebase in under 15 minutes.

## What This Project Does

This is a Java EE web application built on **JavaServer Faces (JSF)**, a component-based MVC framework for building web interfaces. The codebase is organized into servlet-based web components — filters, listeners, and JSF managed beans — configured through standard `web.xml` and `faces-config.xml` descriptors. Most components in the repository are currently **scaffolding stubs** (structural placeholders with no operational logic), suggesting this is either an early-stage project or a legacy codebase where functionality is yet to be implemented.

## Recommended Reading Order

Build your understanding in this order:

1. **[`root.md`](../root.md)** — The top-level overview of all packages and how they relate. This is your single source of truth for the full architecture.
2. **[`eo/web/webview/ACA001SF.md`](../eo/web/webview/ACA001SF.md)** — The most substantive module: a complete JSF view with managed bean, logic class, and JSP page. Follow the MVC pattern here and you'll understand every other view.
3. **[`javax/faces/webapp.md`](../javax/faces/webapp.md)** — The `FacesServlet` that serves as the single entry point for all JSF requests. Understand the JSF six-phase lifecycle.
4. **[`com/fujitsu/futurity/web/x33/filter.md`](../com/fujitsu/futurity/web/x33/filter.md)** and **[`com/fujitsu/futurity/web/x33/listener.md`](../com/fujitsu/futurity/web/x33/listener.md)** — The servlet-level hooks (filter and listener) that intercept requests before they reach JSF.
5. **[`com/example/bugca002.md`](../com/example/bugca002.md)** — A short read (one class, one method). Clarifies the scaffolding/import-resolution pattern used in this repo.

## Key Entry Points

These are the classes and files you'll encounter most often:

| Class / File | Role | Package |
|---|---|---|
| [`ACA001SFBean`](full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java) | **Most referenced class (6 connections).** JSF managed bean exposing the `value` property for the ACA001 view. Start here to understand data binding. | `eo.web.webview.ACA001SF` |
| [`ACA001SFLogic`](full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java) | Action handler. The `execute()` method is the designated entry point for all user-triggered actions in the ACA001 view. | `eo.web.webview.ACA001SF` |
| [`FacesServlet`](full-fixture-codebase/src/java/javax/faces/webapp/FacesServlet.java) | JSF front controller. All JSF requests flow through this servlet, which enforces the six-phase lifecycle. Currently a stub class. | `javax.faces.webapp` |
| [`X33JVRequestEncodingSjisFilter`](full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java) | Servlet filter that should enforce Shift JIS encoding on incoming requests. Currently a no-op delegate. | `com.fujitsu.futurity.web.x33.filter` |
| [`X33AppContextListener`](full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/listener/X33AppContextListener.java) | Application lifecycle listener that fires on startup and shutdown. Currently empty and package-private. | `com.fujitsu.futurity.web.x33.listener` |

## Project Structure

The repository is organized into top-level directories, each representing a set of related modules (fixtures, test cases, or a complete build):

```mermaid
flowchart TD
    WEB["Web Tier<br/>web.xml, web-full.xml"] --> JSF["FacesServlet<br/>javax.faces.webapp"]
    WEB --> FILTER["X33JVRequestEncodingSjisFilter<br/>com.fujitsu"]
    WEB --> LISTENER["X33AppContextListener<br/>com.fujitsu"]
    JSF --> VIEW["ACA001SF<br/>eo.web.webview"]
    VIEW --> BEAN["ACA001SFBean<br/>Managed Bean"]
    VIEW --> LOGIC["ACA001SFLogic<br/>Action Handler"]
    EX["com.example<br/>Scaffolding"] -.->|independent| JSF
```

### Java source packages

| Package | What it contains |
|---|---|
| `javax.faces.webapp` | JSF framework front controller (`FacesServlet`) |
| `eo.web.webview.ACA001SF` | The primary JSF view module — managed bean + logic class |
| `com.fujitsu.futurity.web.x33.filter` | Servlet filter for Shift JIS encoding |
| `com.fujitsu.futurity.web.x33.listener` | Servlet context lifecycle listener |
| `com.example.bugca002` | Scaffolding class for import resolution |

### Top-level module directories

| Directory | Purpose |
|---|---|
| `full-fixture-codebase` | Complete, self-contained fixture with Java sources and `web.xml` / `web-full.xml` |
| `xml-*` directories | Individual test fixtures for specific XML parsing scenarios (e.g., `xml-faces-config`, `xml-web-xml-multi-pattern`, `xml-japanese-elements`) |
| `jsp-*` directories | JSP-specific test fixtures for tag parsing, usebean, wildcard imports, etc. |
| `bug-ca-*` directories | Code-quality rule test cases (`bug-ca-001` unresolved references, `bug-ca-002` attribute ordering) |

## Configuration

The application is wired together entirely through XML deployment descriptors. You will not find annotations or programmatic configuration — everything goes through `web.xml` and JSF config files.

### Key configuration files

| File | What it controls |
|---|---|
| `web.xml` | Servlet, filter, and listener declarations. Registers `FacesServlet`, `X33AppContextListener`, and `X33JVRequestEncodingSjisFilter`. |
| `web-full.xml` | Full Java EE web profile variant. Mirrors filter registration — used when deploying on servers that prefer the full profile (e.g., WebSphere). |
| `faces-config.xml` | JSF managed bean declarations, navigation rules, and converters. Declares which beans are available to JSF pages. |
| `WEBGAMEN_FULL_ACA001.xml` | Module-specific JSF configuration for the ACA001 view. |
| `WEBGAMEN_ACA001010PJP.xml` | View-specific JSF configuration for the ACA001010PJP screen. |
| `x33S_ACA001.xml` | Additional ACA001 module configuration referenced from the futurity app. |

### How to add a new view

1. Create a managed bean class (e.g., `NewViewBean`) with properties as getters/setters.
2. Create a logic class (e.g., `NewViewLogic`) with an `execute()` method.
3. Register the bean in `faces-config.xml` or the appropriate module-specific XML descriptor.
4. Create the JSP view page and reference the bean via EL expressions like `#{newViewBean.property}`.
5. Ensure any new classes are wired through the filter chain in `web.xml` if needed.

## Common Patterns

### JSF Managed Bean MVC Pattern

Every view follows the same three-tier structure:

```mermaid
flowchart LR
    USER["User"] --> JSP["JSP View Page"]
    JSP --> BEAN["Managed Bean<br/>EL properties"]
    JSP --> LOGIC["Logic Class<br/>execute()"]
    LOGIC --> SVC["Service Layer<br/>external"]
```

- **View Layer** — JSP pages render the UI, pulling data from beans via EL (`#{beanName.property}`).
- **Model Layer** — Plain Java beans expose properties as getters (and optionally setters). If only a getter exists, the property is read-only.
- **Controller Layer** — Dedicated logic classes handle user actions through their `execute()` method.

### Scaffolding / Stub Pattern

Most classes in this codebase are scaffolding — they have the correct structure and XML registrations, but no operational logic:

- Logic classes have empty `execute()` methods — implementation belongs here.
- Managed beans may have minimal or no properties — add as needed.
- Filters and listeners are registered in `web.xml` but their methods are no-ops.

**When working with stubs:** verify what is wired up versus what is placeholder before implementing. The structural pattern is reliable; add behavior on top.

### Issue-Tied Packaging

Sub-package names like `com.example.bugca002` are tied to specific issue tracker items or code-quality rules (`bug-ca-NNN`). Each rule or defect gets its own directory. Follow this convention: create a `bug-ca-NNN` directory and a corresponding sub-package with a `KnownClass`-style stub.

### Naming Conventions

| Convention | Example | Meaning |
|---|---|---|
| `<ModuleCode>SF` | `ACA001SF` | JSF view sub-module |
| `<ModuleCode>SFBean` | `ACA001SFBean` | Managed bean backing the view |
| `<ModuleCode>SFLogic` | `ACA001SFLogic` | Action handler for the view |
| `bug-ca-NNN` | `bug-ca-001`, `bug-ca-002` | Code-quality rule or defect directory |
| `X33*` | `X33JVRequestEncodingSjisFilter` | X33 module-specific infrastructure |

### Character Encoding

The filter package (`com.fujitsu.futurity.web.x33`) contains a Shift JIS encoding filter. Before implementing encoding logic, confirm with the team whether Shift JIS is still a requirement — modern applications typically use UTF-8.

## Deployment Checklist

Before deploying or starting development, verify:

1. **`FacesServlet` is mapped** — A `<servlet>` declaration and `<servlet-mapping>` must exist in `web.xml` for JSF requests to be processed.
2. **Listener is `public`** — `X33AppContextListener` is currently package-private but must be `public` for the container to instantiate it.
3. **Bean descriptors match** — Every managed bean used in a JSP must be declared in `faces-config.xml` or the appropriate XML config, or EL expressions will fail to resolve.
4. **Build configuration is clear** — Some classes exist in multiple locations (e.g., full fixture vs. XML unresolved-FQN variants). Confirm you are editing the correct variant.