# Com / Optage / Testdata

## Overview

The `com.optage.testdata` package is a **test-data scaffolding layer** for a static analysis and code-quality tooling ecosystem. It does not contain production business logic. Instead, it provides carefully constructed fixtures, stubs, and minimal implementations that exercise specific Java language features (reflection, dependency injection, factory patterns) so that a static analysis engine — likely a SonarQube rule or similar scanner — can verify that it correctly detects and tracks those patterns.

The package is driven by a single entry point, [`App`](src/main/java/com/optage/testdata/App.java), which exercises five reflection harnesses and one DI consumer class. The sub-modules break this concern down into focused responsibilities:

- **`reflection`** — classes that exercise different Java reflection APIs (`Class.forName`, `getDeclaredMethod`, factory instantiation).
- **`targets`** — stub classes that reflection consumers load and inspect at runtime.
- **`util`** — a shared utility for rule-based invocation.
- **`di`** — a minimal Jakarta EE dependency-injection demo (interface + implementation + `@Stateless` consumer).

Together, these sub-modules give the analysis engine representative code to crawl, trace, and verify.

## Sub-module Guide

### `com.optage.testdata.reflection` — Reflection Exercise Classes

This sub-module contains five classes, each demonstrating a distinct reflection or factory-instantiation technique. Every class follows a convention: a single public `run()` method that performs a self-contained exercise. This convention lets a test harness discover and execute all `run()` methods programmatically.

| Class | Technique | Why it exists |
|---|---|---|
| [`ReflectionForNameConstant`](src/main/java/com/optage/testdata/reflection/ReflectionForNameConstant.java) | `Class.forName()` with a `static final` string constant | Tests that the analyzer resolves class names from constants, not just literals |
| [`ReflectionForNameLiteral`](src/main/java/com/optage/testdata/reflection/ReflectionForNameLiteral.java) | `Class.forName()` with a literal string | The literal counterpart; also casts the result and calls a typed method (`hello()`), testing the analyzer's ability to follow cast chains |
| [`ReflectionInvokeConstant`](src/main/java/com/optage/testdata/reflection/ReflectionInvokeConstant.java) | `getDeclaredMethod()` + `Method.invoke()` | Exercises the `java.lang.reflect.Method` API (distinct from `Class.forName()`); tests indirect method-call tracking |
| [`DispatchFrameworkInvoke`](src/main/java/com/optage/testdata/reflection/DispatchFrameworkInvoke.java) | Delegates to a shared utility (`JBSbatCheckUtil.invoke`) with different rule arrays | Tests parameterized runtime behavior with varying rule identifiers |
| [`XmlFactoryFalsePositive`](src/main/java/com/optage/testdata/reflection/XmlFactoryFalsePositive.java) | Standard JAXP `SAXParserFactory.newInstance()` | A deliberate **no-op test** ensuring the static analyzer does **not** flag common, safe factory patterns as security risks |

The classes in `reflection` depend on:
- [`ReflectTarget`](src/main/java/com/optage/testdata/targets/ReflectTarget.java) — the reflection target class (loaded via `Class.forName` and via `getDeclaredMethod`)
- [`JBSbatCheckUtil`](src/main/java/com/optage/testdata/util/JBSbatCheckUtil.java) — the shared utility invoked by `DispatchFrameworkInvoke`

### `com.optage.testdata.targets` — Stub Target Classes

This sub-module provides lightweight fixture classes that the `reflection` sub-module loads and inspects. It contains three classes:

- **[`EmailRule`](src/main/java/com/optage/testdata/targets/EmailRule.java)** — A stub with an empty `check()` method, acting as a type placeholder for email-rule checks.
- **[`SmsRule`](src/main/java/com/optage/testdata/targets/SmsRule.java)** — Mirrors `EmailRule` for SMS rules, maintaining symmetry so the test harness can treat both rule types uniformly.
- **[`ReflectTarget`](src/main/java/com/optage/testdata/targets/ReflectTarget.java)** — The only class with actual behavior. Its `hello()` method prints `"hello"` to stdout. It is the primary class actively consumed by the test harness.

