# Getting Started

Welcome to the **Futurity** codebase. This guide answers the question: *"I just joined the team — where do I start reading?"*

---

## What This Project Does

Futurity is a Java EE web application built for Fujitsu that serves as the presentation and request-processing layer of a larger system. It uses **JavaServer Faces (JSF)** and **Struts 1.x** to render component-based, server-side views -- primarily for Japanese-language deployments. The application is deployed as a standard WAR file and follows a classic multi-layered MVC architecture: servlet filters handle request preprocessing (e.g. character encoding), the JSF FacesServlet manages the request lifecycle, and Struts action-logic classes populate data beans that JSP views render.

---

## Recommended Reading Order

Build your mental model in this order:

1. **[web-full.xml](../full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml)** -- The deployment descriptor. It wires together every entry point: which servlets are registered, which filters are in the chain, and what URL patterns they match. This is the single best starting point for understanding the whole application.

2. **[FacesServlet](../full-fixture-codebase/src/java/javax/faces/webapp/FacesServlet.java)** -- The JSF entry point. Read it to understand how `FacesServlet` receives and dispatches HTTP requests through the six-phase JSF lifecycle (RestoreView, ApplyRequestValues, ProcessValidations, UpdateModelValues, InvokeApplication, RenderResponse).

3. **[X33JVRequestEncodingSjisFilter](../full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java)** -- The servlet filter at the edge of the request pipeline. It currently delegates every request without modifying it, but it is the intended location for Shift-JIS character encoding handling.

4. **[ACA001SFBean](../full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java) and [ACA001SFLogic](../full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java)** -- The Struts MVC pattern used for the application's view pages. The logic class processes a request, populates the bean, and the JSP views consume the bean's data.

5. **[X33AppContextListener](../full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/listener/X33AppContextListener.java)** -- A stub listener for future servlet context initialization hooks. Peek here when you need to add startup or shutdown logic.

---

## Key Entry Points

These are the classes you will encounter most often -- either by following the request flow or by extending them:

### ACA001SFBean

**Location:** `src/java/eo/web/webview/ACA001SF/ACA001SFBean.java`

The data carrier (model) for the ACA001SF view. It holds a single `String value` field exposed via a getter. Every JSP page for this view reads data through this bean. It is the **most referenced class** in the codebase (8 connections) because both the logic handler and multiple JSP views depend on it.

**How it's used:**

```java
// ACA001SFBean.java
package eo.web.webview.ACA001SF;

public class ACA001SFBean {
    private String value;

    public String getValue() { return value; }
}
```

In a JSP view:

```jsp
<jsp:useBean id="myBean" class="com.foo.Bean" scope="request"/>
<p><%= myBean.getValue() %></p>
```

### ACA001SFLogic

**Location:** `src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java`

The Struts action handler. Its `execute()` method is currently an empty stub -- it is called by Struts based on the XML action mappings and is responsible for populating the `ACA001SFBean` before forwarding to the view.

```java
// ACA001SFLogic.java
package eo.web.webview.ACA001SF;

public class ACA001SFLogic {
    public void execute() { }
}
```

### X33JVRequestEncodingSjisFilter

**Location:** `src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java`

The sole Servlet Filter in the application. It implements `javax.servlet.Filter` and is mapped in `web-full.xml`. Today it is a no-op (delegates to the next filter unchanged), but it is the intended home for Shift-JIS request encoding.

```java
// X33JVRequestEncodingSjisFilter.java
package com.fujitsu.futurity.web.x33.filter;

import javax.servlet.*;

public class X33JVRequestEncodingSjisFilter implements Filter {
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws Exception {
        chain.doFilter(req, res);   // no-op today
    }
    public void init(FilterConfig config) { }
    public void destroy() { }
}
```

---

## Project Structure

```
full-fixture-codebase/
├── src/java/                          # All Java source code
│   ├── com/fujitsu/futurity/web/      # Fujitsu-specific web layer
│   │   ├── x33/filter/                # Servlet filters (encoding)
│   │   │   └── X33JVRequestEncodingSjisFilter.java
│   │   └── x33/listener/              # App context listeners (stubs)
│   │       └── X33AppContextListener.java
│   ├── eo/web/webview/                # MVC view modules (Struts)
│   │   └── ACA001SF/
│   │       ├── ACA001SFBean.java      # Data carrier
│   │       └── ACA001SFLogic.java     # Action handler
│   └── javax/faces/webapp/            # JSF entry point (stub)
│       └── FacesServlet.java
└── koptWebA/WebContent/               # Web resources (WAR content)
    ├── WEB-INF/
    │   └── web-full.xml               # Deployment descriptor
    └── wsd/                           # JSP view pages
        ├── fragments/                 # Shared JSP fragments (.jspf)
        │   └── header.jspf
        ├── ns/jpn/pc/                 # Japanese-language views
        ├── usebean.jsp
        ├── multi-usebean.jsp
        ├── multiline.jsp
        ├── wildcard.jsp
        ├── comment-only.jsp
        └── static-no-java.jsp
```

