# Getting Started

## What This Project Does
This repository is a fixture-heavy Java/XML codebase used to exercise code indexing, configuration parsing, and cross-reference detection. Most of the value here comes from the way Java classes, JSP/JSF web assets, and XML config files refer to one another across different packaging patterns.

If you are new to the codebase, start by understanding the small set of Java entry points and then trace how the surrounding XML files wire them into the web application.

## Recommended Reading Order
1. **Project manifest** — read [`_manifest.json`](_manifest.json) first to understand which fixture families exist and where the important files live.
2. **Web application wiring** — then inspect [`xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml`](xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml) and [`xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml`](xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml) to see how the app is assembled.
3. **Representative end-to-end fixture** — review [`full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml) together with the Java classes under `full-fixture-codebase/src/java/`.
4. **Special cases** — skim the XML-only fixtures such as [`xml-unresolved-fqn/src/config/external-refs.xml`](xml-unresolved-fqn/src/config/external-refs.xml), [`xml-comment-with-class/src/config/commented-classes.xml`](xml-comment-with-class/src/config/commented-classes.xml), and [`xml-no-java-refs/src/config/pure-config.xml`](xml-no-java-refs/src/config/pure-config.xml) to learn the edge cases this repo covers.

## Key Entry Points
These are the first classes to understand because they anchor the web flow and are referenced by multiple config files:

- [`eo.web.webview.ACA001SF.ACA001SFLogic`](full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java) — the main view logic class used in the full fixture.
- [`eo.web.webview.ACA001SF.ACA001SFBean`](full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFBean.java) — the matching managed bean for the ACA001 screen flow.
- [`com.fujitsu.futurity.web.x33.filter.X33JVRequestEncodingSjisFilter`](full-fixture-codebase/src/java/com/fujitsu/futurity/web/x33/filter/X33JVRequestEncodingSjisFilter.java) — the request-encoding filter wired from web.xml.

When in doubt, trace references from these classes back into the XML files listed above.

## Project Structure
The repository is organized as a set of small fixtures rather than one monolithic application:

- **`full-fixture-codebase/`** — the most complete example; use this when you want to see Java, JSP, web.xml, and view definitions working together.
- **`xml-web-xml-multi-pattern/`** — web.xml examples with multiple container patterns and servlet/filter/listener wiring.
- **`xml-faces-config/`** — JSF managed-bean configuration examples.
- **`xml-build-excluded/`** — build-related exclusion and configuration samples, including Maven and XML config pairing.
- **`xml-unresolved-fqn/`** — references to both internal and external fully qualified class names.
- **`xml-comment-with-class/`** — class references embedded in comments, useful for testing comment-aware parsing.
- **`xml-no-java-refs/`** — pure configuration with no Java linkage.
- **`xml-dtd-xsd-ref/`** — schema-location and DTD/XSD reference examples.
- **`xml-malformed/`** — intentionally broken XML for parser-edge testing.
- **`xml-css-class-only/`, `xml-jndi-only/`, `xml-japanese-elements/`, and related fixtures** — specialized samples that isolate a single parsing pattern.

In practice, most work starts in one fixture directory and then jumps to the corresponding Java package or deployment descriptor.

## Configuration
The most important config files are the deployment descriptors and fixture XMLs that connect web resources to Java classes:

- [`xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml`](xml-web-xml-multi-pattern/koptWebA/WebContent/WEB-INF/web.xml) — declares filters, servlets, and listeners.
- [`full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml) — compact example of the same web wiring used in the full fixture.
- [`xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml`](xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml) — maps JSF managed beans to Java classes and scopes.
- [`xml-build-excluded/pom.xml`](xml-build-excluded/pom.xml) — Maven project metadata for the build-excluded fixture.
- [`xml-build-excluded/src/config/real-config.xml`](xml-build-excluded/src/config/real-config.xml) — example of a real configuration file that still contains class references.
- [`xml-unresolved-fqn/src/config/external-refs.xml`](xml-unresolved-fqn/src/config/external-refs.xml) — shows internal vs. unresolved external class references.
- [`xml-no-java-refs/src/config/pure-config.xml`](xml-no-java-refs/src/config/pure-config.xml) — config with no code references, useful as a baseline.
- [`xml-dtd-xsd-ref/src/config/schema-only.xml`](xml-dtd-xsd-ref/src/config/schema-only.xml) — schema reference example without embedded Java linkage.

## Common Patterns
A few patterns repeat across the repo:

- **Configuration-driven wiring** — Java classes are usually connected through XML descriptors rather than annotations or framework bootstrap code.
- **Package-to-screen naming** — screen and bean names often mirror the Java package structure, especially in the `ACA001SF` examples.
- **Minimal implementations** — many classes are intentionally tiny so the important behavior is the reference graph, not the business logic.
- **Comment-sensitive parsing** — some fixtures place class names in comments to verify that tooling handles non-code references correctly.
- **Edge-case coverage** — malformed XML, unresolved FQNs, and schema-only files exist to test the boundaries of parsers and indexers.

## A Practical First Pass
If you only have a few minutes, read in this order:
1. [`_manifest.json`](_manifest.json)
2. [`full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java`](full-fixture-codebase/src/java/eo/web/webview/ACA001SF/ACA001SFLogic.java)
3. [`full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml`](full-fixture-codebase/koptWebA/WebContent/WEB-INF/web-full.xml)
4. [`xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml`](xml-faces-config/koptWebA/WebContent/WEB-INF/faces-config.xml)
5. [`xml-unresolved-fqn/src/config/external-refs.xml`](xml-unresolved-fqn/src/config/external-refs.xml)

That sequence gives you the fastest path from repository map to real reference examples.