These stubs are intentionally minimal — empty method bodies, no fields. They exist solely to give the analysis engine concrete types to reference, instantiate, and inspect via reflection.

### `com.optage.testdata.util` — Shared Utilities

This sub-module contains a single class:

- **[`JBSbatCheckUtil`](src/main/java/com/optage/testdata/util/JBSbatCheckUtil.java)** — A static utility class with an `invoke(Object ctx, String[] rules)` method that applies a set of rules against a context object. The current implementation is a **no-op stub** (method body is a comment placeholder), but the method signature suggests it is the hook through which the broader system dispatches rule evaluation at runtime. It accepts string-based rule names (e.g., `"e-mail"`, `"sms"`) and a context object, indicating that the system resolves rule types by string name.

### `com.optage.testdata.di` — Dependency Injection Demo

This sub-module demonstrates a standard Jakarta EE / Java EE DI pattern, separate from the reflection focus of the other sub-modules. It contains:

- **[`BillingService`](src/main/java/com/optage/testdata/di/BillingService.java)** — An interface with a single `bill()` method, following the dependency-inversion principle.
- **[`BillingServiceImpl`](src/main/java/com/optage/testdata/di/BillingServiceImpl.java)** — The concrete (currently no-op) implementation.
- **[`StatelessBeanExample`](src/main/java/com/optage/testdata/di/StatelessBeanExample.java)** — A `@Stateless` EJB session bean that `@Inject`s `BillingService` and delegates to it in its `business()` method.

This sub-module appears to serve as a **reference implementation** for understanding DI wiring in a Jakarta EE environment. It is exercised by `App.main()`, making it part of the end-to-end test coverage.

### How the Sub-modules Relate

The sub-modules are not independent silos — they form a dependency graph where `reflection` and `di` are consumers, and `targets` and `util` are fixtures consumed by them:

```mermaid
flowchart LR
    APP["App - Main Entry"] -->|executes| REFLECT["reflection"]
    APP -->|uses| DI["di"]
    REFLECT -->|uses| TARGETS["targets"]
    REFLECT -->|uses| UTIL["util"]
    DI -->|depends on| TARGETS["targets"]
```

`reflection` is the largest sub-module and the primary driver of the test-data package. It loads `ReflectTarget` from `targets` via multiple reflection strategies, delegates to `JBSbatCheckUtil` from `util`, and exercises the `targets` rule stubs (`EmailRule`, `SmsRule`) as type fixtures. The `di` sub-module is conceptually independent but shares the `targets` module as a common fixture.

## Key Patterns and Architecture

### Convention-over-discovery for test harnesses

All reflection classes in the `reflection` sub-module follow the same pattern: a single `run()` method. This convention enables a test harness to discover and execute all `run()` methods via reflection or classpath scanning without hard-coding class names. It is a lightweight form of convention-over-configuration.

### Reflection as a first-class test concern

The `reflection` sub-module deliberately exercises multiple reflection APIs — `Class.forName()`, `newInstance()`, `getDeclaredMethod()`, and `Method.invoke()` — to ensure the static analysis engine can track each pattern. The pairing of `ReflectionForNameConstant` with `ReflectionForNameLiteral` is especially instructive: the two classes are identical except for how the class name is supplied (constant vs. literal), testing the analyzer's ability to resolve both forms.

The `XmlFactoryFalsePositive` class demonstrates an important meta-pattern: **testing for non-detections**. The static analyzer might flag any `newInstance()` factory call as a potential security risk; this class provides a known-safe pattern to verify the analyzer does not over-report.

### Stub-for-testing design

The `targets` sub-module embodies a **stub-for-testing** pattern: classes with empty method bodies that exist solely to provide concrete types for reflection and integration tests. The only exception is `ReflectTarget`, which has non-trivial behavior and serves as the actively exercised class. This separation lets the test suite exercise both reflection-based dispatch (where the stubs suffice) and direct invocation (where `ReflectTarget` is needed).

### Dependency inversion in DI

