# Com

## Overview

The `com` package is the top-level Java namespace that groups two distinct, unrelated code areas sharing the same root prefix. Rather than forming a cohesive module, these sub-namespaces reflect separate concerns:

- **`com.example`** — Minimal test fixtures used to validate a JSP parser's handling of `<%@ page %>` directive attributes. This is a regression-test harness, not production code.
- **`com.fujitsu`** — A Japanese-targeted Java EE web application scaffold (currently all stubs) that was reserved as an extension point for Fujitsu-specific HTTP workflows.

Together, these namespaces occupy the `com` root without depending on each other. Neither sub-module is imported by or imports from the broader codebase — both are leaf packages.

## Sub-module Guide

### `com.example` — JSP Parser Test Fixtures

The `com.example` package contains test fixtures that exercise a JSP parser edge case. The primary concern is validating a fix for a bug where attribute ordering within a JSP page directive causes the parser to silently drop `import` declarations.

The sub-module `com.example.bugca002` provides:

- **`KnownClass`** — a trivial, no-op Java class that serves as the resolution target for the JSP import. It has no fields, no constructors beyond the default, and a single empty `execute()` method. Its only purpose is to give the parser a symbol to resolve.
- **`BugCa002Language Before Import.jsp`** — a JSP page whose page directive deliberately places `language="java"` before `import="com.example.bugca002.KnownClass"`. The filename intentionally contains a space to test file-handling edge cases.

These two files form a complete regression test: the JSP declares the import in an attribute order that previously triggered the parser bug, and `KnownClass` provides the class that should have been resolved if the parser had handled the attribute correctly.

### `com.fujitsu` — Fujitsu Web Application Scaffold

The `com.fujitsu` namespace is the top-level corporate boundary for Fujitsu-related code. Its only documented child is `com.fujitsu.futurity`, a Java EE web application targeting Japanese-language HTTP workflows.

The `futurity` sub-package follows a standard Java EE servlet architecture with components registered through deployment descriptors:

- **`X33AppContextListener`** — an empty lifecycle stub. No-op today, reserved for future application initialization (Spring context bootstrapping, resource pools, etc.).
- **`X33JVRequestEncodingSjisFilter`** — a no-op request filter designed to handle Shift JIS (SJIS / cp932) encoding. Currently unimplemented, posing a risk of mojibake if the server's default encoding is not SJIS-compatible.

This module is entirely in scaffolding phase. Both components are no-op stubs that exist to validate deployment-time descriptor resolution and reserve extension points ahead of active sprint work.

### How the Sub-modules Relate

Despite sharing the `com` namespace, `example` and `fujitsu` are functionally independent:

- **No shared dependencies.** Neither imports from the other, and they share no utility classes or interfaces.
- **Different lifecycles.** `example` is driven by external test harnesses that invoke the JSP parser against its fixtures. `fujitsu` is driven by the servlet container at deployment and runtime.
- **Different maturity.** `example` contains working test logic with a known, validated parser bug fix. `fujitsu` contains only stubs — no runtime behavior is exercised by either component.

## Key Patterns and Architecture

### Attribute Order Independence (example)

A key architectural principle in `com.example` is that JSP directive attributes are **a set, not a sequence**. The JSP specification does not guarantee attribute ordering within a directive, so parsers should parse each `key=value` pair independently. The `bugca002` fixture validates this invariant by constructing a JSP that deliberately violates the expected order.

### Scaffold / Stub Pattern (fujitsu)

The `com.fujitsu` module follows a "declare the hook, leave the body empty" pattern. The listener and filter exist in the compiled codebase but perform zero work at runtime. This is common when reserving extension points: it allows deployment-time validation of descriptors and ensures the container won't error on missing classes.

### Deployment Descriptor-Driven Registration (fujitsu)

Rather than using Java EE annotations (`@WebListener`, `@WebFilter`), the Futurity module registers its components entirely through `web.xml` and `web-full.xml`. This dual-registration across both the servlet-only and full Java EE profiles ensures hooks activate regardless of whether the application runs on a lightweight container (Tomcat) or a full Jakarta EE server.

```mermaid
flowchart LR
    subgraph EX["com.example"]
        EGF["Test Fixtures (JSP parser tests)"]
    end
    subgraph FUJ["com.fujitsu"]
        FG["Fujitsu Web Scaffolding"]
    end
    EX -->|"share top-level namespace"| ROOT["com (root package)"]
    FUJ -->|"share top-level namespace"| ROOT
    ROOT -->|"serves as"| NS["Java namespace boundary"]
```

## Dependencies and Integration

### External Dependencies

| Sub-module | Dependency | Purpose |
|---|---|---|
| `com.example` | None (leaf) | `KnownClass` extends only `java.lang.Object`. |
| `com.fujitsu` | `javax.servlet` | Servlet API — the sole external import for both the listener and filter classes. |

### Inbound Relationships

- **`com.example`**: Nothing in the broader project consumes or references code in this package. It is driven entirely by external test harnesses that invoke the JSP parser against the fixture.
- **`com.fujitsu`**: No other package imports from `com.fujitsu`. It is a leaf node in the dependency graph.

### Outbound Relationships

- **`com.example`**: Has no outbound dependencies beyond the JSP parser (external system) that consumes its fixtures.
- **`com.fujitsu`**: Imports only `javax.servlet`. No Spring, Guice, or CDI frameworks are wired in.

## Notes for Developers

### For `com.example`:

- **This is test fixture code, not production code.** Do not refactor or extend with business logic. Its sole purpose is to exercise a specific parser edge case.
- **The JSP filename contains a space** (`BugCa002Language Before Import.jsp`). File-handling logic in this directory must be robust to whitespace in filenames.
- **The class is intentionally trivial.** If you need to add test cases, add new classes rather than modifying `KnownClass`.
- **Related test fixtures** exist in the sibling `bug-ca-002-attr-order` project directory for additional variations on attribute ordering within JSP page directives.

### For `com.fujitsu`:

- **Everything is currently a stub.** The listener has no class body, and the filter's `doFilter`, `init`, and `destroy` methods are no-ops. No runtime behavior depends on these components performing work.
- **Japanese encoding is an open risk.** If the Futurity application serves Japanese-language users, unhandled Shift JIS encoding will cause mojibake. To fix, `X33JVRequestEncodingSjisFilter.doFilter` should call `((HttpServletRequest) req).setCharacterEncoding("cp932")` before delegating. For correctness, wrap the request in a custom `HttpServletRequestWrapper` so `getParameter` calls throughout the application respect the encoding.
- **Listener implementation needs a design decision.** Before adding behavior to `X33AppContextListener`, determine whether it should implement `javax.servlet.ServletContextListener` (generic container lifecycle, receiving `contextInitialized`/`contextDestroyed`) or integrate with Spring by extending `ContextLoaderListener`. This choice dictates both the API to implement and the `web.xml` configuration required.
- **Thread-safety today is not a concern.** Both the filter and listener are stateless. Any future state added to these components should be handled carefully, especially application-scoped resources the listener may hold.
- **Low-risk area to modify.** Since no other package references classes from this module, changes here have no downstream impact. The module can be safely extended, refactored, or removed.
- **Possible deprecation.** Given that all components are empty stubs with no cross-module references, verify with the team whether the X33 / Futurity module is still in scope. If not, the `x33` package and its `web.xml` entries can be cleaned up to reduce deployment confusion.