**Key directories at a glance:**

| Directory | Contents |
|---|---|
| `src/java/com/fujitsu/futurity/web/x33/filter/` | Servlet filter for request encoding |
| `src/java/com/fujitsu/futurity/web/x33/listener/` | Application lifecycle listeners |
| `src/java/eo/web/webview/` | MVC view modules (Struts bean + logic) |
| `src/java/javax/faces/webapp/` | JSF FacesServlet stub |
| `koptWebA/WebContent/WEB-INF/` | Deployment descriptors |
| `koptWebA/WebContent/wsd/` | JSP pages and fragment includes |

---

## Configuration

### web-full.xml

**Location:** `full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml`

The primary deployment descriptor. It registers three core components:

1. **SjisFilter** (`X33JVRequestEncodingSjisFilter`) -- The character encoding filter. Mapped via `<filter>` and `<filter-mapping>`.
2. **FacesServlet** (`javax.faces.webapp.FacesServlet`) -- The JSF servlet. Mapped via `<servlet>` and `<servlet-mapping>`.
3. **(Future)** Struts action mappings -- Wired through external XML files such as `WEBGAMEN_FULL_ACA001.xml`.

```xml
<!-- web-full.xml (excerpt) -->
<web-app>
  <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>
</web-app>
```

No other external dependencies (Spring, Hibernate) were detected -- the stack relies on Java EE APIs and the Struts/JSF frameworks.

---

## Common Patterns

### MVC Flow for a View Page

Every Struts-driven view follows the same pattern:

1. **Struts XML config** (e.g. `WEBGAMEN_FULL_ACA001.xml`) maps a URL to an Action class.
2. The **Logic class** (`ACA001SFLogic`) processes the request and populates the **Bean** (`ACA001SFBean`).
3. The **JSP view** reads the bean via `<jsp:useBean>` and renders HTML.

```mermaid
flowchart LR
    REQ["HTTP Request"] --> FILTER["X33 Filter<br/>SjisFilter"]
    FILTER --> STRUTS["Struts Action<br/>ACA001SFLogic"]
    STRUTS --> BEAN["Data Bean<br/>ACA001SFBean"]
    BEAN --> JSP["JSP View<br/>usebean.jsp"]
    JSP --> RESP["HTML Response"]
```

### JSP View Patterns

The JSP files in `WebContent/wsd/` demonstrate several conventions used throughout the project:

- **`<jsp:useBean>` with `scope="request"`** -- Beans are scoped to the request, making them available to the JSP that renders the response. Session-scoped beans (`scope="session"`) appear in multi-bean test pages.

- **Fragment includes (`.jspf`)** -- Shared UI pieces live in `wsd/fragments/`. The `header.jspf` fragment imports its own dependencies via the page `import` attribute and renders a `<div>` block.

- **Single-class views** -- Most JSP files import exactly one package (e.g. the `ACA001SF` bean package) to keep the view layer lightweight. Multi-import pages (e.g. `multiline.jsp`) exist but are exceptions.

- **Japanese-language naming** -- Pages under `wsd/ns/jpn/pc/` target the Japanese market. The filter package (`x33.filter`) and encoding references reflect this internationalization strategy.

- **JSPF fragment includes** -- Reusable UI fragments live in `wsd/fragments/` with the `.jspf` extension. Include them via `<jsp:include>` in your pages.

### Code Style Conventions

- **Package naming:** `com.fujitsu.futurity.web.*` for Fujitsu web infrastructure; `eo.web.webview.*` for business view modules; `javax.*` for Java EE API stubs.
- **Bean naming:** Data carrier classes end with `Bean` (e.g. `ACA001SFBean`). Logic classes end with `Logic` (e.g. `ACA001SFLogic`).
- **Filter naming:** Filter classes end with `Filter` and follow the pattern `<Module><Purpose>Filter` (e.g. `X33JVRequestEncodingSjisFilter`).
- **Listener naming:** Listener classes follow the `<Module>AppContextListener` pattern (e.g. `X33AppContextListener`).
- **No third-party DI:** No Spring or Guice wiring -- classes are instantiated directly by the container or Struts framework.
- **Minimal boilerplate:** Existing classes are intentionally terse -- no Lombok, no annotations beyond `@Override` equivalents, no builder patterns. Keep new code equally concise.