The `di` sub-module follows a classic Java EE dependency-inversion pattern: `StatelessBeanExample` depends on the `BillingService` interface, not the concrete `BillingServiceImpl`. The CDI container wires them together at deployment time. This pattern is standard enterprise architecture, enabling testability (mocking the interface) and extensibility (adding new implementations).

### Data flow summary

```mermaid
flowchart TD
    subgraph REFLECT["com.optage.testdata.reflection"]
        DFI["DispatchFrameworkInvoke"]
        RFC["ReflectionForNameConstant"]
        RFL["ReflectionForNameLiteral"]
        RIC["ReflectionInvokeConstant"]
        XFP["XmlFactoryFalsePositive"]
    end
    subgraph TARGETS["com.optage.testdata.targets"]
        RT["ReflectTarget"]
        ER["EmailRule"]
        SR["SmsRule"]
    end
    subgraph UTIL["com.optage.testdata.util"]
        JBU["JBSbatCheckUtil"]
    end
    DFI -->|"invoke(ctx, rules)"| JBU
    RFC -->|"Class.forName + newInstance"| RT
    RFL -->|"Class.forName + newInstance"| RT
    RIC -->|"getDeclaredMethod + invoke"| RT
    RFC -. "target type" .- ER
    RFC -. "target type" .- SR
```

## Dependencies and Integration

### Internal package dependencies

| Consuming package | Consumed package | Nature |
|---|---|---|
| `reflection` | `targets` | Loads `ReflectTarget` via `Class.forName` and `getDeclaredMethod`; references `EmailRule` and `SmsRule` as type fixtures |
| `reflection` | `util` | Delegates to `JBSbatCheckUtil.invoke()` |
| `di` | `targets` | Appears to depend on `targets` for rule-related types |

### Entry point

[`App`](src/main/java/com/optage/testdata/App.java) is the single entry point. Its `main()` method exercises all five reflection harnesses and the DI consumer, making it the natural end-to-end test and the primary way the test-data package is validated.

### External dependencies

- **Jakarta EE APIs** (`javax.ejb.Stateless`, `javax.inject.Inject`) — used only by the `di` sub-module.
- **Standard JDK APIs** (`java.lang.reflect.*`, `javax.xml.parsers.SAXParserFactory`) — used by `reflection` and `XmlFactoryFalsePositive`.
- No external libraries or third-party dependencies are declared.

## Notes for Developers

- **This is test data, not production code.** The `com.optage.testdata` package name is a strong signal: these classes exist to feed a static analysis engine or test harness. Do not assume they contain production-ready logic.
- **Empty method bodies are intentional.** `BillingServiceImpl.bill()`, `EmailRule.check()`, `SmsRule.check()`, and `JBSbatCheckUtil.invoke()` are all empty or near-empty by design. They are type fixtures and stubs.
- **`newInstance()` is deprecated.** Several classes use `Class.newInstance()`, which has been deprecated since Java 9. This is intentional for test coverage of legacy code paths — do not rewrite to `getConstructor().newInstance()` unless the static analyzer rules require it.
- **Constants vs. literals matter for static analysis.** The paired classes `ReflectionForNameConstant` and `ReflectionForNameLiteral` exist to test that the analyzer handles both resolved constant references and literal strings when tracking `Class.forName()` targets. Preserving this distinction is important.
- **`XmlFactoryFalsePositive` is a no-op.** It configures a `SAXParserFactory` but never uses it to build a parser. The class only needs to exercise the instantiation and setter to verify the analyzer does not flag it as a security risk.
- **`ReflectTarget` is the only class with real behavior.** Its `hello()` method is the only non-empty method body across the `targets` sub-module, and it is the primary class actively consumed by the `run` module.
- **`ReflectionInvokeConstant` uses `getDeclaredMethod` (not `getMethod`).** This means it can find methods regardless of visibility — useful for testing analyzer behavior around private or protected methods.
- **Extending `targets`:** When adding new rule types, ensure they follow the same convention — a public no-arg constructor and a `check()` method — so that `JBSbatCheckUtil.invoke()` can resolve and dispatch to them by string name.