# Com / Fujitsu / Futurity / Web

## Overview

The `com.fujitsu.futurity.web` package is the web-tier root of the Fujitsu Futurity application. It provides the servlet-container-facing boundary layer — the entry point through which all HTTP requests and application lifecycle events flow from the JEE servlet container into the rest of the application's domain logic.

This area of the codebase appears to be a **structural skeleton**. Rather than implementing request handlers, controllers, or business-facing logic directly, it delegates to downstream packages that reside in sibling modules. The current package is organized around sub-systems, each of which exposes its own pair of servlet lifecycle hooks — a **filter** for per-request processing and a **listener** for application-wide initialization and teardown. Today, all such components are implemented as no-op stubs, meaning the web tier is currently serving as a registration layer rather than an active processing layer.

The web package follows a **configuration-over-code** approach: components are wired into the servlet container exclusively through `web.xml` and `web-full.xml` deployment descriptors, with no programmatic `@WebFilter` or `@WebListener` annotations. This is consistent with legacy Java EE applications and enterprise deployments that prefer explicit XML configuration.

## Sub-module Guide

The web package currently contains one documented sub-system: **X33**.

### X33 — `com.fujitsu.futurity.web.x33`

The X33 sub-system provides the web-tier scaffolding for the X33 domain within the Futurity application. It lives at the intersection of the Java EE servlet container and the X33 business domain, offering two extension points:

1. **`X33JVRequestEncodingSjisFilter`** — A servlet filter designed to set the character encoding of incoming HTTP requests to **Shift JIS (SJIS / Windows-31J)** for Japanese-language input. The "JV" suffix in the name likely refers to Japan. Currently, the filter is a pure pass-through: it calls `chain.doFilter(req, res)` without inspecting or modifying the request.

2. **`X33AppContextListener`** — A servlet context listener registered in `web.xml` to react to application startup and shutdown events. Currently, the class body is entirely empty (it does not even implement `ServletContextListener`), so the container instantiates it at startup but performs no action.

#### Relationship Between X33 Components

The filter and listener serve complementary but distinct roles:

| Aspect | Filter | Listener |
|---|---|---|
| **Lifecycle phase** | Per-request | Application lifecycle (startup/shutdown) |
| **Invocation model** | Called once per matching HTTP request | Called once on container startup, once on shutdown |
| **Role in request flow** | Pre-processor before the target servlet | Setup/cleanup around the entire application lifetime |
| **Current state** | Registered, no-op pass-through | Registered, empty class body |

Together, they form a complete but inert pair of hooks: the **filter** would handle per-request concerns (encoding, authentication, logging), and the **listener** would handle application-wide concerns (initialization, teardown). Neither is functional today, but both are properly registered in the deployment descriptors, meaning the infrastructure is in place for X33-specific logic to be grafted in without deployment changes.

Both X33 components have **no Java-level dependencies** on other classes within the `com.fujitsu.futurity` codebase. They depend solely on the standard Servlet API (`javax.servlet.Filter`, `javax.servlet.ServletContextListener`, etc.). Their integration point with the rest of the system is implicit: requests that pass through the filter are destined for X33-targeting servlets or controllers in sibling packages, and the listener, if implemented, would initialize services or resources used by those downstream components.

## Key Patterns and Architecture

### Deployment Descriptor-Driven Registration

All components in this web package follow a **configuration-over-code** pattern. They are wired into the servlet container exclusively through `web.xml` and `web-full.xml`, with no programmatic registration via annotations. This approach is typical of legacy Java EE applications that predate the servlet 3.0 annotation model, or of enterprise deployments that prefer explicit XML configuration for auditable, version-controlled lifecycles.

### No-Op Stub Pattern

Both the X33 filter and listener follow a **stub-first, implement-later** approach. Rather than omitting registration entirely (which would require editing `web.xml`), the codebase registers placeholder classes in the descriptors and implements them incrementally. This pattern minimizes merge conflicts and deployment risk when adding X33-specific functionality, and suggests this area of the codebase may be in a transitional or legacy state.

### Request Lifecycle Flow

The following diagram shows how the X33 components fit into the overall web request and application lifecycle:

```mermaid
flowchart TD
    subgraph Web["com.fujitsu.futurity.web — Web Tier Root"]
        subgraph X33["com.fujitsu.futurity.web.x33"]
            subgraph Filter["Filter (per-request)"]
                X33F["X33JVRequestEncodingSjisFilter"]
            end
            subgraph Listener["Listener (app lifecycle)"]
                X33L["X33AppContextListener"]
            end
        end
    end

    webxml["web.xml / web-full.xml<br/>Deployment Descriptors"] --> X33F
    webxml --> X33L

    X33F --> doFilter["doFilter(req, res, chain)"]
    doFilter --> chain["chain.doFilter(req, res)"]
    chain --> Next["Next filter or target servlet"]

    X33L --> ctxInit["ServletContext lifecycle<br/>contextInitialized / contextDestroyed"]

    note["Note: Both components are currently no-op stubs"]
```

### Encoding Strategy (Planned)

The filter name (`X33JVRequestEncodingSjisFilter`) strongly implies an intended encoding strategy: set the request character encoding to **Windows-31J** (the MIME-compatible alias for Shift JIS) before the request is processed. This is the standard approach in legacy Japanese enterprise applications where forms and API payloads use SJIS rather than UTF-8. The intended implementation would look like:

```java
((HttpServletRequest) req).setCharacterEncoding("Windows-31J");
chain.doFilter(req, res);
```

Until this is implemented, the filter is transparent and offers no encoding guarantees.

## Dependencies and Integration

### External Dependencies

Both the X33 filter and listener depend solely on the standard Java EE / Jakarta EE Servlet API. No other packages within `com.fujitsu.futurity` are imported.

| Dependency | Purpose |
|---|---|
| `javax.servlet.Filter` API | Provides the `Filter` interface and `FilterChain` for the filter |
| `javax.servlet.ServletRequest` / `ServletResponse` | Request and response types passed through the filter |
| `javax.servlet.FilterConfig` / `FilterChain` | Container-provided configuration and chain management for the filter |

### Inbound Dependencies

| Artifact | Relationship |
|---|---|
| `web.xml` | Registers both the filter and the listener under `<filter-class>` and `<listener-class>` |
| `web-full.xml` | Extended/alternate deployment descriptor that also registers both components |

### Integration with the Rest of the System

The web package is a **leaf layer** — it has no child packages of its own and delegates all request handling to downstream modules. The X33 components act as a leaf module with no outgoing Java-level dependencies; their integration point with the rest of the Futurity system is implicit:

- **Request flow:** Incoming HTTP requests matching the X33 URL pattern flow through the filter chain, then land in X33-targeting servlets, controllers, or action classes in sibling packages.
- **Lifecycle flow:** If the listener is implemented with `ServletContextListener`, it would initialize services or resources consumed by those downstream components during application startup, and perform cleanup on shutdown.

## Notes for Developers

- **All components are no-ops.** If you are onboarding to the X33 web layer, be aware that the filter does not perform encoding and the listener does not run any initialization code. Functionality must be added explicitly.
- **The filter needs encoding logic.** To activate Shift JIS encoding, add `((HttpServletRequest) req).setCharacterEncoding("Windows-31J")` in `doFilter()` before `chain.doFilter(req, res)`. Consider making this conditional on the request path if only Japanese endpoints need SJIS encoding.
- **The listener needs interface implementation.** To make the listener functional, add `implements javax.servlet.ServletContextListener` and implement `contextInitialized` and optionally `contextDestroyed`.
- **Thread safety is not a concern** for the current no-op implementations, but any future initialization logic in the listener must account for the fact that `contextInitialized` runs on the container's startup thread — heavy blocking work will delay application startup.
- **Both components are registered in two descriptors.** Changes to one (`web.xml`) may need to be mirrored in the other (`web-full.xml`) depending on your deployment profile. Check your CI/CD pipeline to understand when each is used.
- **This is a structural skeleton.** The web tier currently does not implement request-handling logic itself; it registers lifecycle hooks that downstream modules use. When adding new web-layer functionality, look to sibling packages for the actual controllers and dispatchers.